Voice Application: Message Broadcast – EnableX Developer Centre

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.

Introduction
Message Broadcast APIs
Advanced Usage
Error codes

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.enabenablexlex.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 / Object	Description
`application_name`	Name of the application such as Message Broadcast for Sales
`broadcast_numbers_array`	Broadcast number inputs in array. e.g. [‘Number1’,’Number2’,’Number3’]
`broadcast_numbers_json`	Broadcast numbers as stringified json array. e.g. jsonNumberArray = JSON.stringify([{“phone”: “Number1”}, {“phone”: “Number2”},{“phone”: ”Number3”}])
`from`	Number that will be used as a caller Id (CLI)
`action_on_connect`	This structure will be same as defined in Outbound message in voice API
`event_url`	Broadcast will post Initiated and completed event on this URL
`call_handler_url`	This 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_retries	retrying the call in number of seconds. Default will be 5 seconds
number_of_retries	The 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"
}

Key	Description
`app_instance`	Requested instance for the result set
`application_name`	Name of App given at time of creation
`result_set`	Array of numbers and result of dialout as following
`dialed_number`	Individual Number
`state`	Current state of the call
`result`	Call 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:

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://api.enablex.io/voice/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://api.enablex.io/voice/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_id	Unique 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:

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://api.enablex.io/voice/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.

Table of Contents

Introduction

Workflow Explanation

Message Broadcast APIs

Create and start Broadcast Instance

Report of the MessageBroadcast

Stop the Message Broadcast prematurely

Advanced Usage

Example:

Play Prompt:

API request:

HTTP Request:

PUT

Request Example:

Key Description

Response

Events

Key Description

Bridging

API request

HTTP Request

Request Example

Key Description

Response

Events

Key description

Disconnect Individual Outbound Call

API request

HTTPS request

Request Example :

Response Example

Key description: