Table of Contents

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

Incoming call is always accepted by the Voice service. 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 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.

Example: Incoming Event JSON

{
	“voice_id”: “f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58”,
	“state”: “Incomingcall”,
	“from”: “CLI number”,
	“to”: “Called number”,
	“channel_id”:
	“timestamp: “2020-02-16T10:52:00Z”
}
KeyDescription
voice_idvoice_id of the incoming call. This identification
shall be used for all further requests to
the server.
stateIncoming 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
fromOriginating phone number – also known as Caller Id
toThe number to which the call is received, the Phone number assigned to voice service for the project.
timestampTimestamp at which the call is received

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": "Called number", 
	“action_on_connect”: {
		“play”: {   
			“prompt_name”:"prompt_name"
		}, // Or  
		{ 
			“text”: "your prompt here"
			“language”: “es-US”,
			“voice”: "female"
		},               
		event_url”: https://yourserver.com/webhook
	}
}
Object/KeyDescriptionConstraints
nameOptional parameter to name this service Optional
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.Optional
auto_recordRecording by default or on commandOptional
fromThe CLI assigned on the outbound number. This number is matched with the configured number. Mandatory
toDestination numberMandatory
action_on_connect If set, prompt will be played automatically when destination number is connectedOptional
actionSpecifies the action to perform when an outbound call is
connected. Action, could either be to connect the cal or to bridge the call with one more participant or play voice prompt or voice menu
Optional
prompt_namePlays the prompt that has been uploaded with Prompt Id
through portal provisioning
Optional
textTTS to play the prompt according to the parameter defined as following parameters belowOptional
languageThe preferred spoken language for TTS Conditional, if text
is supported
voiceVoice genderConditional. Need to
be there if “text” is present.
event_urlWebhook URL to be called for the application to take controlOptional

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”,	// Reason code if failed ; else success                             
	“description”: string,     
	“owner_ref”:		// User defined Id                              
	“time_stamp": "2020-02-16T10:52:00Z"              
}
KeyDescription
voice_idVoice Call Identifier
stateInitiated
descriptionTextual 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 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": 9,
	"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”,
        "from": "31644556677",
        "to": "31612345678",
        "channel_id": "xxxx"//channel id associated with the call leg
        "timestamp": "2020-02-16T10:52:00Z",
}
KeyDescription
voice_idvoice ID is a unique identifier created when a call is made.
This identification shall be used for all subsequent requests to the server.
stateCall state events while connecting the call.
ringing: Receiving ringing tone from called party
connected: Call is accepted
rejected: Call was not answered or declined by called party
voicemail: Call was connected to voice mail
from Originating number (typically configured number) used as the CLI
toDestination number (aka Called party number)
channel_idChannel id associated with the call leg
timestampEvent’s timestamp created by server

Hang-Up Call

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

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

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

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": "99999999999",
	"to": "8888888888",
	"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"
}
KeyDescription
voice_idVoice ID is a unique identifier on which the disconnect call is invoked.

Bridge Call

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

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

Request Example

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

{
	“connect”{
		"from": "9999999999",
		"to" : "8888888888"
	}
}
KeyDescriptionConstraints
fromA valid caller id. The call will be connected with the following CLIMandatory
toThe destination number or SIP URIMandatory

Response: Response to REST will be the standard response

{
	"voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
	"channel_id":  "xxxxx", //unique channel id
	"state": “Initiated”  |  “failed”,  
	“description”: "message",
	"from": "9999999999",
	"to" : "8888888888"
	"timeStamp": "2017-02-16T10:52:00Z"
 }
KeyDescription
voice_idVoice instance of the voice service call.
channel_id unique identifier for the channel
stateState of the bridge request
descriptionDescription of the failure in case the call failed.
fromValid CLI which is used as Caller Id for this call.
toThe destination number where the call is bridged.
timestampUTC timestamp at the time 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 the exact error that occurred and it’s description.

HTTPS:// 4xx //Or other HTTP result on the REST 
{
	"voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
	"bridge_id": "",
	"state": “failed”,  
	"from": "9999999999",
	"to" : "8888888888",
	"timeStamp": "2017-02-16T10:52:00Z",
	"result": code,
	"msg": "Description"
}

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

{
	"voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58", // Call_Id
	“state":  "briding" | "bridge_disconnected" | "bridged",
	"from": "9999999999",
	"to" : "8888888888",
	"timestamp": "2017-02-16T10:52:00Z"
 }
KeyDescription
voice_idUnique call identifier
stateBridging -> if the other end is ringing
Bridged -> If the call is accepted by the other party
Bridge_disconnected -> if the call is disconnected by the bridged number,
Disconnected: If the original participant disconnected the call.
from“CLI number”.
toThe destination number where the call is bridged.
timestampUTC timestamp at the time response was generated

Analyse Call

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

API Route: https://voice.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": "9999999999",
	"to" : "8888888888",
	"timestamp": "2017-02-16T10:52:00Z"
}  
KeyDescription
voice_idUnique call identifier
stateState 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
fromCall originating number
toDestination Number
timestampUTC timestamp at the time 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 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”: "Called number",
	"result": "Number",
	"msg": "",
	"timestamp": "2017-02-16T10:52:00Z"
}

Record Call

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

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

{
	“voice_id”: “f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58”,
	“state”: “connected” | “In progress” | “IVR” ,
	“direction”: “Inbound” | “Outbound”,
	"from": "9999999999",
	"to" : "8888888888",
	“timestamp”: “2017-02-16T10:52:00Z”
}
KeyDescriptionConstraint
recording_name If User specifies recording_name and any recording file with same name already exist, the request will fail Optional

Response: Immediate response if the server has accepted the request from the client

{
         “state”: "success",
         “description”: "text" ,
         "voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",  
         “recording_id”: “uniquerecording identifier”,
         "timeStamp": "2017-02-16T10:52:00Z" 
}

Errors:

{ 
	“state”: ”failed” 
	“description”: text 
	“voice_id”: “f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58”,  
	"recording_id": "", // If applicable
	“result”: "Code"
	“msg”: ""
} 

Events: Events of various progression of the recording will be sent back to the application via Even URLs

{
         "voice_id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",  
         "recording_id": "8f2a-4fe8-b5ef-9a330",
         “state”: “started”, /* started,  completed, failed */
         “description”: "text",
         "timestamp": "2017-02-16T10:52:00Z"
}
KeyDescription
voice_idUnique call identifier
recording_idUnique recording identifier
stateState of call after the current action:
started—Recording started
completed—Recording completed
failed—recording failed for reason code
descriptionFailure description (blank in case of success)
timestampUTC timestamp at the time response was generated