Trigger Flow using Outgoing Call

Outgoing call flows allow you to connect to your customers through interactive voice calls. When customers receive the calls, they will experience the Interactive Voice Response (IVR) configured.

To trigger an outbound call flow, create a flow in Flowbuilder. Use the FLow ID as a target in the Outbound Calling API to trigger the API. Customers answering the call will hear IVR.

📘

Note:

Only one IVR ID can be configured per Outbound Calling API.

The outbound call flow can be triggered using the following steps:

  1. Get Flow ID from Kaleyra Flowbuilder
  2. Trigger Outgoing Call Flow through API

Get Flow ID

You can view and copy the Flow ID from Flowbuilder under existing flows.

To view and copy the Flow ID, perform the following steps:

  1. Sign in to your Kaleyra.io account.
  2. Navigate to Flow Builder in the left navigation bar.
1366
  1. Scroll to the Existing Flows section.
1366
  1. Click the copy icon next to Flow ID. The Flow ID gets copied to the clipboard.

📘

Notes:

  • Flows can be filtered based on the following options:
    • Webhook
    • Voice
    • Published
    • Paused
    • Draft
  • You can search the flow from the list of existing flows using the Search field in top-right of the Existing Flows section.

Trigger Outgoing Call Flow

Base URL

  • SG region - https://api.ap.kaleyra.io/
  • IN region - https://api.in.kaleyra.io/
  • EU region - https://api.eu.kaleyra.io/

Prerequisite

Request Format

curl -X POST '<URL>/v1/<SID>/voice/outbound' \
		 -H 'Content-Type: <CONTENT_TYPE>' \
		 -H 'api-key: <API_KEY>' \
		 -d 'to=<TO_NUMBER>' \
		 -d 'bridge=<BRIDGE>' \
		 -d 'target=<TARGET>'

📘

Note:

Outbound Calling API also supports other parameters, for more details on other supported parameters, see Outbound Calling API Request Format.

Sample Request Format

curl -X POST 'https://api.kaleyra.xx/v1/HXIN169510844XXX/voice/outbound' \
		 -H 'Content-Type: application/x-www-form-urlencoded' \
		 -H 'api-key: Aaf0dff8cd58cf99cba958f8941d3XXX0' \
		 -d 'to=+18830907XXX' \
		 -d 'bridge=+13236789XXX' \
		 -d 'target=SG_8b37a0d3-1c97-47ac-99a5-380969XXXXb'

Parameters and Data Types

Following is the list of parameters and data types required for outgoing call flows:

ParameterData TypeDescriptionExamples/Numeric FormatMandatory
<SID>StringAccount SID (Security Identifier).HXIN169510844XXXYes
<CONTENT_TYPE>StringThe format in which the data is sent.application/x-www-form-urlencodedYes
<API_KEY>StringAPI key generated from Kaleyra.io account.Aaf0dff8cd58cf99cba958f8941d3XXX0Yes
<TO_NUMBER>StringThe 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.
+18830907XXXYes
<BRIDGE>IntegerThe 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.
+13236789XXXYes
<TARGET>ArrayThe message to be played when the receiver(callee) picks up the call.

Valid Format:
Provide the valid Flow ID obtained from the Flow. Only one Flow ID is supported by an Outbound Calling API.
[
{"ivr":[SG_8b37a0d3-1c97-47ac-99a5-380969XXXXb]}
]
Yes

Response Format

This section provides you with the successful JSON response format.

Sample Success Response

Basic outbound response with Flow ID

{
  "code": "RBC3007",
  "message": "Submitted Successfully",
  "data": {
    "to": "+18830907XXX",
    "target": [
      {
        "ivr": ["SG_8b37a0d3-1c97-47ac-99a5-380969XXXXb"]
      }
    ],
    "bridge": "+13236789XXX"
  },
  "error": {}
}

Sample Failure Response

Basic outbound response with an invalid bridge (invalid Flow ID) or (valid FLow ID but not assigned to the organization)

{
  "code": "RBC3115",
  "message": "IVR not found",
  "data": [
    {
      "to": "+18830907XXX",
      "target": [
        {
          "ivr": ["SG_8b37a0d3-1c97-47ac-99a5-380969XXXXb"]
        }
      ],
      "bridge": "+13236789XXX"
    }
  ],
  "error": {
    "scalar": "IVR not found"
  }
}

HTTP Status Code and Response Code

For more information regarding the HTTP Status Codes and Response Codes, refer to Voice Error Codes.