API to perform outbound calls using the POST Method.
Description
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
To make your first outbound voice call, follow the below steps:
1. 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.
2. 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
- Response Code
Request Format
To make your first outbound voice call, use the following /outbound endpoint.
curl -X POST 'https://api.kaleyra.io/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>'
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 supported:
Parameter | Variable | Description | Examples/Numeric Format | Mandatory? |
---|---|---|---|---|
SID | String | Account SID (Security Identifier). | HXXXXXXX071US | True |
CONTENT_TYPE | String | The format in which the data is sent. | application/x-www-form-urlencoded | True |
API_KEY | Alphanumeric | API key generated from Kaleyra.io account. | Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3 | True |
TO_NUMBER | 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 |
RETRY_COUNT | Integer/JSON | The number of retries that can be made until a timeout is reached if the initial call fails to connect. The default retry count is 0 and the maximum count is 2. Any value higher than 2 will be considered 2. You can also provide the statuses for which this retry shall be applicable. Available statuses are- {the list of statuses}. Valid values for 'status' are: CONGESTION, FAILED, NOANSWER, BUSY, and CHANUNAVAIL. You can use more than one status. | 2 or { {"count":2, "status":["CONGESTION", "FAILED"]} } | False |
BRIDGE | Integer | 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 | Integer | Optional prefix applied to 'TO' & 'BRIDGE' if already not given. Length is 1 to 4 digits. | Prefix supports both +1 and 1 | False |
TARGET | Array | The message to be played when the receiver(callee) picks up the call. Valid Formats: Format 1: Provide the valid Flow ID obtained from the Flowbuilder. 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. Valid language inputs: 1. en-IN - English (India) 2. en-US - English (US) 3. es-ES - Spanish 4. it-IT - Italian Note: The language input is case-sensitive. Valid speed input: 1. fast - High speed 2. slow - Slow speed 3. medium - Medium speed 4. x-fast - x-High speed 5. x-slow - x-Slow speed Note The speed input is case sensitive. | Format 1 [ {"ivr":[SG_5XXXXXX6-eXX4-4XXa-8XXd-eXXXXXXXXXXf]} ] Format 2 [ {"sound":[1,2,3,4]} ] Format 3 [ {"message":{"language":"en-US", "speed":"medium", "text":"<your message here>"}} ] Format 4 [ {"sound":[1,2]}, {"message": {"language":"en-US", "speed":"medium", "text":"<your second message here>"}} ] | True |
DLRURL | 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. You can configure the URL based on your need using the defined Dynamic Variables for DLRURL | https://webhook.site/55XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX0fe?rev=id&rev1=ivruuid&rev2=ringtime | False |
TIME | 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 |
TIMEOUT | Numeric/JSON | Timeout configuration defines the timeout settings of the outbound call based on requirements. Valid Timeout Format 1 - Numeric Format - Provide the timeout for an outbound call in seconds, the numeric timeout validation ranges from 30 seconds to 48 hours. Format 2 - Timeout outbound call can be scheduled for specific duration. For example, timeout outbound call can be scheduled between 10:00 hrs and ends at 15:00 hrs on that particular day. Format 3 - You can configure timeout outbound call in multiple time slots. For example, timeout call can be scheduled between 10:00 hrs and ends at 14:00 hrs, again the can be re-scheduled between 17:00 hrs and ends at 19:00 hrs on that particular day. Format 4 - You can configure timeout outbound calls for different days with specific time slots. For example, timeout call can be scheduled between 10:00 hrs and ends at 14:00 hrs on Monday and Thursday. Again, the timeout call can be re-scheduled between 19:00 hrs and ends at 20:00 hrs on Tuesday, Wednesday, and Friday. | Numeric Format 60 Format 2 [ {"start_time":"10:00:00", "end_time" : "17:00:00"} ] Format 3 [ {"start_time":"10:00:00", "end_time" : "14:00:00"}, {"start_time":"17:00:00", "end_time" : "19:00:00"} ] Format 4 [ {"start_time":"10:00:00", "end_time" : "14:00:00", "days":["mon", "thu"]}, {"start_time":"19:00:00", "end_time" : "20:00:00", "days":["tue","wed","fri"]} ] | False |
CALLBACK | JSON | Callback Profiles are used to trigger the endpoints and receive callback data at the configured callback event. {"call_start":{"callback_profile":[],"url":[]}, "call_answer":{"callback_profile":[],"url":[]}, "call_end":{"callback_profile":[],"url":[]}} Notes: 1. One or more callback events can be configured among the following call_start, call_answer, and call_end. 2. For each event type, the upper limit for callback_profile ID's/URL's is 10. 3. The keys in the JSON are case insensitive. | { "call_start": { "callback_profile": [ "SG_cXX9-bXX4-4XX9-aXXf-27XX9" ], "url": ["https://webhook.site/2cXX9-6XX0-4XX7-bXX9-aeXX31?caller={{caller}}" ] }, "call_answer": { "callback_profile": [ "SG_96XX3-2XXb-4XX2-9XX3-feXXe" ], "url": ["https://webhook.site/2cXX9-6XX0-4XX7-bXX9-aeXX31?caller={{caller}}" ] }, "call_end": { "callback_profile": [ "SG_f8XX40-fXX8-4XXf-aXX3-c9XXb" ], "url": ["https://webhook.site/2cXX9-6XX0-4XX7-bXX9-aeXX1?caller={{caller}}", "https://webhook.site/2cXX89-6XX0-4XX7-bXX9-aeXX1?callee={callee}" ] } } | 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
If your response fails due to the unavailability of an API Key, please re-execute the command with an API key.
{
"code": "RBC201",
"message": "API key does not exist",
"data": [],
"error": {
"error": "API key does not exist"
}
}
Body parameters are not available
If your response fails due to the unavailability of the body parameters, please re-execute the command providing the body parameters.
{
"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)
If your response fails due to the invalid receiver number, please re-execute the command providing the valid receiver number.
{
"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)
If your response fails due to an invalid bridge (invalid bridge number) or (valid bridge number but not assigned to the organization), please re-execute the command providing a valid bridge.
{
"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)
If your response fails due to the invalid time (lesser than 15 minutes, please re-execute the command providing the valid time (more than 15 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)
If your response fails due to an invalid bridge (invalid IVR UUID) or (valid IVR UUID but not assigned to the organization), please re-execute the command providing a valid bridge.
{
"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)
If your response fails due to an invalid bridge (invalid sound ID(s) or (valid IVR UUID(s) but not assigned to the organization), please re-execute the command providing a valid bridge.
{
"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 'https://api.kaleyra.io/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}}"]}}'
HTTP Status Code
The below table provides information about the HTTP status code you would receive when executing the outbound calling 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. |