Outbound Multicast API Documentation

Background

The Central Outbound Multicast API allows you to send outbound communications to your customers on single or multiple channels including Calls, SMS and Email.

The API will log a request in one of the workflows created in your admin account. The request will be picked subsequently and executed.

Pre Requisites

1. IP Whitelisting: IP must be whitelisted in the admin account.

2. Checksum Check: Two request must have at-least one byte change in it. If two requests are same, you’ll get Checksum Repeated error.

Outbound Create Request API

Use this API to initiate an Outbound Flow request. In your Outbound Multicast Flow, you can configure your flow containing Call, SMS, Email or any combination of the same!

Before sending a request, make sure to whitelist the IP through which you send the API request in the whitelist section.

1. For Bulk Requests - Where you need high through-put or uploading a large data.

   1. API End Point: https://central-api.phonon.io/kairos-apis/outbound/create

   2. Rate Limit: 30k per minute

2. For Real Time Requests - Low through-put but instant connect and faster response.

   1. API End Point: https://central.phonon.io/kairos-apis/outbound/create

   2. Rate Limit: 500 per minute

Request Parameters:

Payload Schema:

{
	"api-version": "1.0", // Fixed
	"security-id": "<64 character alphanumeric>",
	"flow-id": "<8 character alphanumeric>",
	"calls": [
		{
			"client-identifier": "<identifier, callback parameter>",
			"start-time": "<ISO-8601 Format YYYY-MM-DDTHH:MM:SS+05:30",
			"contact-numbers": [
				"918000XXXXXX",
				"918100XXXXXX",
				"<Other Alternate Numbers>"
			],
			"keys": [
				{
					"name": "$flow.key.Name",
					"value": "Abhinandan"
				},
				{
					"name": "$flow.key.Language",
					"value": "English"
				},
				{
					// Other flow variables
				}
			]
		},
		{
			// 2nd Call to be place
		}
	]
}

Sample Payload

{
	"api-version": "1.0",
	"security-id": "a0095e7ac42205cb1388d7ac0d2db4afad1b5b2304907a27a6154bf93253088c",
	"flow-id": "wruHzoCK",
	"calls": [
		{
			"client-identifier": "AcmeBankCampaign_001",
			"start-time": "2021-06-29T09:42:00+05:30",
			"contact-numbers": [
				"916262772728"
			],
			"keys": [
				{
					"name": "$flow.key.LeadID",
					"value": "130586000000165414"
				},
				{
					"name": "$flow.key.token",
					"value": "English"
				}
			]
		}
	]
}

Request Parameters Explanation:

As text:

1. api-version: Use 1.0 to use the IN PRODUCTION. This is fixed value.

2. security-id: Get the security ID from the ‘Edit Flow’ page of any Outbound Flow

3. flow-id: Get the 8 characters' alphanumeric Flow ID from the ‘Edit Flow’ page of any Outbound Flow

4. calls: Array. Each element in the array represents one call. You can have up to 500 calls in one request.

   1. client-identifier: Callback variable to uniquely represent this request.

   2. start-time: ISO-8601 Timestamp. The format is YYYY-MM-DDTHH:MM:SS+05:30. The date cannot be from the past. If the time is of past (and the date is today) the flow will be initiated immediately.

   3. contact-numbers: Array. Mobile numbers of the customer. You can provide alternate numbers of a customer and calls will be initiated to each number until one is connected in one attempt.

   4. keys: Array of Flow Variables. There’s no limit on how many flow variables can be provided.

      1. "name": "$flow.key.<variable>": Name of flow variable.

      2. "value": "Abhinandan": Value of the above flow variable.

Response:

1. Successful Response:
   Status Code: 200

   {
     "api-response-code": 200,
     "api-response-message": "Success",
     "request-id": "c46e46f4-dc58-4839-9483-f7dd9aac28a0",
     "call-details": [
       {
         "client-identifier": "2021-04-28T03:48:07.110Z",
         "phonon-uuid": "501c78ee-8d06-498e-8952-fce3495f326b"
       }
     ]
   }

a. Request ID: Unique Identifier for the whole request.

b. Phonon UUID: Unique Identifier for each call.

2. Important Error Response:

{
  "api-response-code": 500/401/201/202/301,
  "api-response-message": "Failure/IP Not Whitelisted/Checksum Repeated/Invalid Security ID/Invalid Flow ID",
}

1. IP Not Whitelisted 401: Please whitelist your IP in the Whitelist section.

2. Checksum Repeated 201: You can trigger the same API payload more than once. Please change at least one parameter. (Date-time, client-identifier, etc.)

3. Invalid Security ID 202: The security ID is invalid. Please check the endpoint and security ID.

4. Invalid Flow ID 301: Flow ID is invalid. Please check the endpoint and Flow ID.

5. Failure 500: Any Failure scenario.

3. All Error Codes:

FAQs:

How to get the status of the request?

You can check the request for the API by:

1. Using the Pull API - Using Phonon UUID | API Documentation using Phonon UUID or Request ID to pull the status of the request.

2. Using End Call Webhook Push - which can push various details after every workflow (call / sms / email) execution to an external webhook end point.

3. Using EOD or On Demand Reports.

4. Using Summary Dashboards.