Programmable Voice API Routes

The Voice API version 2.0 provides the following methods:

Dial-Out a Number

The voice service makes an outbound call to a destination number. The CLI (Caller Line Identification) of the number you have rented (shared or dedicated) for the outbound call must be passed as a parameter in the API. This number is matched against the provisioned number. In case of a mismatch, the outbound call will fail.

This API allows a connected call to bridge to another number or join as a participant in a video room.

Route: https://api.enablex.io/voice/v1/call

Sample Request

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

{
	"name": "service name",
	"owner_ref": "xzy",
	"auto_record": false,
	"from":"CLI number",
	"to": "Destination number",
	"action_on_connect": {
		"play": {	// Play pre-recorded file uploaded on Portal	
			"prompt_name":"prompt_name",
			"prompt_ref" : "1"
		}, 
		"play":{	// Play Text-to-Speech
			"text": "text to be played as speech",
			"language": "en-US",
			"voice": "female",
		}, 
		"play" : {	//Play Text-to-Speech (Advance Options)
			"text_to_speech_option": {
				"silence": {
					"type": "leading", 
					"value": '2000ms"  
				}, 
				"text": "Initial Text Play after 2s",
				"break": {
					"value": "2000ms"  
				},
				"text2": "Text Play after 2s break", 
				"express-as": {
					"style": "gentle", 
					"text": "Text play in gentle voice" 
				}, 
				"prosody": {
					"rate": "+30.00%",
					"pitch": "high",
					"volume": "+50.00%",
					"text": "Text play at 30% higher rate & 50% volume",
					"break": {
						"value": "2000ms"
					},
					"text2": "Text Play after 2s break"
					"say-as" : {
						"interpret-as": "date",
						"format": "mdy",
						"text": "10/19/2020"
					},
					"text3": "Text Play"
				} 
			}
		},
		"connect": { // Call to bridge
 			"from": "Originating CLI",
			"to": "Number for bridging"  	   
 	    },
        "room": {	// Join Video Room 
			"room_id": "Video Room ID" 
 	    },
   	}   "event_url": "https://yourserver.com/webhook"
}

Explanation for JSON Payload

action_on_connect.play.express as: To express emotions like cheerfulness, empathy, and calm.

action_on_connect.play.break: The absolute duration of a pause in seconds or microseconds.

action_on_connect.play.prosody: Used to specify changes to pitch, contour, range, rate, and volume for the text-to-speech output. It can contain text and these elements: break, prosody, say-as.

action_on_connect.play.prosody.say_as

action_on_connect.play.prosody.interpret-as The following content types are supported for interpret-as and format attributes/key. Include the format attribute/key only if the format column is not empty in the below table.

To try the API, use our Open API tool.

Sample Response

Response to the REST request is immediately generated from the server. The response code indicates if the call was successful along with the JSON body.

{     
	"voice_id: "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
	"state: "initiated",	// If failed, stats will show failed                            
	"from" : "Originating CLI",
	"to" : "Called Number",
	"timestamp": "2020-02-16T10:52:00Z"  
}

Explanation of JSON Payload

Error Response All error responses follow the standard HTTP error format and error code. The JSON body of the response highlights the exact error that occurred along with its description. For detailed information about error codes, see error codes, here.

Sample Error Response:

{   
	"result": 1234, // 4 digit error code
	"msg": "description of the error",
	"state": "failed",
	"timestamp": "2020-02-16T10:52:00Z"
}

Events

Events that are triggered by the system are called using the webhooks provided by the API.

{
        "voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",  
        "state":  "ringing",
        "from": "CLI number",
        "to": "Destination number",
		"recording_url": "https://domain/sample.wav", 
        "recording_duration": 50, 
		"disconnect_reason": "Normal Clearing | User Busy",
		"room_id": "5f83f9743a8ad03af54eab4b", 	
		"timestamp": "2020-02-16T10:52:00Z"
}

Explanation of JSON Payload

Receive DTMF

EnableX receives DTMF on the voice call and can dispatch it to the application for further processing. For more information about DTMF, see Receiving DTMF.

