Click to Call API

API to perform Click to Call using the POST Method.

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/

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.

2. 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 'https://api.kaleyra.io/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 Variables

Below is the list of parameters and variables used:

Parameter

Variable

Description

Example/Format

Is mandatory?

SID

String

Account SID (Security Identifier). Generated by Kaleyra.io while creating an API key.

HXEPXXXXXX1US

True

CONTENT_TYPE

String

Indicates the format of the content the API will be processing.

application/x-www-form-urlencoded

True

API_KEY

Alphanumeric

API key generated from Kaleyra.io account

Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3

True

FROM_NUMBER

Numeric

First number to be dialed.

13236xxxxx7

True

TO_NUMBER

Numeric

Second number to be dialed.

13236xxxxx7

True

BRIDGE

Numeric

The 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.

13236xxxxx7

False

PREFIX

Numeric

Optional prefix applied to "To", "From" & "Bridge" if already not given. Length is 1 to 4 digits.

1

False

RETRY_COUNT

Numeric / JSON

Number 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

DLRURL

HTTP URL

URL 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

TIME

PHP atom

Specifies 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:30

False

CALLBACK

JSON

You can provide Callback profile ID(s), multiple URL(s) or both.

Only the GET request with replaceable params is supported in the case of URL(s).

{"from_call_start":{"callback_profile":[],"url":[]},

"to_call_start":{"callback_profile":[],"url":[]},

"from_call_answer":{"callback_profile":[],"url":[]},

"to_call_answer":{"callback_profile":[],"url":[]},

"call_end":{"callback_profile":[],"url":[]}}

Notes:

  1. For each event type,
    the upper limit for callback_profile ID's/URL's is 10 for each event type.
  2. The keys in the JSON are case insensitive.
  3. One or more callback events can be configured among the following:
    To_call_start, From_call_start, To_call_answer, From_call_asnwer, and call_end.

{
"from_call_start":{
"callback_profile":[
"SG_xxxx"
], "url":[ "https://webhook.site/2c2xxxx?caller={{caller}}"
]
},

"from_call_answer":{
"callback_profile":[
"SG_SG_xxxx"
], "url":[ "https://webhook.site//2c2xxxxxxxxxxx?caller={{caller}}"
]
},

"to_call_start":{
"callback_profile":[
"SG_SG_xxxxxxx"
], "url":[ "https://webhook.site//2c2xxxxxxxxxxx?caller={{caller}}"
]
},

"to_call_answer":{
"callback_profile":[
"SG_SG_xxxxxxxx"
], "url":[ "https://webhook.site//2c2xxxxxxxxx?caller={{caller}}"
]
},

"call_end":{
"callback_profile":[
"SG_SG_xxxxxxx"
], "url":[ "https://webhook.site//2c2xxxxxxxx?caller={{caller}}",

  ]

}
}

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 'https://api.kaleyra.io/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

The below table provides information about the HTTP status code for the Click to Call API.

HTTP Status

Description

202

The successful request has been accepted.

400

Invalid input, validation failed.

Response Code

The below table provides information about the response codes and their description.

Code

Description

RBC3007

Submitted Successfully.

RBC3109

Invalid number.

RBC3119

Bridge number not found.

RBC3108

Schedule time has to be 15 minutes greater from now.

RBC3107

Schedule time can be a maximum of 3 months from now.

RBC3004

Invalid Inputs, Validation Error.


Did this page help you?