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

Object/KeyDescription
NameOptional parameter to name this service.
owner_refFree 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_recordAutomatic recording of the call or through command.
FromThe CLI assigned on the outbound number. This number is matched with the configured number.
ToThe destination number.
action_on_connectActions to be performed on connected calls.
action_on_connect.playSpecify Pre-Recorded Voice Prompt Play or TTS Definition
action_on_connect.connectThis is to call another number to bridge
action_on_connect.roomThis is to join a Video Room and put the call as Participant in the Room
action_on_connect.event_urlURL to receive event/update posts

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

KeyRequired/OptionalDescription
styleRequiredSpecifies the speaking style.
Supported styles are advertisement_upbeat, Cheerful customerservice, Friendly, and gentle.
textNot ApplicableText to speak with the selected style.

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

KeyRequired/OptionalDescription
timeRequiredAlways 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.

KeyRequired/Optionaldescription
pitchOptionalSpecifies the baseline pitch for the text.
rateOptionalSpecifies the speaking rate of the text.
volumeOptionalSpecifies 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

KeyRequired/Optionaldescription
Content TypeRequiredSpecifies the content type of an element's text.
FormatOptionalSpecifies 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-asformatInterpretation
characters, spell-outNoneThe 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, numberNoneThe 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."
ordinalNoneThe 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_digitNoneThe 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."
fractionNoneThe 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."
datedmy, mdy, ymd, ydm, ym, my, md, dm, d, m, yThe 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."
timehms12, hms24The 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."
durationhms, hm, msThe 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.
telephoneNoneThe 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."
currencyNoneThe 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."
addressNoneThe 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."
nameNoneThe 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

KeyDescription
voice_idIdentifier of the voice call.
stateThe state of the voice call such as initiated or failed.
msgTextual description of the reason code.
owner_refFree data passed during the request.
timestampUTC 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

KeyDescription
voice_idA unique identifier created when a call is made This identification is used for all subsequent requests to the server.
stateThe 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.
fromThe originating number (typically the configured number) used as the CLI.
toThe destination number.
recording_urlPath of the call recording file.
timestampThe 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

KeyDescription
voice_idA unique identifier of the voice call.
stateThe state of the DTMF event: dtmfcollected.
digitThe DTMF value pressed by the user.
timestampThe 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

KeyDescription
voice_idA unique identifier of the voice call.
staterecognized, timeout, unrecognized
`text"recognized text content
timestampThe 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

KeyDescription
fromThe The originating number (typically the configured number) used as the CLI.
transfer_toThe 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

KeyDescription
voice_idA unique identifier of the voice call.
fromThe originating number (typically the configured number) used as the CLI.
toThe destination number to bridge the call.
statusThe state of the transfer request. The possible states are: initiated or failed. All call related events are called using webhooks.
channel_idA unique identifier for the channel.
timestampThe 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

KeyDescriptionRequired
fromThe The originating number (typically the configured number) used as the CLI.Mandatory
toThe destination number to forward the leg of a bridged callMandatory

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

KeyDescriptionRequired
prompt_nameThe identifier of the prompt as configured on the EnableX portal.Required if text is not used
prompt_refThe user specified prompt_ref.Optional
textText to play by the text-to-speech engine. Either the text or the prompt is played.Required if prompt_name is not used
voiceFor text-to-speech only. Possible values are: male or female.Mandatory if text is used.
languageLanguage to speak in the prompt.
dtmfSpecify true if you want to wait for the digits pressed by the user.Optional
asrSpecify true if you want to enable interactive voice response through speech recognition.Optional
start_timeoutThe initial silence timeout before the user starts speaking. The allowed range is 1 - 10 seconds. The default is 10 seconds.Optional
recognizer_timeoutWait before the voice server returns the result after silence. Range : 1 - 10 seconds. Default : 2 seconds.Optional
text_to_speech_optionText to Speech Advance OptionsOptional

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

KeyDescription
playstateInitiated
voice_idA unique identifier of the call.
timestampThe 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

KeyDescription
voice_idA unique identifier of the call.
playstateState 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_refThe user specified prompt_ref.
digitDTMF digits collected if playstate is set in the digitcollected timestamp.
timestampThe 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

KeyDescriptionRequired
fromThe The originating number (typically the configured number) used as the CLI..Mandatory
toThe 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

KeyDescription
voice_idA unique identifier of the voice call.
bridge_idA unique identifier of the bridge.
stateThe state of the bridge request. The possible values are: initiated and failed.
fromThe valid CLI that is used as Caller Id for the call.
toThe destination number to bridge the call.
timestampThe 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

KeyDescription
voice_idA unique identifier of the voice call.
stateThe 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.
fromThe original phone number, also known as Caller Id.
toThe destination number to bridge the call.
timestampThe 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

KeyDescription
voice_idA unique identifier of the voice call.
stateThe 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.
fromThe The originating number (typically the configured number) used as the CLI..
toThe destination phone number.
timestampThe 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

KeyDescriptionRequired
holdSpecify 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

KeyDescription
startRequired to start the recording. Accepts Boolean values. By default, it is set to true, which means to start the recording.
recording_nameSpecifies the name of the recording file. If a recording file with the same name already exists, the request will fail.
stopRequired 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

KeyDescription
voice_idA unique identifier of the call.
statusThe state of the call, whether recording started
msgTextual description of the reason code. It contains a description in case of failure description. It case of success, it is blank.
timestampThe 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.

KeyDescription
voice_idA unique identifier of the call.
stateThe state of the recording
started: Recording has started.
completed: Recording is completed.
failed: Recording has failed for a reason code.
descriptionThe description of the recording state.
timestampThe 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

KeyDescription
resultThe result code returned by the API.
msgThe 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

KeyDescription
voice_idA unique identifier on which the disconnect call event is invoked.
disconnect_reasonNormal 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.