Programmable Voice API Routes

Postman collection

Voice API - Last updated: Aug 12, 2024

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

Object/Key	Description
Name	Optional parameter to name this service.
owner_ref	Free data field that will be returned as-is in response to an event. It can be used as means to co-relate requests and responses.
auto_record	Automatic recording of the call or through command.
From	The CLI assigned on the outbound number. This number is matched with the configured number.
To	The destination number.
action_on_connect	Actions to be performed on connected calls.
action_on_connect.play	Specify Pre-Recorded Voice Prompt Play or TTS Definition
action_on_connect.connect	This is to call another number to bridge
action_on_connect.room	This is to join a Video Room and put the call as Participant in the Room
action_on_connect.event_url	URL to receive event/update posts

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

Key	Required/Optional	Description
style	Required	Specifies the speaking style. Supported styles are advertisement_upbeat, Cheerful customerservice, Friendly, and gentle.
text	Not Applicable	Text to speak with the selected style.

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

Key	Required/Optional	Description
time	Required	Always set this value below 5000 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.

Key	Required/Optional	description
pitch	Optional	Specifies the baseline pitch for the text.
rate	Optional	Specifies the speaking rate of the text.
volume	Optional	Specifies the volume level of the speaking voice.You can express the volume as: Percentage : Expressed as a number preceded by "+" (optionally) or "-" and followed by "%", indicating the relative change. For Example: `<prosody volume="50%">some text</prosody>` Constant value: silent , x-soft, soft , medium , loud , x-loud , default

action_on_connect.play.prosody.say_as

Key	Required/Optional	description
Content Type	Required	Specifies the content type of an element's text.
Format	Optional	Specifies additional information about the precise formatting of the element's text for content types that might have ambiguous formats.

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.

`interpret-as`	format	Interpretation
characters, spell-out	None	The text is spoken as individual letters (spelled out). The speech synthesis engine pronounces: `<say-as interpret-as="characters">test</say-as>` as "T E S T."
cardinal, number	None	The text is spoken as a cardinal number. The speech synthesis engine pronounces: There are `<say-as interpret-as="cardinal">10</say-as>` options as "There are ten options."
ordinal	None	The text is spoken as an ordinal number. The speech synthesis engine pronounces: Select the `<say-as interpret-as="ordinal">3rd</say-as>` option as "Select the third option."
number_digit	None	The text is spoken as a sequence of individual digits. The speech synthesis engine pronounces: `<say-as interpret-as="number_digit">123456789</say-as>` as "1 2 3 4 5 6 7 8 9."
fraction	None	The text is spoken as a fractional number. The speech synthesis engine pronounces: `<say-as interpret-as="fraction">3/8</say-as>` of an inch as "three eighths of an inch."
date	dmy, mdy, ymd, ydm, ym, my, md, dm, d, m, y	The text is spoken as a date. The format attribute/key specifies the date's format (d=day, m=month, and y=year). The speech synthesis engine pronounces: Today is `<say-as interpret-as="date" format="mdy">10-19-2016</say-as>` as "Today is October nineteenth two thousand sixteen."
time	hms12, hms24	The text is spoken as a time. The format attribute/key specifies whether the time is specified by using a 12-hour clock (hms12) or a 24-hour clock (hms24). Use a colon to separate numbers representing hours, minutes, and seconds. Some valid time examples are: 12:35, 1:14:32, 08:15, and 02:50:45. The speech synthesis engine pronounces: The train departs at `<say-as interpret-as="time" format="hms12">4:00am</say-as>` as "The train departs at four A M."
duration	hms, hm, ms	The text is spoken as a duration. The format attribute/key specifies the duration's format (h=hour, m=minute, and s=second). The speech synthesis engine pronounces: `<say-as interpret-as="duration">01:18:30</say-as>` as "one hour eighteen minutes and thirty seconds". `<say-as interpret-as="duration" format="ms">01:18</say-as>` as "one minute and eighteen seconds". This tag is only supported on English and Spanish.
telephone	None	The text is spoken as a telephone number. The format attribute/key can contain digits that represent a country code. Examples are "1" for the United States or "39" for Italy. The speech synthesis engine can use this information to guide its pronunciation of a phone number. The phone number might also include the country code, and if so, takes precedence over the country code in the format attribute/key. The speech synthesis engine pronounces: The number is `<say-as interpret-as="telephone" format="1">(888) 555-1212</say-as>` as "My number is area code eight eight eight five five five one two one two."
currency	None	The text is spoken as a currency. The speech synthesis engine pronounces: `<say-as interpret-as="currency">99.9 USD</say-as>` as "ninety-nine US dollars and ninety cents."
address	None	The text is spoken as an address. The speech synthesis engine pronounces: I'm at `<say-as interpret-as="address">150th CT NE, Redmond, WA</say-as>` as "I'm at 150th Court Northeast Redmond Washington."
name	None	The text is spoken as a person's name. The speech synthesis engine pronounces: `<say-as interpret-as="name">ED</say-as>` as `[æd]`.

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  state will be "failed"                            
	"from" : "Originating CLI",
	"to" : "Called Number",
	"timestamp": "2020-02-16T10:52:00Z"   
}

