Voice API v1.0 Reference

Table of Contents

• Receive incoming Call
• Dial-Out a Number
• Receive DTMF
• Receive Speech recognition results
• Transfer Call
• Forward Call
• Play Voice Prompt
• Bridge Call
• Analyze Call
• Call Hold-Unhold
• Recording
  • Start / Stop Call Recording
  • Retrieve Call Recording
• Hang-Up Call
• Error Codes

EnableX Voice Service handles both Inbound and Outbound Voice Calls. Inbound Voice Call are processed through pre-configured WebHook URL to accept call, play Tones / Voice Prompts and make onward call to Bridge. On the other hand, Outbound Voice Calls are originated through Rest API Service and handled through pre-configured WebHook URL called by Voice Services to notify progress/status, etc.

Receive Incoming Call

Inbound Voice Service needs to be configured for your Project through EnableX Portal. Follow the detailed Guidelines given in the Get Started page to configure the following:

• A Phone Number to receive Inbound Voice Call
• Voice Prompt (Optional) – If not configured, default prompts would be played
• WebHook to process Inbound Voice Call

If you have chosen a shared incoming call, you will get a PIN displayed along with the assigned phone number. This PIN will be used for receiving a call and once the caller dials the PIN, call will be routed to your application.

Handle Incoming Call Events

If the incoming number is dedicated, the prompt configured for the incoming numbers will be played and then the control will be handed over to the program using the configured webhook event. If the incoming number is shared, an additional system-generated IVR will be played to query the PIN before the call is routed to the configured application.

In case if the greeting is configured, the greetings will be played by the system. Once the play is complete, a Webhook will be invoked for further processing.

If the developer intend to make programatic decision if the call to be accepted or not, the “/accept” API should be used.

Example: Incoming Event JSON

{
	“voice_id”: “f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58”,
	“state”: “incomingcall”,
	“from”: “CLI number”,
	“to”: “Destination number”,
	“channel_id”:
	“timestamp: “2020-02-16T10:52:00Z”
}

Key	Description
voice_id	voice_id of the incoming call. This identification shall be used for all further requests to the server.
state	Incoming call: The webhook notification is set to call as soon as the incoming call comes, the call can be rejected through API. This state will be invoked if there is no default greeting configured
from	Originating phone number – also known as Caller Id
to	The number to which the call is dialed in. Phone number assigned to voice service for the project.
timestamp	Timestamp at which the call is received

In case if the developer needs to take control of the call before it is auto-answered, developer should remove the default greetings and implement the webhook for notification of the incoming call. Once the application receives the webhook event, the following “/accept” API can be used to accept a call. If this API is not called, the incoming call will not be answered and the call shall be dropped.

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

Request Example:

POST https://api.enablex.io/voice/v1/call/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58/accept
Authorization: Basic xxxxx

Responses:

HTTPS 200 Success. //Or other standard HTTP result
{
"voice_id": "3d561239-a1e8-43dd-bd6d-73f60b027a81"
"status": "success"
}

Key Description:

voice_id	Voice instance of the voice service call
status	status of the accept call

Dial Out a Number

This service makes an outbound call to the destination number.

The CLI (Caller Line Identification) of the number you have rented (shared or dedicated) for the outbound call is expected to be passed by the developer, as a parameter to the API. The number passed by the developer will be matched against the provisioned number. If there is any mismatch, the outbound call will fail.

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

Request Example:

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": {   
			"prompt_name":"prompt_name",
                        "asr":true
		}, // Or  
		"play":{ 
			"text": "your prompt here",
			"language": "en-US",
			"voice": "female",
                        "asr":true   
		}, 
                "start_timeout": 10, 
                "recognizer_timeout": 1               
	}
        "event_url": "https://yourserver.com/webhook"
}

Object/Key	Description	Constraints
name	Optional parameter to name this service	Optional
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.	Optional
auto_record	Recording by default or on command	Optional
from	The CLI assigned on the outbound number. This number is matched with the configured number.	Mandatory
to	Destination number	Mandatory
action_on_connect	If set, prompt will be played automatically when destination number is connected	Optional
action	Specifies the action to perform when an outbound call is connected. Action, could either be: To connect the call To bridge the call with one more participant or Play voice prompt or voice menu	Optional
prompt_name	Plays the prompt that has been uploaded with Prompt Id through portal provisioning	Optional
text	TTS to play the prompt according to the parameter defined as following parameters below	Optional
language	The preferred spoken language for TTS	Conditional, if text is supported
voice	Voice gender	Conditional. Need to be there if “text” is present.
asr	Enable Automatic Speech Recognition, to detect words/sentences and return in the text	Optional
start_timeout	Initial silence timeout before user start speaking.   Range : 1 – 10 seconds.  Default : 10 seconds.	Optional
recognizer_timeout	Wait before the voice server returns the result after silence.  Range : 1 – 10 seconds.  Default : 2 seconds.	Optional
event_url	Webhook URL to be called for the application to take control	Optional

Try Open API Tool…

Response: Immediate response will be generated from the server as a response to the REST request. REST response code would represent if the call was successful along with the JSON body.

Response Example

{     
	"voice_id:  
	“state: “initiated”,	// If failed  state will be "failed"                            
	“msg”: string,     
	“owner_ref”:		// User defined Id                              
	“time_stamp": "2020-02-16T10:52:00Z"              
}

Key	Description
voice_id	Voice Call Identifier
state	state could be initiated | 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 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.

Error Response Example:

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

Events: Events will be triggered by the system will be called using the webHooks provided by the API

{
        "voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58", // Call_Id
        “state”:  “ringing” | “connected” | “disconnected” | "voicemail",
        "from": "CLI number",
        "to": "Destination number",
        "channel_id": "xxxx"//channel id associated with the call leg
        "timestamp": "2020-02-16T10:52:00Z",
}

Key	Description
voice_id	voice ID is a unique identifier created when a call is made This identification shall be used for all subsequent requests to the server
state	Call state events while connecting the call. ringing: Receiving ringing tone from called party connected: Call is accepted disconnected: Call was not answered or declined by called party voicemail: Call was connected to voice mail, only if voice mail detection is enabled
from	Originating number (typically configured number) used as the CLI
to	Destination number (aka Called party number)
channel_id	Channel id associated with the call leg
timestamp	Event’s timestamp created by server

Receive DTMF

EnableX receives DTMF on the voice call and can dispatch it to the application for further processing.

DTMFs are asynchronous events, and EnableX expect API developers to provide a Webhook. The Webhook will be invoked by the EnableX platform on Application server in the DTMF event.

The DTMF are conveyed in plain text, but are encrypted by the Webhook security provided by the platform.

Note: This Event is different from digitcollected event which comes for voice menu, and this event will come only after call is bridged.

Events: Events will be triggered by the system will be called using the webHooks provided by the API

{
	"voice_Id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58", // Call_Id
	“channel_id”:” fdgdfg451c0-8f2a-4fe8-b5ef-9addawrttfh”,
	“state”: “dtmfcollected”,
	“digit”: 12345,
	“timestamp": "2017-02-16T10:52:00Z"
}

Key	Description
voice_id	voice ID is a unique identifier
channel_id	Unique channel ID of the channel which received DTMF
state	State of Event: dtmfcollected
digit	DTMF value pressed by user
timestamp	UTC timestamp at which the response was generated

Receive Speech recognition results

EnableX passes the recognized sppech text as event to the application. The text could be a word or sentence.

Application should accept the text and may need to add algorithm to detect the word correctly, as speech recognition depends on various factors and accuracy is always subjective.

The recognized text will be available in the event under attribute: recognized_phrase

Events: Events will be triggered by the system will be called using the webHooks provided by the API

{ 
   "voice_id": "6b211e69-c2cc-4a65-99e9-f7a3c6922796", 
   "result": { 
   "reason": " RecognizedSpeech” 
   }, 
   "state": "recognized |  timeout | unrecognized", 
   "from": "CLI number", 
   "to": "Destination number", 
   "asr_id": "50f4dcd7-5f9b-4b62-a86f-5e2ab65ab84c", 
   "recognised_phrase": "No, I'm not available.", 
   "prompt_ref": "welcome-prompt" 
} 

