Outbound Calling API
API to perform outbound calls.
Kaleyra.io offers an API to make outbound (outgoing) voice calls. You can initiate the outbound voice call using the Direct Inward Dialing (DID) number subscribed from the Kaleyra.io account. The DID number can be passed as a value for the 'bridge' parameter in the API to initiate the call. You can also configure the number of retries, call schedules, target, and etc for these voice calls.
Base URL
<https://api.kaleyra.io/v1/><SID>
To make your first outbound voice call, follow the below steps:
- Signup or Login to Kaleyra.io and Create Your API Key
Before you get started, sign up in Kaleyra.io for free and Create an API Key. To view the API Key and the SID, see View API Key and SID.
- API Command to Make Your First Outbound Voice Call
This section houses the following topics:
- Request Format
- Parameters and Variables
- Response Format
- Sample Request
- HTTP Status Code and Response Code
Request Format
To make your first outbound voice call, use the following /outbound endpoint.
curl -X POST '<URL>/v1/<SID>/voice/outbound' \
-H 'Content-Type: <CONTENT_TYPE>' \
-H 'api-key: <API_KEY>' \
-d 'to=<TO_NUMBER>' \
-d 'retry=<RETRY_COUNT>' \
-d 'bridge=<BRIDGE>' \
-d 'prefix=<PREFIX>' \
-d 'target=<TARGET>' \
-d 'dlrurl=<DLRURL>' \
-d 'time=<TIME>' \
-d 'timeout=<TIMEOUT>' \
-d 'callback=<CALLBACK>'\
-d 'delay=<DELAY>' \
-d 'custom=<CUSTOM>' \
-d 'interval=<INTERVAL>'
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 supported:
Parameter | Data Type | Description | Examples/Numeric Format | Mandatory? |
---|---|---|---|---|
| String | Account SID (Security Identifier). | HXXXXXXX071US | True |
| String | The format in which the data is sent. | application/x-www-form-urlencoded | True |
| Alphanumeric | API key generated from Kaleyra.io account. | Axxxxxxxxxxxxxxxxxx3 | True |
| Integer | The recipient’s number(callee). The number must contain the country code, if not already given in the prefix parameter. You have the option to make maximum outbound voice calls up to 100 numbers. To make multiple outbound calls, separate the numbers using the (,) comma. | +13236xxxxx7 | True |
| Integer/JSON. | The number of retries that can be made until a timeout is reached if the initial call fails to connect.
| 2 or { | False |
| Integer | The DID number to be used for originating the call, should be an Active subscribed number. | +13236xxxxx7 | False |
| Integer | Optional prefix applied to 'TO' & 'BRIDGE' if already not given. Length is 1 to 4 digits. | Prefix supports both +1 and 1 | False |
| Array | The message to be played when the receiver(callee) picks up the call.
Format 2: Provide the valid sound id obtained from Sound Manager. Format 3. Provide text input with valid speech rate and language. Format 4: Combination of Sound and Message. Provide the valid Sound ID obtained from the Sounder Manager and valid text with speech rate and language.
| Format 1 Format 2 Format 3 Format 4
| True |
| HTTP URL | DLR URL enables you to receive callback data such as call duration, call start time, call end time, call charges, etc when an outbound call is answered. | https://webhook.site/55XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX0fe?rev=id&rev1=ivruuid&rev2=ringtime | False |
| PHP atom | Schedule the outbound voice call. Time Format: Y-m-d\TH:i:sP. Scheduled call time must be between 15 minutes to 90 days from the current time. | 2009-11-04T19:55:41+05:30 | False |
| Numeric/JSON | Timeout configuration defines the timeout settings of the outbound call based on requirements.
| Numeric Format Format 2 Format 3 Format 4
| False |
| JSON | Callback Profiles are used to trigger the endpoints and receive callback data at the configured callback event. Only the GET request with replaceable parameters is supported in the case of URL(s). | To know how to use Callback Profiles in Outbound Calling API refer to Callback Profile in Outbound Calling API. | False |
| Numeric | Defines the delay in seconds after which the call should initiate once the request is submitted. Delay time must be between 0 to 900 seconds. Any input higher or lower than the capped range will be wrapped to 900 or 0, whichever is closer.
| 60 | False |
| Alphanumeric | Allows you to provide your own custom reference ID. For example, if you are making multiple outbound API requests, you can provide different reference IDs. It helps you in identifying the outbound calls using custom reference IDs, instead of call IDs by Kaleyra. Custom reference ID has a maximum limit of 100 characters. | TxxxxT | False |
| Numeric | Allows you to add the interval in seconds after which the retry will be attempted. You can use the interval either as a standalone parameter or with retry. When you use an interval with a retry parameter, it will re-attempt the call based on the provided interval. The interval range is valid from 15 to 60 seconds. Any interval higher or lower than the capped range will be wrapped to 60 or 15, whichever is closer. Sample 2: Retry format with numeric retry and Interval. Sample 3: Retry format with JSON retry and Interval. | Numeric Format Sample 2: Sample 3:
| 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
Basic outbound response with IVR UUID
{
"code": "RBC3007",
"message": "Submitted Successfully",
"data": {
"to": "+13236xxxxx7",
"target": [
{
"ivr": ["SG_5XXXXXX6-eXX4-4XXa-8XXd-eXXXXXXXXXXf"]
}
],
"bridge": "+13236xxxxx7"
},
"error": {}
}
Basic outbound response with sound
{
"code": "RBC3007",
"message": "Submitted Successfully",
"data": {
"to": "+13236xxxxx7",
"bridge": "+13236xxxxx7",
"target": [
{
"sound": [13,34,38]
}
]
},
"error": {}
}
Basic outbound response with a messages
{
"code": "RBC3007",
"message": "Submitted Successfully",
"data": {
"to": "+13236xxxxx7",
"bridge": "+13236xxxxx7",
"target": [
{
"message": {
"text": "your message here"
}
},
{
"message": {
"text": "your second message here"
}
}
]
},
"error": {}
}
Basic outbound response with scheduled time
{
"code": "RBC3007",
"message": "Submitted Successfully",
"data": {
"to": "+13236xxxxx7",
"target": [
{
"ivr": ["SG_5XXXXXX6-eXX4-4XXa-8XXd-eXXXXXXXXXXf"]
}
],
"bridge": "+13236xxxxx7",
"time": "2020-05-13T12:45:00+05:30"
},
"error": {}
}
Basic outbound response with call_back, retry(JSON), source, campaign_name
{
"code": "RBC3007",
"message": "Submitted Successfully",
"data": {
"to": "+13236xxxxx7",
"target": [
{
"ivr": ["SG_5XXXXXX6-eXX4-4XXa-8XXd-eXXXXXXXXXXf"]
}
],
"bridge": "+13236xxxxx7",
"campaign_name": "TestCampaign",
"dlrurl": "https://webhook.site/5XXXXXX6-8XX1-4XXd-bXX3-bXXXXXXXXXXf?rev=id&rev1=ivruuid",
"source": "API",
"retry": "[{\"count\":2,\"status\":[\"congestion\", \"chanunavail\"]},\n{\"count\":2,\"status\":[\"noanswer\", \"busy\"]},\n{\"count\":1, \"status\": []},\n{\"count\": 2, \"status\": [\"answer\"]}\n]"
},
"error": {}
}
Basic outbound response with a prefix
{
"code": "RBC3007",
"message": "Submitted Successfully",
"data": {
"to": "+13236xxxxx7",
"target": [
{
"ivr": ["SG_5XXXXXX6-eXX4-4XXa-8XXd-eXXXXXXXXXXf"]
}
],
"bridge": "+13236xxxxx7",
"prefix": "+1"
},
"error": {}
}
Sample Failure Response
API Key is not available
{
"code": "RBC201",
"message": "API key does not exist",
"data": [],
"error": {
"error": "API key does not exist"
}
}
Body parameters are not available
{
"code": "RBC3004",
"message": "Invalid Inputs, Validation Error.",
"data": [
{
"apiStartTime": 1591700481.081621
}
],
"error": {
"to": "to field has to be filled",
"target": "target field has to be filled"
}
}
Basic outbound response with an invalid number (receiver)
{
"code": "RBC3109",
"message": "Invalid number",
"data": [
"+13236xxxxx7"
],
"error": {
"scalar": "Invalid number"
}
}
Basic outbound response with an invalid bridge (invalid bridge number) or (valid bridge number but not assigned to the organization)
{
"code": "RBC3119",
"message": "Bridge number not found",
"data": [
{
"to": "+13236xxxxx7",
"target": [
{
"ivr": ["SG_5XXXXXX6-eXX4-4XXa-8XXd-eXXXXXXXXXXf"]
}
],
"bridge": "+13236xxxxx7"
}
],
"error": {
"scalar": "Bridge number not found"
}
}
Basic outbound response with invalid time (in minutes)
{
"code": "RBC3108",
"message": "Schedule time has to be 15 min greater from now",
"data": [
{
"to": "+13236xxxxx7",
"target": [
{
"ivr": ["SG_5XXXXXX6-eXX4-4XXa-8XXd-eXXXXXXXXXXf"]
}
],
"bridge": "+13236xxxxx7",
"campaign_name": "test",
"time": "2020-04-13T12:45:00+05:30"
}
],
"error": {
"scalar": "Schedule time has to be 15 min greater from now"
}
}
Basic outbound response with an invalid bridge (invalid IVR UUID) or (valid IVR UUID but not assigned to the organization)
{
"code": "RBC3115",
"message": "IVR not found",
"data": [
{
"to": "+13236xxxxx7",
"target": [
{
"ivr": ["SG_5XXXXXX6-eXX4-4XXa-8XXd-eXXXXXXXXXXf"]
}
],
"bridge": "+13236xxxxx7"
}
],
"error": {
"scalar": "IVR not found"
}
}
Basic outbound response with an invalid bridge (invalid sound ID(s) or (valid IVR UUID(s) but not assigned to the organization)
{
"code": "RBC3114",
"message": "Sound file(s) not found",
"data": [
{
"to": "+13236xxxxx7",
"target": [
{
"sound": [13,34]
}
],
"bridge": "+13236xxxxx7"
}
],
"error": {
"scalar": "Sound file(s) not found"
}
}
Sample Request
The following code is a sample request:
curl -X POST '<URL>/v1/HXXXXXXX071US/voice/outbound' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
-d 'to=+13236xxxxx7' \
-d 'retry_count={"count":2}' \
-d 'bridge=+13236xxxxx7' \
-d 'prefix=1' \
-d 'target=[{"ivr":[SG_5XXXXXX6-eXX4-4XXa-8XXd-eXXXXXXXXXXf]}]' \
-d 'dlrurl=https://webhook.site/55XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX0fe?rev=id&rev1=ivruuid&rev2=ringtime' \
-d 'time=2021-01-04T19:55:41+05:30' \
-d 'timeout=[60]' \
-d 'callback={"call_start":{"callback_profile":["SG_cXXXXXX9-bXX4-4XX9-aXXf-27XXXXXXXX69"],"url":["https://webhook.site/2cXXXX89-6XX0-4XX7-bXX9-aeXXXXXXXX31?caller={{caller}}"]}}'\
-d 'delay=60' \
-d 'custom=TxxxxT' \
-d 'interval=<20>'
HTTP Status Code and Response Code
For more information regarding the HTTP Status Codes and Response Codes, refer to Voice Error Codes.
Updated 10 days ago