SMSWhatsAppVoiceVideoAPIIntegrationRelease NotesFAQs
Guides
Contact UsKaleyra.io Sign InSupport

Click to Call API

API to perform Click to Call using the POST Method.

Suggest Edits

Description

Kaleyra.io provides a Click to Call API, through which one can initiate the outgoing calls and connect two numbers over the bridge number. In this API 'from' number will be called first and then the 'to' number. Both the calls happen via the 'bridge' number.

Base URL

<https://api.kaleyra.io/v1/><SID>

To initiate Click to Call, follow the below steps:

  1. Signup or Login to Kaleyra.io and create your API key

Before you get started, sign up at Kaleyra.io for free and Create an API Key. To view the API Key and the SID, see View API Key and SID.

  1. API command to initiate Click to Call

This section houses the following topics:

Request Format

To initiate Click to Call, use the /messages endpoints.

curl -X POST '<URL>/v1/<SID>/voice/click-to-call' \
		 -H 'Content-Type: <CONTENT_TYPE>' \
		 -H 'api-key: <API_KEY>' \
		 -d 'from=<FROM_NUMBER>' \
		 -d 'to=<TO_NUMBER>' \
		 -d 'bridge=<BRIDGE>' \
		 -d 'prefix=<PREFIX>' \
		 -d 'retry=<RETRY_COUNT>' \
		 -d 'dlrurl=<DLRURL>' \
		 -d 'time=<TIME>' \
		 -d 'callback=<CALLBACK>'

📘

Note:

Ensure to replace the parameter values with the proper inputs in the above code.

Parameters and Data Types

Below is the list of parameters and data types used:

ParameterData TypeDescriptionExample/FormatIs mandatory?
SIDStringAccount SID (Security Identifier). Generated by Kaleyra.io while creating an API key.HXEPXXXXXX1USTrue
CONTENT_TYPEStringIndicates the format of the content the API will be processing.application/x-www-form-urlencodedTrue
API_KEYAlphanumericAPI key generated from Kaleyra.io accountAxxxxxxxxxxxxxxxxxxxxxxxxxxxx3True
FROM_NUMBERNumericFirst number to be dialed.13236xxxxx7True
TO_NUMBERNumericSecond number to be dialed.13236xxxxx7True
BRIDGENumericThe DID number to be used for originating the call, should be an Active subscribed number.
The number must contain the format as Country Code followed by Mobile Number.		13236xxxxx7False
PREFIXNumericOptional prefix applied to "To", "From" & "Bridge" if already not given. Length is 1 to 4 digits.1False
RETRY_COUNTNumeric / JSONNumber of retries in case the call fails to connect.
Default value is 0.
Max value is 2, value greater than 2 will be considered 2.

Valid values for 'status' are CONGESTION, FAILED, NOANSWER, BUSY, and CHANUNAVAIL.		Numeric Format
2
Format 2
{
{"count":2, "status":["CONGESTION", "FAILED"]},
{"count":2,"status":["NOANSWER", "BUSY"]}
}		False
DLRURLHTTP URLURL callback for delivery reports.

For more information on DRLURL, refer to the below link:
https://developers.kaleyra.io/docs/dynamic-variable-for-dlrurl		https://webhook.site/2c2xxxxxxx-xxxxx-xxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxx?call_id={id}&ivr_id={flow_id}&ring_time={ringtime}False
TIMEPHP atomSpecifies the call schedule time.
The call schedule time should be more than 15 minutes from the current time."
datetime format: Y-m-d\TH:i:sP."		2009-11-04T19:55:41+05:30False
CALLBACKJSONYou can provide Callback profile ID(s), multiple URL(s) or both.

Only the GET request with replaceable parameters is supported in the case of URL(s).		To know how to use Callback Profiles in Click to Call API refer to Callback Profile in Click to Call API.False

Response Format

This section provides you the success and failure JSON response format for different scenarios.
Refer to the below sections for more information.

Sample Success Response
Sample Failure Response

Sample Success Response

Click to Call success response 

{
    "code": "RBC3007",
    "message": "Submitted Successfully",
    "data": {
        "to": "917XXXXXXXX6",
        "from": "919XXXXXXXX5",
        "bridge": "9180XXXXXXX3"
    },
    "error": {}
}