DTMFs are asynchronous events, and application developers must provide a webhook which will be invoked by the EnableX platform on the application server in the DTMF event. The DTMFs are conveyed in plain text, but are encrypted by the webhook security provided by the platform.

Note: A DTMF event is different from the digitcollected event, which comes for voice menu. A DTMF event is received only after a call is bridged.

Events: Events triggered by the system are called using the webhooks provided by the API.

{
	"voice_Id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",  
	"state": "dtmfcollected",
	"digit": 12345,
	"timestamp": "2017-02-16T10:52:00Z"
}

Explanation of JSON Payload

Receive Speech Recognition Results

EnableX passes the recognized speech text as an event to the application. The text could be a word or a sentence. The application accepts the text and may need to add algorithm to detect the word correctly from the text, as speech recognition depends on various factors and accuracy is always subjective.

The recognized text is available in the event under the recognized_phrase attribute/key.

Events

Events triggered by the system are called using the webhooks provided by the API.

{ 
	"voice_id": "6b211e69-c2cc-4a65-99e9-f7a3c6922796", 
	"state": "recognized", 
	"from": "CLI number", 
	"to": "Destination number", 
	"text": "No, I'm not available.", 
	"reason": "Reczognized",
	"playstate": "speech_recognized",
	"timestamp": "2017-02-16T10:52:00Z",
	"prompt_ref": "welcome-prompt" 
}

Explanation of JSON Payload

Transfer Call

EnableX provides a way to perform an attended or consulted transfer of a bridged (two participants) call to transfer one call leg to an external or a terminating number.

API Route: https://api.enablex.io/voice/v1/call/$voiceId/transfer

Sample Request

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

{ 
	"from": "CLI number",	 
	"transfer_to": "Terminating number"
}

Note: Embedded $voiceId on API Endpoint URL.

Explanation of JSON Payload

To try the API, use our Open API tool.

Response

Response to the REST request is immediately generated from the server. The response code indicates if the server has accepted the request from the client.

{
	"voice_id": "3d561239-a1e8-43dd-bd6d-73f60b027a81",
	"from": "CLI number",
	"to": "Destination number" ,
	"status": "initiated",
	"channel_id": "fdgdfg451c0-8f2a-4fe8-b5ef-9addawrttfh",
	"timestamp": "2020-08-20T09:03:09.893Z"
}

Sample Response

HTTPS 200 Success

{
	"voice_id": "3d561239-a1e8-43dd-bd6d-73f60b027a81",
	"from": "CLI number",
	"to": "Destination number",
	"status": "success",
	"timestamp": "2020-08-20T09:03:09.893Z"
}

Explanation of JSON Payload

Sample Error Response

HTTPS 409 Call State Mismatch

{
	"voice_id": "3d561239-a1e8-43dd-bd6d-73f60b027a81",
	"from": "CLI number",
	"to": "Destination number",
	"status": "failed",
	"msg": "Call is not bridged yet",
	"timestamp": "2020-08-20T09:03:09.893Z"
}

Sample Error Response

HTTPS 500 Internal Server Error

{
	"voice_id": "3d561239-a1e8-43dd-bd6d-73f60b027a81",
	"from": "CLI number",
	"to": "Destination number",
	"status": "failed",
	"result": 500,
	"msg": "Internal Server Error",
	"timestamp": "2020-08-20T09:03:09.893Z"
}

Forward Call

This API is used to forward the leg of a bridged call.

API Route: https://api.enablex.io/voice/v1/call/$voiceId/forward

Sample Request

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

{ 
	"from": "CLI number",		 
	"to": "Destination number"
}

Note: Embedded $voiceId on API Endpoint URL.

Explanation of JSON Payload

Sample Response

Response to REST will be the standard response. Immediate response if the server has accepted the request from client

HTTPS 200 Success

{
	"voice_id": "3d561239-a1e8-43dd-bd6d-73f60b027a81",
	"from": "CLI number",
	"to": "Destination number",
	"status": "success",
	"timestamp": "2020-08-20T09:03:09.893Z"
}

To try the API, use our Open API tool.

Error Response Example

HTTPS 409 Call State Mismatch