Transfer Call

EnableX provides a way to perform a attended or consulted transfer by using this call. It is assumed that you have a bridged (i.e. 2 participants) call exist and want to transfer one call leg to external or terminating number.

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

PUT https://api.enablex.io/voice/v1/call/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58/transfer
Authorization: Basic xxxxxx
Content-Type: application/json 

{ 
	"from": "CLI number",		// Valid CLI
        "transfer_to": "Terminating number”
}

Key	Description	Constraints
from	Originating phone number – also known as Caller Id	Mandatory
transfer_to	The Destination Number	Mandatory

Try Open API Tool…

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

Response Example: HTTPS 200 Success

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

Key	Description
voice_id	Voice instance of the voice service call
from	Originating phone number – also known as Caller Id
to	The destination number where the call is bridged
status	State of the transfer request Possible states are: initiated or failed (All call related events shall be posted on webhook)
channel_id	Unique identifier for the channel
timestamp	UTC timestamp at which the response was generated

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

Key	Description
voice_id	Unique call identifier
msg	Textual description on failure
timestamp	UTC timestamp at which the response was generated

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

Key	Description
voice_id	Voice instance of the voice service call
from	Originating phone number – also known as Caller Id
to	The destination number where the call is bridged
result	Result Code
msg	Textual description of Result Code
timestamp	UTC timestamp at which the response was generated

Forward Call

This API is called to forward bridged call leg.

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

PUT https://api.enablex.io/voice/v1/call/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58/forward
Authorization: Basic xxxxxx
Content-Type: application/json 

{ 
	"from": "CLI number",		// Valid CLI
        "to": "Destination number”
}

Key	Description	Constraints
from	Originating phone number – also known as Caller Id	Mandatory
to	The Destination Number	Mandator

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

Response Example: 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"
}

Key	Description
voice_id	Voice instance of the voice service call
from	Originating phone number – also known as Caller Id
to	The destination number where the call is bridged
status	State of the forward request. Possible states are: failed, success
timestamp	UTC timestamp at which the response was generated

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

Key	Description
voice_id	Unique call identifier
msg	Textual description on failure
timestamp	UTC timestamp at which the response was generated

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

Key	Description
voice_id	Voice instance of the voice service call
from	Originating phone number – also known as Caller Id
to	The destination number where the call is bridged
result	Result Code
msg	Textual description of Result Code
timestamp	UTC timestamp at which the response was generated

Play Voice Prompt

This API is called to Play prompts in the call. This command can be used to play prompts from TTS engine or stored pre-recorded prompt or from the remote URL. Action describes the start and stop play.

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

PUT https://api.enablex.io/voice/v1/call/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58/play
Authorization: Basic xxxxxx
Content-Type: application/json 
{
  //Play parameters
  "prompt_name":"prompt file name to be played",
  // or
  "text": "text to be played"
  “language”: “es-US",
  “voice”: "female",
  “dtmf”: true  
  "prompt_ref":"welcom_ref" // optional parameter for user reference.
  //asr parameter
  "asr": true  // user input via speech
  start_timeout :10 // initial silence timeout before user start speaking
  recognizer_timeout: 1 // wait timer before recognizer returns the result.
}

Key	Description	Constraints
prompt_name	Identifier of the prompt as configured on the portal.	Required if text is not used
text	Text to be played by the TTS. Either text or prompt will be be played	Required if prompt_name is not used
voice	For TTS only. Possible value is male or female	Mandatory if text is used.
language	Language to be spoken	Mandatory if the text is used
dtmf	If dtmf is true, it will wait for digits	Optional
prompt_ref	User specified prompt_ref	Optional
asr	IVR via speech recognition enabled.	Optional
start_timeout	Initial Silence Timeout before user start speaking.   Range : 1 – 10 seconds.  Default : 10 seconds.	Optional
recognizer_timeout	Wait before the voice server returns the result after silence.  Range : 1 – 10 seconds.  Default : 2 seconds.	Optional

Try Open API Tools…

Response: Response to REST will be the standard response.

Success Response Example: HTTPS  200  Accepted

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

