EnableX introduced application APIs to create a complex application such as Message Broadcast with minimal or zero codings. Message Broadcast API provides a wrapper API to maintain state and other complex info of multiple ongoing calls, while also gives full control over individual calls made under the application if the developer needs fine-grained control.

Table of Contents

Introduction

EnableX Voice service APIs provide a basic call control such as make or receive a call, detect if it is NOT an automated answering machine, and plays voice/text that is configured/programmed and create a workflow till call disconnect.

Though basic API can fulfill most of the fundamental apps, it requires advanced skills to write a complex program especially when it is required to make a massive number of calls, which is a typical use case in telemarketing applications.

EnableX introduced application APIs to create a complex application such as Message Broadcast with minimal or zero codings. Message Broadcast API provides a wrapper API to maintain state and other complex info of multiple ongoing calls, while also gives full control over individual calls made under the application if the developer needs fine-grained control.

Workflow Explanation

  • Create a JSON structure with the desired phone numbers and stringify it to pass in API
  • Create a new application instance using API https://api.enablex.io/voice/v1/broadcast
    • Pass all required parameters
    • API requires 2 WebHook URLs that will be registered by the application
      • Event URL for returning the state of message broadcast
      • WebHook Url to pass on to the Outbound call that is initiated by the API. This webhook returns you the voice_id of every call.
  • On the application server-side, you can take control of the call-leg through the application instance handle and can call any of the voice service call APIs through MessageBroadcast instance.

Message Broadcast APIs

Create and start Broadcast Instance

This service makes a broadcast call to the configured numbers. The numbers will be passed as a comma-separated value or as a predefined JSON structure. The CLI (Caller Line Identification) for the outbound call is expected to be passed by the developer, as a parameter to the API.

API Route: https://api.enablex.io/voice/v1/broadcast

Request Example: 

POST https://api.enablex.io/voice/v1/broadcast
Authorization: Basic XXXXXXXX
Content-Type: application/json

{
	"application_name": "Message Broadcast for sales",
	"owner_ref": "xyz",
	/* Array of Numbers to be called */
	"broadcast_numbers_array": numbers,
	/* broadcast number as an stringified json array */	
	"broadcast_numbers_json": jsonNumberArray 
	"from": "999999999",
	"action_on_connect": {
		"play": {
			"prompt_ref": "1",
			"text": "Text to Speech Prompt",
			"voice": "Male",
			"language": "en-US"
		}    
	},
	"call_param": {
		"interval_between_retries": 5000,
		"number_of_retries": 3
	},
	"event_url": "http://applicationserver.com:3000/event",
	"call_handler_url": "http://applicationserver.com:3000/event"
}
Key / ObjectDescription
application_nameName of the application such as Message Broadcast for Sales
broadcast_numbers_arrayBroadcast number inputs in array. e.g. [‘Number1’,’Number2’,’Number3’]
broadcast_numbers_jsonBroadcast numbers as stringified json array. e.g. jsonNumberArray =
JSON.stringify([{“phone”: “Number1”}, {“phone”: “Number2”},{“phone”: ”Number3”}])
fromNumber that will be used as a caller Id (CLI)
action_on_connectThis structure will be same as defined in Outbound message in voice API 
event_urlBroadcast will post Initiated and completed event on this URL
call_handler_urlThis handler is passed from broadcast API to internal Outbound API,  and will be a Webhook that will be called on App-Server in a same way that Outbound call is handled and processed

Response: 

{
	“app_instance": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
	”application_name”: “MessageBroadcast for sales”,
	“state”: "success",
	"timestamp": "2020-02-16T10:52:00Z"
}

Error Response: All error responses will follow the standard HTTP error format and error code. The JSON body of the response will highlight exact error that occurred and it’s description. Please see Erro codes here.