Explanation of JSON Payload

Key	Description
`voice_id`	Identifier of the voice call.
`state`	The state of the voice call such as initiated or failed.
`msg`	Textual description of the reason code.
`owner_ref`	Free data passed during the request.
`timestamp`	UTC timestamp at which the response was generated.

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

Key	Description
`voice_id`	A unique identifier created when a call is made This identification is used for all subsequent requests to the server.
`state`	The voice call state event while connecting the call - ringing: The ringing tone is received from the destination number (called party). connected: The call is accepted. disconnected: The call is not answered or is declined by the called party. bridging: The bridged call is initiated. bridged: The call is bridged. bridged_disconnected: Bridged call disconnected. failed: Bridging the call has failed.
`from`	The originating number (typically the configured number) used as the CLI.
`to`	The destination number.
`recording_url`	Path of the call recording file.
`timestamp`	The timestamp of the event created by the server in UTC.

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

Key	Description
`voice_id`	A unique identifier of the voice call.
`state`	The state of the DTMF event: `dtmfcollected`.
`digit`	The DTMF value pressed by the user.
`timestamp`	The timestamp in UTC at which the response is generated.

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

Key	Description
`voice_id`	A unique identifier of the voice call.
`state`	recognized, timeout, unrecognized
`text"	recognized text content
`timestamp`	The timestamp in UTC at which the speech is analyzed.

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

Key	Description
`from`	The The originating number (typically the configured number) used as the CLI.
`transfer_to`	The destination number to transfer the call.

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

Key	Description
`voice_id`	A unique identifier of the voice call.
`from`	The originating number (typically the configured number) used as the CLI.
`to`	The destination number to bridge the call.
`status`	The state of the transfer request. The possible states are: initiated or failed. All call related events are called using webhooks.
`channel_id`	A unique identifier for the channel.
`timestamp`	The timestamp in UTC at which the response is generated.

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

Key	Description	Required
`from`	The The originating number (typically the configured number) used as the CLI.	Mandatory
`to`	The destination number to forward the leg of a bridged call	Mandatory

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

Key	Description	Required
`prompt_name`	The identifier of the prompt as configured on the EnableX portal.	Required if `text` is not used
`prompt_ref`	The user specified `prompt_ref`.	Optional
`text`	Text to play by the text-to-speech engine. Either the text or the prompt is played.	Required if `prompt_name` is not used
`voice`	For text-to-speech only. Possible values are: male or female.	Mandatory if `text` is used.
`language`	Language to speak in the prompt.
`dtmf`	Specify true if you want to wait for the digits pressed by the user.	Optional
`asr`	Specify true if you want to enable interactive voice response through speech recognition.	Optional
`start_timeout`	The initial silence timeout before the user starts speaking. The allowed range is 1 - 10 seconds. The default is 10 seconds.	Optional
`recognizer_timeout`	Wait before the voice server returns the result after silence. Range : 1 - 10 seconds. Default : 2 seconds.	Optional
`text_to_speech_option`	Text to Speech Advance Options	Optional

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

Key	Description
`playstate`	Initiated
`voice_id`	A unique identifier of the call.
`timestamp`	The timestamp in UTC at which the response is generated.

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

Key	Description
`voice_id`	A unique identifier of the call.
`playstate`	State of the current action. `playfinished`: Completed the play prompt `digitcollected`: The user has provided DTMF for voice menu prompt. `menutimeout`: The user has not provided DTMF for the voice menu prompt. `failed`: Could not play the prompt
`prompt_ref`	The user specified `prompt_ref`.
`digit`	DTMF digits collected if `playstate` is set in the `digitcollected` timestamp.
`timestamp`	The timestamp in UTC at which the response is generated.

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

Key	Description	Required
`from`	The The originating number (typically the configured number) used as the CLI..	Mandatory
`to`	The destination number or SIP URI.	Mandatory

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

Key	Description
`voice_id`	A unique identifier of the voice call.
`bridge_id`	A unique identifier of the bridge.
`state`	The state of the bridge request. The possible values are: `initiated` and `failed`.
`from`	The valid CLI that is used as Caller Id for the call.
`to`	The destination number to bridge the call.
`timestamp`	The timestamp in UTC at which the response is generated.

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

Key	Description
`voice_id`	A unique identifier of the voice call.
`state`	The state of the bridge request. The possible values are: The voice call state event while connecting the call. `initiated`: The bridged call is initiated. `bridging` : The called number is ringing. `bridged` : The call is accepted by the other party. `failed` : Bridging the call has failed. `bridge_disconnected` : : The call is disconnected by the bridged number. `disconnected` : The call is disconnected by the original party.
`from`	The original phone number, also known as Caller Id.
`to`	The destination number to bridge the call.
`timestamp`	The timestamp in UTC at which the response is generated.

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

Key	Description
`voice_id`	A unique identifier of the voice call.
`state`	The state of call after the current action: `Connected` : The Call is running and is in progress `In progress` : Call is not yet connected. The call may be ringing or attempting to connect. `IVR` : The call is connected and interactive voice response is being played.
`from`	The The originating number (typically the configured number) used as the CLI..
`to`	The destination phone number.
`timestamp`	The timestamp in UTC at the which the response is generated.

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

Key	Description	Required
`hold`	Specify true to hold, false to unhold the bridged call leg. To resume the bridged call leg, specify false.	Required

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

Key	Description
`start`	Required to start the recording. Accepts Boolean values. By default, it is set to true, which means to start the recording.
`recording_name`	Specifies the name of the recording file. If a recording file with the same name already exists, the request will fail.
`stop`	Required to stop the recording. Accepts Boolean values. By default, it is set to true, which means to stop the recording.

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

Key	Description
`voice_id`	A unique identifier of the call.
`status`	The state of the call, whether recording started
`msg`	Textual description of the reason code. It contains a description in case of failure description. It case of success, it is blank.
`timestamp`	The timestamp in UTC at which the response is generated.

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

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

Key	Description
`voice_id`	A unique identifier of the call.
`state`	The state of the recording started: Recording has started. completed: Recording is completed. failed: Recording has failed for a reason code.
`description`	The description of the recording state.
`timestamp`	The timestamp in UTC at which the time response is generated.

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

Key	Description
`result`	The result code returned by the API.
`msg`	The textual description of the result code.

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

Key	Description
`voice_id`	A unique identifier on which the disconnect call event is invoked.
`disconnect_reason`	Normal Clearing, User Busy

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.

Programmable Voice API | Incoming Calls Programmable Voice API | Sample Codes