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/

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

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

View Response

{
    "code": "RBC3007",
    "message": "Submitted Successfully",
    "data": {
        "to": "919740149106",
        "target": {"message":{"language":"en-IN", "speed":"medium", "text":"your message"}},
        "bridge": "918043135533"
    },
    "error": {}
}
{
    "code": "RBC3109",
    "message": "Invalid number",
    "data": [
        "9740149106"
    ],
    "error": {
        "scalar": "Invalid number"
    }
}
{
    "code": "RBC3108",
    "message": "Schedule time has to be 15 min greater from now",
    "data": [
        {
            "to": "919740149106",
            "target": {"message":{"language":"en-IN", "speed":"medium", "text":"your message"}},
            "bridge": "918043135533",
            "time": "2020-04-13T12:45:00+05:30"
        }
    ],
    "error": {
        "scalar": "Schedule time has to be 15 min greater from now"
    }
}

Did this page help you?