Click to Call success response with schedule time

{
    "code": "RBC3007",
    "message": "Submitted Successfully",
    "data": {
        "to": "917XXXXXXXX6",
        "from": "919XXXXXXXX6",
        "bridge": "9180XXXXXXX3",
        "time": "2020-05-23T00:59:00+05:30"
    },
    "error": {}
}

Click to Call success response with the prefix 

{
    "code": "RBC3007",
    "message": "Submitted Successfully",
    "data": {
        "to": "77XXXXXXXX",
        "from": "97XXXXXXX6",
        "bridge": "80XXXXXXX3",
        "prefix": "91"
    },
    "error": {}
}

Sample Failure Response

Click to Call failure response with an invalid number (to/from)
If your response fails due to an invalid number, please re-execute the command with a valid to and from number.

{
    "code": "RBC3109",
    "message": "Invalid number",
    "data": [
        "97XXXXXXX6"
    ],
    "error": {
        "scalar": "Invalid number"
    }
}

Click to Call failure response with an invalid bridge
If your response fails due to an invalid bridge, please re-execute the command with a valid bridge number.

{
    "code": "RBC3119",
    "message": "Bridge number not found",
    "data": [
        {
            "to": "917XXXXXXXXX5",
            "from": "91XXXXXXXXX6",
            "bridge": "91XXXXXXXXX3"
        }
    ],
    "error": {
        "scalar": "Bridge number not found"
    }
}

Click to Call failure response with invalid schedule time (min)
If your response fails due to an invalid schedule time, ensure the schedule time has to be a minimum of 15 minutes greater than the current time from now.

{
    "code": "RBC3108",
    "message": "Schedule time has to be 15 min greater from now",
    "data": [
        {
            "to": "91XXXXXXXXXX5",
            "from": "9197XXXXXXX6",
            "bridge": "9180XXXXXXX3",
            "time": "2020-04-23T00:59:00+05:30"
        }
    ],
    "error": {
        "scalar": "Schedule time has to be 15 min greater from now"
    }
}

Click to Call failure response with invalid time (max)
If your response fails due to an invalid schedule time, ensure the schedule time can be a maximum of three months than the current time from now.

{
    "code": "RBC3107",
    "message": "Schedule time can be maximum of 3 months from now",
    "data": [
        {
            "to": "91XXXXXXXXX5",
            "from": "91XXXXXXXXXX6",
            "bridge": "9180XXXX3XXXX3",
            "time": "2020-08-23T00:59:00+05:30",
            "retry": "2"
        }
    ],
    "error": {
        "scalar": "Schedule time can be maximum of 3 months from now"
    }
}

Click to Call failure response with Invalid Inputs and Validation Error
If your response fails due to an invalid input and validation, please re-execute the command with a valid to and from number.

{
    "code": "RBC3004",
    "message": "Invalid Inputs, Validation Error.",
    "data": [
        {
            "apiStartTime": 1591700481.081621
        }
    ],
    "error": {
        "to": "to field has to be filled",
        "from": "from field has to be filled"
    }
}

Sample Request

The following code is a sample request:

curl -X POST '<URL>/v1/<HXEPXXXXXX1US>/voice/click-to-call' \
		 -H 'Content-Type: <application/x-www-form-urlencoded>' \
		 -H 'api-key: <AXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX3>' \
		 -d 'from=<13236xxxxx7>' \
		 -d 'to=<13236xxxxx7>' \
		 -d 'bridge=<13236xxxxx7>' \
		 -d 'prefix=<1>' \
		 -d 'retry=<1>' \
		 -d 'dlrurl=<https://webhook.site/2c2xxxxxxx-xxxxx-xxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxx?call_id={id}&ivr_id={flow_id}&ring_time={ringtime}>' \
		 -d 'time=<2009-11-04T19:55:41+05:30>' \
		 -d 'callback=<https://webhook.site/2c2xxxxxxx-xxxxx-xxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxx?caller=%7B%7Bcaller%7D%7D>'

HTTP Status Code and Response Code

For more information regarding the HTTP Status Codes and Response Codes, refer to Voice Error Codes.

Updated about 1 year ago