https:// 400 Bad request
{
	“application_name": "MessageBroadCast Application Name",
	“state”: "failed",
	“error_description”: “CLI number is not assigned/wrong CLI number” ,
	"timestamp": "2020-02-16T10:52:00Z",
}
https:// 404 Not Found
{
	“app_instance": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
	“state”: "failed",
	“error_description”: “Application Not Found” ,
	"timestamp": "2020-02-16T10:52:00Z"
}
https://  401 Unauthorized
{
	“app_instance": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
	“state”: "failed",
	“error_description”: Not authorized” ,
	"timestamp": "2020-02-16T10:52:00Z"
}

Events: Webhook response once all the calls are disconnected

{
	"app_instance": "03847288-4586-43be-b834-e00204b86cc1",
	"application_name": "MessageBroadcast for sales",
	"resultset": {
		"successfull_calls": 2,
		"failed_calls": 3
	},
	"timestamp": "2020-06-15T08:31:31.849Z"
}

Report of the MessageBroadcast

This API is called to get the info about the created broadcast applications. This can be called at any time during or after the message broadcast is completed. This API shall return the current state of the Broadcast applications such as current numbers called.

API Route: https://api.enablex.io/voice/v1/broadcast/$appInsatnce

Request Example:

GET https://api.enablex.io/voice/v1/broadcast/$appInsatnce
Authorization: Basic XXXXXXXXX

Response Example:

{
	“app_instance": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
	”application_name”: “MessageBroadcast for sales”
	“resultSet”:[
		“dialed_number”: number,
		"state": "Connected", 
		“result”: {
			“code”: “success”|”failed”,
			“reason”: “OK”| “AMD”|”Busy”
		}
	],
	"timestamp": "2020-02-16T10:52:00Z"
}
KeyDescription
app_instanceRequested instance for the result set
application_nameName of App given at time of creation
result_setArray of numbers and result of dialout as following
dialed_numberIndividual Number
stateCurrent state of the call
resultCall result of the individual outbound call

Stop the Message Broadcast prematurely

API Route: https://api.enablex.io/voice/v1/broadcast/$appInsatnce

Request Example:

DELETE https://api.enablex.io/voice/v1/broadcast/$appInsatnce
Authorization: Basic XXXXXXXXX

Response Example:

{
	“app_instance": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
	”application_name”: “MessageBroadcast for sales”
	"timeStamp": "2020-02-16T10:52:00Z"
}

Error Response:

All error responses will follow the standard HTTP error format and error code. The JSON body of the response will highlight exact error that occurred and it’s description. Please see Erro codes here.

Advanced Usage

Message Broadcast APIs are sufficient to make a basic application with minimal APIs, but advanced use cases may demand finer control on every call leg. To enable this finer control, Message Broadcast API has provided a call_handler_url as a webhook. This webhook is passed to the individual call and gets triggered when the call comes alive.

The call_handler_url is invoked on the outgoing call, exactly in the same way that you would have passed the event_url to the outbound call API.

Once the outbound call is executed, call_handler_url will be invoked and will return the voice_id of the call instance. The application_instance and voice_id can be used to make any voice service call on the current call-leg.

Example:

Let’s take an example, we have a message broadcast application set up for 100,000 outbound calls. And it is required that after every 10th call, a different prompt is required to be played instead of standard other 9 calls.

In order to do that, you will need to get handle of every 10th call in the bulk of numbers of dialed calls. Once you have voice_id of the very 10th call, you need to play a prompt as “You are a special client”.

Using Message Broadcast application instance, you can call up a voice service call “PlayPrompt” as follows:

API Route: https://voice.enablex.io/v1/broadcast/$app_instance

Request Example: 

PUT  https://voice.enablex.io/v1/broadcast/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58
 Authorization: Basic xxxxxx
 Content-Type: application/json
 {
 "voice_id":voice.instance_id // voice id of the individual outbound call
  "play":
         {
                 “text”: “You are a special client”
                 “language”: “es-U
                 “voice”: female
                 “dmtf”:false, //optional field,
                 “prompt_ref”:”User specified unique optons” //Optional
                  “timestamp”: UTC_Timestamp
          }
  }

You can further make any voice service call on this voice_id through message broadcast app_instance!