Key	Description
playstate	initiated
play_id	Player identifier
voice_id	Unique call identifier
timestamp	UTC timestamp at the time response was generated

Events: The event will be called upon a Webhook

{ 
	“voice_id”: a8e3607c-46a1-43f6-b0be-f3ead722a6b1,
	"from": "CLI number", 
	"to" : "Destination number", 
	“play_id” “fdgdfg451c0-8f2a-4fe8-b5ef-9addgdg58”,
	“playstate”:  ”playfinished| “failed”|”digitcollected”|”menutimeout”,
	”prompt_ref”:”optional prompt_ref”,
	“digit”: 12345, 
	"timestamp": "2020-02-16T10:52:00Z" 
}

Key	Description
voice_id	Unique call identifier
play_id	Unique PlayId returned to indicate action
playstate	State of the current action: playfnished: Completed the play prompt digitcollected: user have provided DTMF for voice menu prompt menutimeout: user haven’t provided any DTMF for voice menu prompt failed: Could not play the prompt
prompt_ref	User specified prompt_ref
digit	DTMF digits collected, in case playstate in digitcollected
timestamp	UTC timestamp at the time response was generated

Error Response: API returns below error response in case of failure. All error responses will follow the standard HTTP error format and error code i.e. HTTPS 4**, 5**.

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

Key	Description
voice_id	Voice Call Identifier
play_id	Player identifier
result	Result Code
msg	Text Description of Result Code
timestamp	UTC timestamp at the time response was generated

Error Response: HTTPS 405 Method Not allowed. Voice Server returns this error when the call is in bridged mode and cannot play the prompt

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

Error Response: HTTPS 406 Not acceptable. Voice Server returns this error when the voice/language is not supported for the text-to-speech conversion

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

Error Response: HTTPS 408 request pending. Voice server returns this error response when the text to speech conversion fails.

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

Error Response: HTTPS 400 bad request. Voice server returns this error when the media request failed

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

Error Response: HTTPS 503 Server not available. Voice server returns this error response when the text to speech conversion fails.

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

Bridge Call

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

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

Request Example

PUT  https://api.enablex.io/voice/v1/call/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58/connect
Authorization: Basic xxxxxx
Content-Type: application/json 

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

Key	Description	Constraints
from	Originating phone number – also known as Caller Id	Mandatory
to	The destination number or SIP URI	Mandatory

Try Open API Tool…

Response: HTTPS 200 Accepted. Response to REST will be the standard response

{
	"voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
	"bridge_id":  "xxxxx",  
	"state": “Initiated”  |  “failed”,  
	"from": "CLI number",
	"to" : "Destination number"
	"timeStamp": "2017-02-16T10:52:00Z"
 }

Key	Description
voice_id	Voice instance of the voice service call.
bridge_id	Unique identifier for the Bridge
state	State of the bridge request. Possible values initiated or failed.
from	Valid CLI which is used as Caller Id for this call.
to	The destination number where the call is bridged.
timestamp	UTC timestamp at the time response was generated

Events: Event will be called upon a Webhook provided by application server using API

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

Key	Description
voice_id	Unique call identifier
state	bridging : if the other end is ringing bridged : If the call is accepted by the other party bridge_failed : Failed to bridge the call. bridge_disconnected : if the call is disconnected by the bridged number, disconnected : If the original participant disconnected the call.
from	Originating phone number – also known as Caller Id
to	The destination number where the call is bridged.
timestamp	UTC timestamp at the time response was generated

Error: Bridge API returns below error in case of failure. All error responses will follow the standard HTTP error format and error code. The JSON body of the response will highlight the exact error that occurred and it’s description.

Error Response: HTTPS 404 Not Found. Voice Server returns this error response when Outbound/Inbound Service is not configured for the Number

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

Error Response: HTTPS 404 Phone Number Not Found. Voice Service returns this error when the CLI number does not have any service configured

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

Analyze Call

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

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

Request Example:

GET  https://api.enablex.io/voice/v1/call/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58
Authorization: Basic XXXXXXXX 

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