{
	"voice_id": "3d561239-a1e8-43dd-bd6d-73f60b027a81",
	"from": "CLI number",
	"to": "Destination number",
	"status": "failed",
	"msg": "Call is not bridged yet",
	"timestamp": "2020-08-20T09:03:09.893Z"
}

Error Response Example

HTTPS 500 Internal Server Error

{
	"voice_id": "3d561239-a1e8-43dd-bd6d-73f60b027a81",
	"from": "CLI number",
	"to": "Destination number",
	"status": "failed",
	"result": 500,
	"msg": "Internal Server Error",
	"timestamp": "2020-08-20T09:03:09.893Z"
}

Play Voice Prompt

This API is called to play prompts in the call. The prompts can be played from the text-to-speech engine or from a remote URL. You can also play pre-recorded and stored prompts. The action instructs to start and stop the play of the prompt.

API Route: https://api.enablex.io/voice/v1/call/$voiceId/play

Sample Request

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

{
	"prompt_name":"prompt_name",	
	"prompt_ref":"welcome_ref",
	"text": "text to be played as speech",
	"language": "en-US",
	"voice": "female",
	
	"dtmf": true, 

	"asr": true, 
	"start_timeout": 10,		// initial silence before user start speaking
	"recognizer_timeout": 1,	// Wait timer before recognizer returns the result
	
	"text_to_speech_option": {
		 "silence": {
			"type": "leading", 
			"value": '2000ms"  
		}, 
		"text": "Initial Text Play after 2s",
		"break": {
			"value": "2000ms"  
		},
		"text2": "Text Play after 2s break", 
		"express-as": {
			"style": "gentle", 
			"text": "Text play in gentle voice" 
		}, 
		"prosody": {
			"rate": "+30.00%",
			"pitch": "high",
			"volume": "+50.00%",
			"text": "Text play at 30% higher rate & 50% volume",
			"break": {
				"value": "2000ms"
			},
			"text2": "Text Play after 2s break"
			"say-as" : {
				"interpret-as": "date",
				"format": "mdy",
				"text": "10/19/2020"
			},
			"text3": "Text Play"
		} 
	}  
}

Note: Embedded $voiceId on API Endpoint URL.

Explanation of JSON Payload

To try the API use our Open API tool.

Sample Success Response

HTTPS  200  Accepted

{
	"voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
	"playstate":"initiated", // Other playstates will be delivered on webhook
	"from": "CLI number",
	"to" : "Destination number"
	"timestamp": "2020-02-16T10:52:00Z"
}

Explanation of JSON Payload

Events: This event is called by a webhook.

{ 
	"voice_id": a8e3607c-46a1-43f6-b0be-f3ead722a6b1,
	"from": "CLI number", 
	"to" : "Destination number", 
	"playstate":  "playfinished |"failed"|"digitcollected"|"menutimeout",
	"prompt_ref":"prompt_ref",
	"digit": 12345, 
	"timestamp": "2020-02-16T10:52:00Z" 
}

Explanation of JSON Payload

Error Response

The API returns the below error response in case of a failure. All error responses follow the standard HTTP error format and error code, that is, HTTPS 4**, 5**.

{
	"voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
	"playstate": "failed",	
	"timeStamp": "2017-02-16T10:52:00Z",
	"result" : "code",
	"msg": "Description" 
}

Error Response: The voice server returns this error when the call is in bridged mode and cannot play the prompt.

HTTPS 405 Method Not allowed.

{
	"voice_id": a8e3607c-46a1-43f6-b0be-f3ead722a6b1
	"from": "CLI number",
	"to" : "Destination number",
	"playstate":"failed",
	"result" : 6112,
	"msg":"Call is in bridged mode, can't play media",
	"timestamp": "2020-02-16T10:52:00Z "
 }

Error Response: The voice server returns this error when the voice or language is not supported for text-to-speech conversion.

HTTPS 406 Not acceptable 

{
	"voice_id": a8e3607c-46a1-43f6-b0be-f3ead722a6b1
	"from": "CLI number",
	"to" : "Destination number",
	"result" :6117,
	"msg":"Voice not supported for text-to-speech  conversion",
	"playstate": "failed",
	"timestamp": "2020-02-16T10:52:00Z "
 }

