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.

The API expects 2 callback URLs, one is an event url that will be used to communicate the results and responses from the server. While the second URL is a webhook URL that will be used to handle and process individual calls in the message broadcast set. With control of individual calls, developers can program the complete message broadcast process with much fine-grained control. For example, if the workflow demands that if the call is accepted, offer DTMF the choice to send an individual calls to the chosen application/s. In a normal scenario, you may not need these advanced controls.

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 */
        // OR (You can use only one, either array or stringified json array)	
	"broadcast_numbers_json": jsonNumberArray 
	"from": "999999999",
	"action_on_connect": {
		"play": {
			"prompt_ref": "1",
                        // OR 
			"text": "Text to Speech Prompt",
			"voice": "Male",
			"language": "en-US"
		}    
	},
	"call_param": {
		"interval_between_retries": 5, // in seconds 
		"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
interval_between_retriesretrying the call in number of seconds. Default will be 5 seconds
number_of_retriesThe number of call retries the system will attempt before declaring failed. Default value is 3

Try Open API Tool…

Response: 

{
	“app_instance": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
	”application_name”: “MessageBroadcast for sales”,
	“state”: "initiated",
	"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/$app_Insatnce

Request Example:

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

Try Open API Tool…

Response Example:

{
	“app_instance": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
	”application_name”: “MessageBroadcast for sales”
	“resultSet”:[
		“dialed_number”: number,
		"state": "connected"|"ringing"| "disconnected", 
		“result”: {
			“code”: “success”|”failed”,
			“reason”: “success”| “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

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.

Stop the Message Broadcast prematurely

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

Request Example:

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

Try Open API Tool…

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” on an instance.

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

Play Prompt: 

API request: 

https://voice.enablex.io/v1/broadcast/$app_instance/call/$voiceId /play

HTTP Request:  
PUT 
Request Example: 
PUT  https://voice.enablex.io/v1/broadcast/8ffa7-8f2a-5fa57e-895f241953756d20b2/call/5fa57e895f241953756d20b2/play 
Authorization: Basic xxxxxx 
Content-Type: application/json  
{ 
        “prompt_name”:"prompt_name", 
        //.   OR 
        “text”: “Text” //Text to be played by the TTS.
                       //In play, either it will be text or it is a prompt which is going to be played
        “language”: “es-U 
        “voice”: female 

        “dmtf”:true, //optional field, 
        “prompt_ref”:”User specified unique optons” //Optional 
        “timestamp”: UTC_Timestamp  
} 

Key Description

prompt_name Identifier of the prompt that was configured on the portal. T configured on the portal. See more details above.   Mandatory or next 3
text Text to be played by the TTS,  In play, either it will be text or it is a prompt which is going to be played Mandatory if prompt_name is not specified
voice Possible values are male or female, Only if the play is for text to speech. Mandatory if prompt_name is not specified and using TTS
language Language to be spoken for TTS Mandatory if prompt_name is not specified
dtmf Dtmf if it is true, will wait for the dtmf digits Optional 
prompt_ref User specified prompt ref optional Optional 

Response

Response: 
Response to REST will be standard response  
HTTPS  202  Accepted.                     //Or other HTTP result on the REST  
{ 
           "voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58", 
           "play_id": “fdgdfg451c0-8f2a-4fe8-b5ef-9addgdg58”, // Play_Id 
           “playstate”:”initated”, 
           “from”: valid CLI, 
           “to”:”to_number”, 
           "timeStamp": "2017-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 the exact error that occurred and its description. Please see Erro codes here.

Events

Following Event will be posted through the webhook

{ 
     "voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58", // Call_Id 
     “from”: valid CLI, 
     “to”:””tonumer” 
     “play_id” “fdgdfg451c0-8f2a-4fe8-b5ef-9addgdg58”, 
     “playstate”:  ”playfinished| “failederror”| 
    “description”: "text""””prompt_ref”:”optional prompt_ref” 
    "timestamp": "2017-02-16T10:52:00Z" 
} 

Key Description

voice_id Unique call identifier 
play_id Unique play identifier returned to indicate action  
from CLI (from number or caller Id)
to Destination number 
playstate State of the current action: 
playfnished: Completed the play
prompt failed: Could not play the prompt     
Timestamp UTC timestamp at which the response was generated  

Bridging

This API is called to bridge the call between the different participant.     

API request

https://voice.enablex.io/v1/broadcast/$app_instance/call/$voiceId /connect

HTTP Request

PUT

Request Example
PUT  https://voice.enablex.io/v1/broadcast/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58/call/5fa57e895f241953756d20b2/connect 
Authorization: Basic xxxxxx 
Content-Type: application/json  
{ 
    “from”: valid CLI //A valid cli, 
    "to": “Terminating number”
} 
Key Description
from A valid caller id.Call will be terminated with the following CLI Mandatory 
to The destination number.   Mandatory. 
Response
HTTPS  202  Accepted.                     //Or other HTTP result on the REST  
 
{ 
         "voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58", 
         “bridge_id”:”bridge_id”,
         "state": “Initiated”,| “failed” 
         “description”: text,
         "from”:”CLI for the call” 
         “to”: “Terminating number” 
         "timestamp": "2017-02-16T10:52:00Z"                               
} 

Key Description

voice_id Voice instnace of the voice service call. 
state State of the bridge request 
bridge_idUnique idenitifier for the bridge
description Description of the faiure in case of call is failed. 
from Valid CLI which is used to terminate this call. 
to The destination number where the call is bridged. 
timestamp UTC timestamp at which the response was generated  

Error Response:

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

Events

Event will be called upon a webhook provided by the application. 

{ 
        "voice_Id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
        “state“ : briding|bridge_disconnected |bridging_failed| bridged | disconnected
        “from”:  valid CLI
        “to: "desitnation number where the call is bridged. 
        "timestamp": "2017-02-16T10:52:00Z" 
 
Key description
voice_id Unique call identifier 
state bridging -> if the other end is ringing 
bridged -> If the call is accepted by the other party 
bridge_failed -> Failed to bridge the call. 
bridge_disconnected -> if the call is disconnected by the bridged number, 
disconnected: If the original participant disconnected the call. 
from Valid CLI which is used to terminate this call. 
to The destination number where the call is bridged. 
timestamp UTC timestamp at which the response was generated 

Disconnect Individual Outbound Call

To disconnect individual call that was started by messagebroadcast application, at any point of the workflow.

API request

https://api.enablex.io/voice/v1/broadcast/$app_instance/call/$voiceId

HTTPS request

DELETE

Request Example : 

DELETE  https://voice.enablex.io/v1/broadcast/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58/call/f3dc9b12-01fd-4e03-9591-655cb22fe96a

Response Example

200 OK
{ 
            “app_instance”:instance id of the broadcast instance. 
            "voice_id": voiceid of the inidividual call 
            "state": "success", 
            "timestamp":ts 
 }; 
Key description:
app_instance Unique instance id of the broadcast app 
voice_id Unique instance of individual Oubound call.