Key	Description
voice_id	Unique call identifier
state	State of call after the current action: Connected : Call is running and is in progress In progress : Call is not yet connected … could be in ringing or attempting IVR : Call is connected and IVR is being played
from	Originating phone number – also known as Caller Id
to	Destination Number
timestamp	UTC timestamp at the time response was generated

Try Open API Tool...

Error Response: All error responses will follow the standard HTTP error format and error code. The JSON body of the response will highlight the exact error that occurred and it’s description

HTTPS  400 .      //Or other HTTP result on the REST 
{
	"voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",  
	“from”: "CLI number",
	“to”: "Destination number",
	"result": "Number",
	"msg": "",
	"timestamp": "2017-02-16T10:52:00Z"
}

Call Hold-Unhold API

This API is called to Hold/Resume a bridged channel and to play music on hold.  

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

Request Example: To hold bridged call leg

POST https://api.enablex.io/voice/v1/call/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58/hold
Authorization: Basic xxxxxx
Content-Type: application/json
{
"hold": true,
OR
“hold”: false
}

hold

true: to hold the bridged call leg. false: to resume the bridged call leg.

Mandatory

Try Open API Tool…

Start / Stop Call Recording

This API is called to start or stop Recording on a live call.

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

Request Example: To start call recording

PUT https://api.enablex.io/voice/v1/call/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58/recording
Authorization: Basic xxxxxx
Content-Type: application/json 
 
{
	"start": true,
	"recording_name": "my_voice_recording" 
}

Try Open API Tool…

Request Example: To stop call recording

PUT https://api.enablex.io/voice/v1/call/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58/recording
Authorization: Basic xxxxxx
Content-Type: application/json 
 
{
	"stop": true 
}

Key	Description	Constraint
start	Boolean. Required to start recording; set to true.	Required
recording_name	If User specifies recording_name and any recording file with same name already exist, the request will fail	Optional
stop	Boolean. Required to stop recording; set to true.	Required

Response: Immediate response if the server 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" 
}

Key	Description
voice_id	Unique call identifier
recording_id	Unique recording identifier
state	success – to know recording started successfully
msg	Failure description (blank in case of success)
timestamp	UTC timestamp at the time response was generated

Error Response: HTTPS 500. Voice Service returns this error when it fails to start 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 various progression of the recording will be sent back to application via Event URLs.

{
         "voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",  
         "recording_id": "8f2a-4fe8-b5ef-9a330",
         “state”: “started”, /* started,  completed, failed */
         “msg”: "text",
         "timestamp": "2017-02-16T10:52:00Z"
}

Key	Description
voice_id	Unique call identifier
recording_id	Unique recording identifier
state	State of call after the current action: started—Recording started completed—Recording completed failed—recording failed for reason code
msg	Failure description (blank in case of success)
timestamp	UTC timestamp at the time response was generated

Retrieve Call Recording

This API is used to pull Recorded File(s) by the client app.

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

GET https://api.enablex.io/v1/recording/1aa71c0-8f2a-4fe8-b5ef-9a330454ef58
Authorization: Basic XXXXXXXX

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

Error Response: HTTPS  404 Not Found

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

Key	Description
result	Result Code
msg	Textual description of Result code

Hang-Up Call

This API is called to Hang up or disconnect the call.

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

Request Example: To hangup call

DELETE https://api.enablex.io/v1/call/1aa71c0-8f2a-4fe8-b5ef-9a330454ef58
Authorization: Basic XXXXXXXX

Try Ope API Tool…

Error Response: All error responses will follow the standard HTTP error format and error code. The JSON body of the response will highlight exact error that occurred and it’s description. Please see Erro codes here.

Response Example:

{
	“voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
	“state”:success,
	"from": "CLI number",
	"to": "Destination number",
	"channel_id": "xxxx", //channel id associated with the call leg
	"timeStamp": "2020-02-16T10:52:00Z"
 }

Events: If the event_url is provided, the system will let the application know regarding the status of disconnect

{
	 "voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",  
	 “state”: “Disconnected”,
	 "timeStamp": "2020-02-16T10:52:00Z"
}

Key	Description
voice_id	A unique identifier on which the disconnect call is invoked.
state	Disconnected or error (Call could fail for invalid parameters or if call does not exist)