Error Response: The voice server returns this error response when the text-to-speech conversion fails.

HTTPS 408 request pending

{
	"voice_id": a8e3607c-46a1-43f6-b0be-f3ead722a6b1
	"from":"CLI number",
	"to":"Destination Number",
	"playstate":"failed",
	"result" : 6114,
	"msg":"Play request pending",
	"timestamp": "2020-02-16T10:52:00Z "
 }

Error Response: The voice server returns this error when the media request fails.

HTTPS 400 bad request

{
	"voice_id": a8e3607c-46a1-43f6-b0be-f3ead722a6b1,
	"from": "CLI number",
	"to" : "Destintion number",
	"playstate":"failed",
	"result" :400,
	"msg": "Media Request Failed",
	"timestamp": "2020-02-16T10:52:00Z "
 }

Sample Error Response: The voice server returns this error response when the text-to-speech conversion fails.

HTTPS 503 Server not available

{
	"voice_id": a8e3607c-46a1-43f6-b0be-f3ead722a6b1
	"from":"CLI number",
	"to":"Destination number",
	"playstateus":"failed",
	"result" : 6107,
	"msg": "Error doing text to speech conversion",
	"timestamp": "2020-02-16T10:52:00Z "
 }

Bridge Call

This API is called to bridge a call between two participants.

API Route: https://api.enablex.io/voice/v1/call/$voiceId/connect

Sample Request

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

{
	"from": "CLI number",
	"to" : "Destination number"
}

Note: Embedded $voiceId on API Endpoint URL.

Explanation of JSON Payload

To try the API, use our Open API tool.

Sample Response

HTTPS 200 Accepted

{
	"voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
	"state": "initiated",  
	"from": "CLI number",
	"to" : "Destination number",
	"timeStamp": "2017-02-16T10:52:00Z"
 }

Explanation of JSON Payload

Events

Events are called by a webhook provided by the application server using the API.

{
	"voice_Id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",  
	"state": "bridging" | "failed"| "bridge_disconnected" | "bridged",
	"from":  "CLI number",
	"to": "Destination number",
	"timestamp": "2017-02-16T10:52:00Z"
}

Explanation of JSON Payload

Error

The Bridge API returns errors if the API succeeds or fails. All error responses follow the standard HTTP error format and error code. The JSON body of the response highlights the exact error that occurred and its description.

Error Response: The voice server returns this error response when the outbound or inbound service is not configured for the phone number.

HTTPS 404 Not Found

{
	"result": "6110",
	"msg": "Application Not Found",
	"state": "failed",
	"timestamp": "2020-02-16T10:52:00Z"
}

Error Response: The voice service returns this error when the outbound or inbound service is not configured for the CLI number.

HTTPS 404 Phone Number Not Found

{
	"result": "6118",
	"msg": "Phone number not found for the service",
	"state": "failed",
	"timestamp": "2020-02-16T10:52:00Z"
}

Analyze Call

The Analyze call APIs are used for collecting live details about a call running in the system and the state of the call.

API Route: https://api.enablex.io/voice/v1/call/$voiceId/

Sample Request

GET  https://api.enablex.io/voice/v1/$voiceId
Authorization: Basic XXXXXXXX

Note: Embedded $voiceId on API Endpoint URL.

Sample Response

{
	"voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58", // Call_Id
	"state": "connected", /* connected,  In progress, IVR" */
	"direction": "Inbound", /* Inbound, Outbound */ 
	"from": "CLI number",
	"to" : "Destination number",
	"timestamp": "2017-02-16T10:52:00Z"
}

Explanation of JSON Payload

To try the API, use our Open API tool.

Error Response

All error responses follow the standard HTTP error format and error code. The JSON body of the response highlights the exact error that occurred and its description.

HTTPS 400 

{
	"voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",  
	"from": "CLI number",
	"to": "Destination number",
	"result": "Number",
	"msg": "",
	"timestamp": "2017-02-16T10:52:00Z"
}

Hold or Unhold a Call

This API is called to hold or resume a bridged channel and to play music on hold.

