Voice Message Broadcast API

EnableX introduced application APIs to create a complex application such as Voice Message Broadcast with minimal or zero codings. Voice 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

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.

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 the voice 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.

API Methods

Create Broadcast

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 URL: https://api.enablex.io/voice/v1/broadcast
• Method: POST
• Authorization: Basic XXXXXXXX

Sample Request:

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

{
	"application_name": "Message Broadcast for sales",
	"owner_ref": "xyz",
	"broadcast_numbers_array": "Array of Phone numbers",
	"broadcast_numbers_json": "Phone Numbers in JSON", 
	"from": "999999999",
	"action_on_connect": {
		"play": {
			"prompt_ref": "1",		// Pre-Recorded
			"text": "Text to Speech Prompt",// TTS
			"voice": "Male",
			"language": "en-US"
		}    
	},
	"call_param": {
		"interval_between_retries": 5,	// in seconds 
		"number_of_retries": 3
	},
	"event_url": "http://your-server/event-handler",
	"call_handler_url": "http://your-serer/call-handler"
}

Explaination of JSON Payload

To try the API, use our Open API tool.

Success Response:

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

Error Response

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"
}

Boadcast Report

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 URL: https://api.enablex.io/voice/v1/broadcast/$app_Insatnce
• Method: GET
• Authorization: Basic XXXXXXXXX

Sample Request:

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

Note: Embedded $app_Insatnce in the API Endpoint URL

To try the API, use our Open API tool.

Success Response

{
	"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"
}

Explaination of JSON Payload

Stop Broadcast prematurely

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

Request Example:

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

Note: Embedded $app_Insatnce in the API Endpoint URL

To try the API, use our Open API tool.

Response Example:

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

Advanced Usage

Voice 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, Voice 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 voice 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 the voice 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 the voice message broadcast app_instance!

Play Prompt

• API URL: https://api.enablex.io/voice/v1/broadcast/$app_instance/call/$voiceId/play
• Method: PUT
• Authorization: Basic xxxxxx

Sample Request:

PUT  https://voice.enablex.io/v1/broadcast/$app_instance/call/$voiceId/play 
Authorization: Basic xxxxxx 
Content-Type: application/json  

{ 
       "prompt_name":"prompt_name",	// Pre-Recorded file
       "text":"Text",			// TTS
       "language":"us-EN",
       "voice": "female", 
       "dmtf":true, 
       "prompt_ref":"User specified unique optons",
       "timestamp": "UTC_Timestamp"  
}

Note: Embedded $app_instance & $voiceId in the API Endpoint URL

Explaination of JSON Payload

Sample Response

HTTPS  202  Accepted

{ 
	"voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58", 
	"play_id":"fdgdfg451c0-8f2a-4fe8-b5ef-9addgdg58",  
	"playstate":"initated", 
	"from": valid CLI, 
	"to":"to_number", 
	"timeStamp": "2017-02-16T10:52:00Z", 
}

Events: Following Event will be posted through the webhook

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

Explaination of JSON Payload

Call Bridging

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

• API URL: https://voice.enablex.io/v1/broadcast/$app_instance/call/$voiceId/connect
• Method: PUT
• Authorization: Basic xxxxxx

Sample Request

PUT https://api.enablex.io/voice/v1/broadcast/$app_instance/call/$voiceId/connect
Authorization: Basic xxxxxx 
Content-Type: application/json 
 
{ 
   "from": "Valid CLI", 
    "to":"Terminating number"
}

Note: Embedded $app_instance & $voiceId in the API Endpoint URL

Explaination of JSON Payload

Sample Response

HTTPS  202  Accepted 

{ 
   "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"                               
}

Explaination of JSON Payload

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

{ 
	"voice_Id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
	"state": "briding",
	"from":  "Valid CLI",
	"to: "desitnation number where the call is bridged.", 
	"timestamp": "2017-02-16T10:52:00Z" 
}

Explaination of JSON Payload

Disconnect Call

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

• API URL: https://api.enablex.io/voice/v1/broadcast/$app_instance/call/$voiceId -* Method*: DELETE
• Authorization:

Sample Request

DELETE https://api.enablex.io/voice/v1/broadcast/$app_instance/call/$voiceId
Authorization: Basic xxxxxx 
Content-Type: application/json

Note: Embedded $app_instance & $voiceId in the API Endpoint URL

Sample Response

200 OK

{ 
	"app_instance": "instance id of the broadcast instance.", 
	"voice_id": "Voice ID of the inidividual call",
	"state": "success", 
	"timestamp": "" 
 }

Explaination of JSON Payload

Error Codes

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 Error Codes here.