Outbound Calling API

📘
Note:
This feature is currently not available for users registered in the North America (NA) region.

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

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?
`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.	Axxxxxxxxxxxxxxxxxx3	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: en-IN - English (India) en-US - English (US) es-ES** - Spanish 4.it-IT - Italian Note: The language input is case-sensitive. For more information on supported text-to-speech languages, seeSupported Text-to-Speech LanguagesValid speed input: fast* - High speed slow - Slow speed medium - Medium speed x-fast - x-High speed 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. 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
`DELAY`	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. Note*: If you are using delay as well as timeout parameters. Then the expected call start will be the sum of both the values. For example, if the delay value is 23 and the timeout value is 13 then the expected call start execution time will be before 36 seconds.	60	False
`CUSTOM`	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
`INTERVAL`	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 `25` Sample 2: `"retry": "[{"count":"2","interval":"60","status":["CONGESTION","CHANUNAVAIL"]}]"` Sample 3: `"retry": "[{"count":2,"status":["NOANSWER","BUSY","CONGESTION","CHANUNAVAIL","FAILED"],"interval":"60"}]"`	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.