API Route: https://api.enablex.io/voice/v1/call/$voiceId/hold

**Sample Request to hold **

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

{	"hold": true,
}

Note: Embedded $voiceId on API Endpoint URL.

Explanation of JSON Payload

To try the API, use our Open API tool.

Start or Stop Call Recording

This API is called to start or stop recording of a live call.

API Route: https://api.enablex.io/voice/v1/call/$voiceId/recording

Sample Request to start recording

PUT https://api.enablex.io/voice/v1/call/$voiceId/recording
Authorization: Basic xxxxxx
Content-Type: application/json 
 
{
	"start": true,
	"recording_name": "my_voice_recording" 
}

Sample Request to stop recording

PUT https://api.enablex.io/voice/v1/call/$voiceId/recording
Authorization: Basic xxxxxx
Content-Type: application/json 
 
{	"stop": true 
}

Note: Embedded $voiceId on API Endpoint URL.

Explanation of JSON Payload

To try the API, use our Open API tool.

Response

The server sends an immediate response if it has accepted the request from the client.

Success Response

HTTPS 200 Success

{
         "status": "success",
         "from": "CLI number",
         "to": "Destination number",
         "voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",  
		 “recording_id”: “uniquerecording identifier”,
         "timeStamp": "2017-02-16T10:52:00Z" 
}

Explanation of JSON Payload

Error Response: The voice server returns this error when it fails to start the call recording.

HTTPS 500

{
	"status": "failed",
	"from": "CLI number",
	"to": "Destination number",
	"voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",  
	"result": "6119",
	"msg": "Failed to start recording on bridge",
	"timeStamp": "2017-02-16T10:52:00Z"
}

Error Response

HTTPS 409 Call State Mismatched

{
	"status": "failed",
	"from": "CLI number ",
	"to": "Destination number",
	"voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",  
	"result": "409",
	"msg": "Call is not bridged yet",
	"timeStamp": "2017-02-16T10:52:00Z"
}

Error Response

HTTPS 408 Request Pending

{
	"status": "failed",
	"from": "CLI number",
	"to": "Destination number",
	"voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",  
	"result": "408",
	"msg": "Call is already recording",
	"timeStamp": "2017-02-16T10:52:00Z"
}

Events

Events of different levels of progression of the recording are sent back to the application through the event URLs.

{
	"voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",  
	"state": "completed",  
	"timestamp": "2017-02-16T10:52:00Z",
	"description" : "Recording Started | Recording Completed"
}

The JSON keys for the event are described below.

Retrieve Call Recording

This API is called to pull the recorded files by the client application.

API Route: https://api.enablex.io/voice/v1/recordubg/$recordingId

Sample Request

GET https://api.enablex.io/v1/recording/$recordingId
Authorization: Basic XXXXXXXX

Note: Embedded $recordingId on API Endpoint URL.

Success Response: HTTPS 200. File download starts from server.

Error Response

HTTPS 404 Not Found

{
	"result":404,
	"msg":"Recording File Not Found"
}

Explanation of JSON Payload

Hang-Up Call

This API is called to hang up or disconnect a call.

API Route: https://api.enablex.io/voice/v1/call/$voiceId/

Sample Request

DELETE https://api.enablex.io/v1/call/$voiceId
Authorization: Basic XXXXXXXX

Note: Embedded $voiceId on API Endpoint URL

To try the API, use our Open API tool.

Sample Response

{
	"voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
	"state":success,
	"from": "CLI number",
	"to": "Destination number",
	"timeStamp": "2020-02-16T10:52:00Z"
 }

Events: If event_url is provided, the system lets the application know regarding the disconnection status.

Sample Event Post*

{
	"voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",  
	"state": "disconnected",
	"from": "CLI number",
	"to": "Destination number",
	"timeStamp": "2020-02-16T10:52:00Z",
	"disconnect_reason : "Normal Clearing",
	"recording_url": "https://domain/sample.wav",
	"recording_duration": 50
}

Explanation of JSON Payload

Error Codes

All error responses follow the standard HTTP error format and error code. The JSON body of the response highlights the exact error that occurred and its description. For detailed information about error codes, see Error Handling.