EPICODE iraDialer API

Version- v1.5.1.0

Date: 13-Mar-2023

EPICODE

1 Overview

The Epicode iraDialer API allows users to create rich outbound dialler applications with the simplicity of simple HTTP APIs. With these APIs one can:

Control the flow of outbound calls with JSON driven HTTP APIs.
Register webhooks to track the call progress.
Use the in built CPA engine to identify if the call is answered by a human or by an answering machine.
Play an audio file to the call.
Use the in-built Text-to-speech engine to play dynamic messages to the call.

Each API is an HTTP POST request. The following sections mention the HTTP method, the target URL, the attributes expected in the request body json and the attributes in the response body.

2 Authentication

Epicode APIs require authentication to be done using an Bearer Auth token sent in the Authorization Header.

Authorization: Bearer AUTH_TOKEN

For example, if the auth token provided to you is “dGVzdF9rZXk6dGVzdF9zZWNyZXQ=“, then the Authorization Header will look like below:

Authorization: Bearer dGVzdF9rZXk6dGVzdF9zZWNyZXQ=

All APIs will only work if a valid token is present in the authorization header of the request.

If an API request is made without the Authorization token or with an invalid Authorization token, the response will be the ones shown below respectively.

No Auth Token

{

"statusCode": 401,
"error": "Unauthorized",
"message": "Missing authorization header"
}

Invalid Auth Token

{
"statusCode": 401,
"error": "Unauthorized",
"message": "Invalid authorization header"
}

3 APIs of iraDialer

3.1 Set CPA parameters

This API allows configuration of the various parameters which controls the behaviour of the call progress analysis engine. Some prominent configurations that can be set are:

Time limit for first detection.
The specific frequencies to detect other than identifying humans and answering machines.
Welcome message to play on call establishment. It is recommended to play a short beep of a few milliseconds even if no message is required to be played since some carriers like Amazon Chime require RTP packets to be transmitted both ways immediately after call establishment.
The detection event on which the CPA engine can stop the analysis.
Total analysis time limit.

Each API user (identified by the auth token) can create multiple configurations with different names. The configuration to use for a call should be specified in the makecall API which is covered in the upcoming sections.

3.1.1 Request

POST	https://webserver/api/setcpaparams/

3.1.2 Request Body (application/json)

Key	Description	Example	Default
request_name REQUIRED \| string	Specify the request name	set_cpa_params	None
tenant_id REQUIRED \| string	Name of the licensee	acme	None
api_version REQUIRED \| string	Use 1.0 or 1.1	1.1	None
conﬁg_name REQUIRED \| string	Unique name for the conﬁguration	“my_setup”	None
analysis REQUIRED \| string	Name of the call progress analysis	amd	None
min_ambient_energy integer	Threshold that separates perfect initial silence and ambient silence	1	2
initial_silence_ignore integer	If the energy level is lower than minimum ambient energy, ignore the RTP packets	5000	750
log_rtp_history string	Log the history of rtp packets sent. Must be one of yes, no	yes	no
tones object(key, value pairs)	This is optional, any beeps will emit BP by default. Tones are speciﬁed as frequency and tolerance.	{"FX" : "2100\|5", "MD" : "1662\|5" "BP" : "1000\|10"}	{}
log_voice string	Tells the system whether or not to record and store the analysis stream. Must be one of yes, no	“yes”	“no”
break_events string	Comma separated list of frequencies or events on which the CPA analysis can stop.	“FX,MD,AM”	None
total_timeout integer	The time in milliseconds at which the analysis will stop.	20000	15000
silence_detect_limit integer	Detect silence after initial AM/LV detection. Send SL after the detect limit. Set 0 for no detection. Minimum value 1000 and maximum value is 10000, in milliseconds.	3000	2000
beep_to_silence_gap integer	Detect if silence follows a beep after a certain gap, speciﬁed in milliseconds. Default is 0, then it won’t detect.	1500	0
beep_is_am integer	Consider any beep before the AM/LV event as AM.	no	yes
detect_dtmf integer	Detect DTMF	no	yes

3.1.3 Sample Request

{

"request_name" : "set_cpa_params",

"tenant_id" : "acme",

"api_version" : "1.0",

"config_name" : "my_setup",

"time_limit" : 1750,

"sensitivity" : 5,

"log_voice" : "no",

"tones" :

{

"FX" : "2100|5",

"MD" : "1662|5"

"break_events" : "FX,MD,BP",

"log_top_freq" : 3,

"total_timeout" : "20000"

3.1.4 Response Body (application/json)

Field

Description

statusCode

integer

HTTP status code.

Ex. 200, 400, 401, 404, 500

error

string

Will be present when statusCode is not 200.

One of “Bad Request”, “Not Found”, “Unauthorized”

message

string

Human readable response description.

Ex. “OK”, “Method not allowed”, “ 'config_name' is a required property”

3.2 Create an outgoing call

This API dials a number to initiate an outbound call. There is option to enable call progress analysis (CPA) on the call through the attribute enable_cpa.

When enable_cpa is True:

The moment the call is answered, Epicode’s CPA engine starts analysing the audio stream. The detection is made within the configured time_limit which can be set as an attribute in setcpaparams. The event_url will be triggered notifying whether the call is identified as human(LV), answering machine(AM), Fax(FX) or Modem(MD). The call continues to be parked and the callee hears nothing.
The CPA engine continues to analyse the stream even after the AMD detection (AM or LV) until the total time since call answer reaches detection_timeout seconds or one of the break_events is matched. At this time it only looks for a beep of the configured tones. If the beep is detected within this time, the same will be notified to the event_url. Typically any voicemail message will not be longer than 20 seconds.

If enable_cpa is True, the attribute config_name should be set which points at the configuration created using the request Set CPA Params covered earlier.

The response fields, the response format and the different events which the event_url will receive are explained in the following sections.

3.2.1 Request

POST	https://webserver/api/makecall/

3.2.2 Request Body (application/json)

Key	Description	Example	Default
gateway REQUIRED \| string	The gateway to use for sending the call out.	“sofia/gateway/chime”	None
to REQUIRED \| string	Phone number in E.164 format to dial	“12345678901”	None
from REQUIRED \| string	Phone numbers in E.164 format to set as from header	“12345678901”	None
event_url REQUIRED \| string	Call progress events are sent to this URL as a POST request.	"https://example.com/event"	None
enable_cpa string	Tells the system whether or not to perform call progress analysis on the call to identify answering machines. Must be one of yes, no	“yes”	“no”
dial_timeout	Specifies the timeout for answering the call	15	30
join_conf string	Tells the system whether the call must be parked in a newly created conference.	“yes”	“no”
add_to_conf string	Specify a call_uuid to add to the conference just created. Used only when join_conf is yes.		None
config_name string	The name of the saved config to be used which was set in the previous request. REQUIRED when enable_cpa is yes	“my_setup”	None
call_params object(key, value pairs)	Optional call parameters which will be set as SIP headers.	{ “queue_id”:”Test” “agent_id”:”12345” }	None

3.2.3 Sample Request

{
"gateway": "sofia/gateway/chime",
"to": "+xxxxxxxxxx",
"from": "+yyyyyyyyyy",
"event_url": "https://example.com/event",
"join_conf": "yes",
"enable_cpa": "no",
"call_params": {
"agent_id": "12345",
"queue_id": "Test"
}
}

3.2.4 Response Body (application/json)

Field

Description

statusCode

integer

HTTP status code.

Ex. 200, 400, 401, 404

error

string

Will be present when statusCode is not 200.

One of “Bad Request”, “Not Found”, “Unauthorized”

message

string

Human readable response description.

Ex. “OK”, “Method not allowed”, “ 'from' is a required property”

call_uuid

string

Unique call identifier. Will be returned only if the statusCode is 200. You will use the call_uuid for all the requests for individual live calls.

conf_uuid

string

Unique conference ID. Will only be returned if enable_cpa is set to “False” in the request. The conf_uuid will be required to add a call to a conference or to transfer a call from one conference to another.

3.2.5 Sample Responses

Success sample for a request with "enable_cpa" = "True"

{
"statusCode": 200,
"message": "OK",
"call_uuid": "e55f849a-84c0-43ec-9da5-3928519dd44b"
}

Success sample for a request with "enable_cpa" = "False"

{
"statusCode": 200,
"message": "OK",
"call_uuid": "d9ae995c-d3fc-4c43-bd89-cf045f3f7d72",
"conf_uuid": "CONF-e35f1f5d-02d8-48a0-83bf-f1704123acac"
}

Failure samples

{
"statusCode": 400,
"error": "Bad Request",
"message": "'from' is a required property"
}

3.2.6 Webhook events

As the call progresses through various states, Epicode will send event objects to your event_url. The following table shows the possible values for the status field of the event object.

Event name	Description
ringing	The destination has confirmed that the call is ringing
answered	The destination has answered the call
cpa_detection	This event is emitted when CPA engine makes a detection. An attribute event_data will have the detection outcome. The possible values for event_data are LV (live voice), AM (answering machine), FX (Fax), MD(Modem), BP (Beep), DT(Detection timeout).
hangup	When a call ends. This event_data will have a reason_code which gives the hangup cause. The reason_code would be one of the hangup cause enumerations from Epicode Hangup Causes

3.2.7 Sample event objects

{
"timestamp": "2019-11-04T18:21:45.564Z",
"tenant_id": "epicode_demo",
"call_uuid": "e55f849a-84c0-43ec-9da5-3928519dd44b",
"event": "ringing"
}

{
"timestamp": "2019-11-04T18:21:59.943Z",
"tenant_id": "epicode_demo",
"call_uuid": "e55f849a-84c0-43ec-9da5-3928519dd44b",
"event": "cpa_detection",
"event_data": "LV"
}

{
    "timestamp": "2019-11-04T18:24:23.745Z",
    "tenant_id": "epicode_demo",
    "call_uuid": "e55f849a-84c0-43ec-9da5-3928519dd44b",
    "event": "hangup",
    "event_data": "NORMAL_CLEARING"
}

3.3 Bridge the call into a conference

To transfer a call from one conference bridge to another, call the bridge action with new conf_uuid. To have a multiparty conference, bridge multiple call_uuids to a conf_uuid. If conf_uuid is not mentioned, the API will create a new conference.

3.3.1 Request

POST	https://webserver/api/bridgecall/

3.3.2 Request Body (application/json)

Key	Description	Example
call_uuid REQUIRED \| string	Unique identifier of the call.	‘e55f849a-84c0-43ec-9da5-3928519dd44b’
conf_uuid string	Conference to bridge with	‘CONF-e35f1f5d-02d8-48a0-83bf-f1704123acac’
event_url string	Call progress events are sent to this URL as a POST request.	"https://example.com/event"	None

3.3.3 Sample Request

{
"call_uuid": "e55f849a-84c0-43ec-9da5-3928519dd44b",
"conf_uuid": "CONF-e35f1f5d-02d8-48a0-83bf-f1704123acac"
}

3.3.4 Response Body (application/json)

Field

Description

statusCode

integer

HTTP status code.

Ex. 200, 400, 404

error

string

Will be present when statusCode is not 200.

One of “Bad Request”, “Not Found”, “missing authorization header”

message

string

Human readable response description.

Ex. “OK”, “Route GET:/api/bridgecall/ not found”, “body should have required property 'call_uuid'”

3.4 Play a file into the call

Play the given filename into the call. Once the play is complete, event play_done will be sent just once to the call_back specified during making the call.

3.4.1 Request

POST	https://webserver/api/playfile/

3.4.2 Request Body (application/json)

Key	Description	Example	Default
call_uuid REQUIRED \| string	Unique identifier of the call.	‘e55f849a-84c0-43ec-9da5-3928519dd44b’	None
stop_on_key string	Should the play stop at a key press	‘yes’	‘yes’
loop_count int	How many times to play	2	1
filename REQUIRED \| string	wav/mp3 filename to play	“Welcome.wav”	None
event_url string	Call progress events are sent to this URL as a POST request.	"https://example.com/event"	None

3.4.3 Sample Request

{
    "call_uuid": "e55f849a-84c0-43ec-9da5-3928519dd44b",
    "filename": "Welcome.wav",
    "stop_on_key": "no",
    "loop_count": "2"
}

3.4.4 Response Body (application/json)

Field

Description

statusCode

integer

HTTP status code.

Ex. 200, 400, 404

error

string

Will be present when statusCode is not 200.

One of “Bad Request”, “Not Found”, “missing authorization header”

message

string

Human readable response description.

Ex. “OK”, “Route GET:/api/playfile/ not found”, “body should have required property 'call_uuid'”

3.5 Play a text into the call

Play the given text to the call using a Text-to-Speech(TTS) engine. Once the play is complete, event play_done will be sent just once to the call_back specified during making the call.

3.5.1 Request

POST	https://webserver/api/playtts/

3.5.2 Request Body (application/json)

Key	Description	Example	Default
call_uuid REQUIRED \| string	Unique identifier of the call.	‘e55f849a-84c0-43ec-9da5-3928519dd44b’	None
stop_on_key string	Should the play stop at a key press	‘yes’	‘yes’
loop_count int	How many times to play	2	1
text REQUIRED \| string	text to play	“Welcome to Epicode Demo”	None
tts_voice string	Voice to be used	“Slt” or “rms” or “awb” or kal (works with flite)	“slt”
tts_engine string	TTS engine name	“flite” or “polly” (free) (paid third party)	“flite”
event_url string	Call progress events are sent to this URL as a POST request.	"https://example.com/event"	None

3.5.3 Sample Request

{
    "call_uuid": "e55f849a-84c0-43ec-9da5-3928519dd44b",
    "text" : "All agents are busy",
    "tts_engine" : "flite",
    "tts_voice" : "slt",
    "stop_on_key" : "yes",
    "loop_count" : "1"
}

3.6 Play a url into the call

If the recording is accessible through a URL, this API can be used to play it to the call. Once the play is complete, event play_done will be sent just once to the call_back specified during making the call.

3.6.1 Request

POST	https://webserver/api/playurl/

3.6.2 Request Body (application/json)

Key	Description	Example	Default
call_uuid REQUIRED \| string	Unique identifier of the call.	‘e55f849a-84c0-43ec-9da5-3928519dd44b’	None
stop_on_key string	Should the play stop at a key press	‘yes’	‘yes’
loop_count int	How many times to play	2	1
url REQUIRED \| string	wav/mp3 url to play. If “https://” is not prefixed to the url, the system will make a “http” request.	“https://somewhere.com/Welcome.mp3”	None
event_url string	Call progress events are sent to this URL as a POST request.	"https://example.com/event"	None

3.6.3 Sample Request

{
    "call_uuid": "e55f849a-84c0-43ec-9da5-3928519dd44b",
    "url": "https://somewhere.com/Welcome.mp3",
    "stop_on_key": "no",
    "loop_count": "2"
}

3.7 Stop playing audio

Stops all the audio scheduled to play on the call associated with the passed call_uuid.

3.7.1 Request

POST	https://webserver/api/stopplay/

3.7.2 Request Body (application/json)

Key

Description

Example

call_uuid

REQUIRED | string

Unique identifier of the call.

‘e55f849a-84c0-43ec-9da5-3928519dd44b’

event_url

string

Call progress events are sent to this URL as a POST request.

"https://example.com/event"

None

3.7.3 Sample Request

{
"call_uuid": "e55f849a-84c0-43ec-9da5-3928519dd44b"
}

3.8 Drop the call

Drop the call associated with the passed call_uuid.

3.8.1 Request

POST	https://webserver/api/dropcall/

3.8.2 Request Body (application/json)

Key

Description

Example

call_uuid

REQUIRED | string

Unique identifier of the call.

‘e55f849a-84c0-43ec-9da5-3928519dd44b’

event_url

string

Call progress events are sent to this URL as a POST request.

"https://example.com/event"

None

3.8.3 Sample Request

{
"call_uuid": "e55f849a-84c0-43ec-9da5-3928519dd44b",
}

3.9 Mute a call (can’t hear the person)

Mute all the audio coming from the call associated with the passed call_uuid.

3.9.1 Request

POST	https://webserver/api/mute/

3.9.2 Request Body (application/json)

Key

Description

Example

call_uuid

REQUIRED | string

Unique identifier of the call.

‘e55f849a-84c0-43ec-9da5-3928519dd44b’

event_url

string

Call progress events are sent to this URL as a POST request.

"https://example.com/event"

None

3.9.3 Sample Request

{
"call_uuid": "e55f849a-84c0-43ec-9da5-3928519dd44b"

}

3.10 Unmute the call

Unmute all the audio coming from the call associated with the passed call_uuid.

3.10.1 Request

POST	https://webserver/api/unmute/

3.10.2 Request Body (application/json)

Key

Description

Example

call_uuid

REQUIRED | string

Unique identifier of the call.

‘e55f849a-84c0-43ec-9da5-3928519dd44b’

event_url

string

Call progress events are sent to this URL as a POST request.

"https://example.com/event"

None

3.10.3 Sample Request

{
"call_uuid": "e55f849a-84c0-43ec-9da5-3928519dd44b"

}

3.11 Deaf or Turn On Ear Muff (the person can’t hear anyone)

Block all the audio going to the call associated with the passed call_uuid.

3.11.1 Request

POST	https://webserver/api/earmuffon/ https://webserver/api/deafcall/

3.11.2 Request Body (application/json)

Key

Description

Example

call_uuid

REQUIRED | string

Unique identifier of the call.

‘e55f849a-84c0-43ec-9da5-3928519dd44b’

event_url

string

Call progress events are sent to this URL as a POST request.

"https://example.com/event"

None

3.11.3 Sample Request

{
"call_uuid": "e55f849a-84c0-43ec-9da5-3928519dd44b"

}

3.12 Undeaf or Turn Off Ear Muff

Unblock all the audio going to the call associated with the passed call_uuid.

3.12.1 Request

POST	https://webserver/api/earmuffoff/ https://webserver/api/undeafcall/

3.12.2 Request Body (application/json)

Key

Description

Example

call_uuid

REQUIRED | string

Unique identifier of the call.

‘e55f849a-84c0-43ec-9da5-3928519dd44b’

event_url

string

Call progress events are sent to this URL as a POST request.

"https://example.com/event"

None

3.12.3 Sample Request

{
"call_uuid": "e55f849a-84c0-43ec-9da5-3928519dd44b",

}

3.13 Get Call Details

Get call details related to the call specified by call_uuid

3.13.1 Request

POST	https://webserver/api/getcalldetails/

3.13.2 Request Body (application/json)

Key

Description

Example

call_uuid

REQUIRED | string

Unique identifier of the call.

‘e55f849a-84c0-43ec-9da5-3928519dd44b’

event_url

REQUIRED | string

Url where the DTMF will be sent

"https://example.com/event"

3.13.3 Sample Request

{
"call_uuid": "e55f849a-84c0-43ec-9da5-3928519dd44b"
}

3.14 Get Simple DTMF

Get a string of DTMF digits from the call associated with the passed call_uuid.

3.14.1 Request

POST	https://webserver/api/getsimpledtmf/

3.14.2 Request Body (application/json)

Key	Description	Example	Default
call_uuid REQUIRED \| string	Unique identifier of the call.	‘e55f849a-84c0-43ec-9da5-3928519dd44b’	None
event_url REQUIRED \| string	Url where the DTMF will be sent		None
var_name string	This name will passed to the url along with the data for IDing	“customer_id”	“”
digit_count int	How many digits to collect	5	1
timeout int	How long to wait until the digits are entered	15	10
term_keys string	A list of keys that can end the digit collection	“*” or “#”	empty

3.14.3 Sample Request

{
    "call_uuid": "e55f849a-84c0-43ec-9da5-3928519dd44b",
    "event_url" : "https://example.com/event",
    "var_name" : "data_name",
    "digit_count" : "5",
    "timeout" : "12",
    "term_keys" : "#"
}

3.15 Get Valid DTMF

Get a string of validated DTMF digits from the call associated with the passed call_uuid.

3.15.1 Request

POST	https://webserver/api/getvaliddtmf/

3.15.2 Request Body (application/json)

Key	Description	Example	Default
call_uuid REQUIRED \| string	Unique identifier of the call.	‘e55f849a-84c0-43ec-9da5-3928519dd44b’	None
event_url REQUIRED \| string	Url where the DTMF will be sent		None
var_name string	This name will passed to the url along with the data for IDing	“customer_id”	“”
minimum_digits int	The minimum digits that must be entered within the timeout	3	5
maximum_digits int	The maximum digits that can be entered	5	5
maximum_tries int	The maximum tries allowed for entering	1	3
timeout int	How long to wait until the digits are entered	15	10
term_keys string	A list of keys that can end the digit collection	“*” or “#”	“”
reg_expr string	Regular expression for validating the input	“5[0-9][0-9]”	“”
audio_type REQUIRED \| string	Specify if the audio source is tts, filename or url	“tts”	“”
prompt_message REQUIRED \| string	Prompt message played before accepting input	“Please enter your 5 digit code”	None
error_message string	Error message played after wrong input	“That is an invalid input”	“”
tts_voice string	Voice to be used	“slt” or “rms” or “awb” or “kal” (works with flite)	“slt”
tts_engine string	TTS engine name	“flite” or “polly” (free) (paid third party)	“flite”

3.15.3 Sample Request

{
    "call_uuid" : "b9aa5108-e1b4-4a8e-9afd-6f94f87a1202",
    "event_url" : "https://example.com/event",
    "var_name" : "data_name",
    "minimum_digits" : "5",
    "maximum_digits" : "5",
    "maximum_tries" : "3",
    "timeout" : "12",
    "term_keys" : "#",
    "reg_expr" : "",
    "audio_type" : "tts",
    "prompt_message" : "say: Please enter your 5 digit code",
    "error_message" : "say: That was invalid input",
    "tts_engine" : "flite",
    "tts_voice" : "slt"
}

3.16 Put a conference member on Hold

Put a conference member associated with the passed call_uuid on hold.

3.16.1 Request

POST	https://webserver/api/hold/

3.16.2 Request Body (application/json)

Key

Description

Example

call_uuid

REQUIRED | string

Unique identifier of the call.

‘e55f849a-84c0-43ec-9da5-3928519dd44b’

event_url

string

Call progress events are sent to this URL as a POST request.

"https://example.com/event"

None

3.16.3 Sample Request

{
"call_uuid": "e55f849a-84c0-43ec-9da5-3928519dd44b"

}

3.17 Remove conference member from Hold

Remove a conference member associated with the passed call_uuid from hold.

3.17.1 Request

POST	https://webserver/api/unhold/

3.17.2 Request Body (application/json)

Key

Description

Example

call_uuid

REQUIRED | string

Unique identifier of the call.

‘e55f849a-84c0-43ec-9da5-3928519dd44b’

event_url

string

Call progress events are sent to this URL as a POST request.

"https://example.com/event"

None

3.17.3 Sample Request

{
"call_uuid": "e55f849a-84c0-43ec-9da5-3928519dd44b"

}

3.18 Park the call

Remove a conferenced call and park it outside the conference.

3.18.1 Request

POST	https://webserver/api/parkcall/

3.18.2 Request Body (application/json)

Key

Description

Example

call_uuid

REQUIRED | string

Unique identifier of the call.

‘e55f849a-84c0-43ec-9da5-3928519dd44b’

event_url

string

Call progress events are sent to this URL as a POST request.

"https://example.com/event"

None

3.18.3 Sample Request

{
"call_uuid": "e55f849a-84c0-43ec-9da5-3928519dd44b"

}

3.19 Conference Multiple Calls

Add multiple calls into a new or existing conference

3.19.1 Request

POST	https://webserver/api/multiconf/

3.19.2 Request Body (application/json)

Key

Description

Example

Default

conf_uuid

REQUIRED | string

Unique identifier of the conference. Don’t reuse old conf_uuid for new conferences. Instead use CONF-<UUID> using a new V4 uuid.

‘CONF-e55f849a-84c0-43ec-9da5-3928519dd44b’

None

call_uuid

REQUIRED | string array

You can specify multiple call_uuid in a string array. The calls must exist.

["e55f849a-84c0-43ec-9da5-3928519dd44b",

"84273317-a222-4223-a93a-eb58a573a060",

"d1680a86-810d-4e67-ad49-760bbdc15e5d",...]

None

3.19.3 Sample Request

{
"conf_uuid": "CONF-eb7267bb-8eea-4483-933a-acf4166c96d9",

"call_uuid": ["e55f849a-84c0-43ec-9da5-3928519dd44b",

"84273317-a222-4223-a93a-eb58a573a060",

"d1680a86-810d-4e67-ad49-760bbdc15e5d",...]

}

3.20 Send DTMF to a call

Send a string of DTMF digits to a call

3.20.1 Request

POST	https://webserver/api/senddtmf/

3.20.2 Request Body (application/json)

Key

Description

Example

call_uuid

REQUIRED | string

Unique identifier of the call.

‘e55f849a-84c0-43ec-9da5-3928519dd44b’

digits

REQUIRED | string

String of one or more digits.

123

None

3.20.3 Sample Request

{
"call_uuid": "e55f849a-84c0-43ec-9da5-3928519dd44b",

"digits": "123"

}

3.21 Get system status

Get the configuration in use, service and license usage status.

3.21.1 Request

GET	https://webserver/api/status/json

This will return the status data in a json format to be consumed by applications

3.21.2 Browser request

GET	https://webserver/api/status/dashboard

This will show the status in a dashboard format and update the data once in every 10 seconds.

3.22 Get license status

Allows to check if the application has acquired licenses or not. Since the web service requests will all fail if the licenses are not acquired, this can be used as a periodic status check and ensure that requests are only sent to instances of the IraDialerWeb that have acquired the licenses.

3.22.1 Request

GET	https://webserver/api/status/check_license i

This will return status code 200 if license is acquired and 400 is license is not acquired.

3.23 Set ASR parameters

This API allows conﬁguration of the various parameters which controls the behavior of Automated Speech Recognition. Some prominent conﬁgurations that can be set are:

Total time limit for recognition.
Aggressiveness mode.
Name of the application that will process the audio by calling the ASR API like Lex.

Each API user (identiﬁed by the auth token) can create multiple conﬁgurations with diﬀerent names. The conﬁguration to use for a call should be speciﬁed in the start_asr API.

Request

POST	https://webserver/api/setasrparams/

Request Body (application/json)

Key	Description	Example	Default
conﬁg_name REQUIRED \| string	Unique name for the conﬁguration	“my_setup”	None
asr_application integer	The application that will process the audio	LexConnect	None
aggr_mode integer	The aggressiveness of voice activity detection. (1 or 2 or 3)	1	1
log_voice string	Tells the system whether or not to record and store the analysis stream. Must be one of yes, no	“yes”	“no”
total_timeout integer	The time in milliseconds at which the VAD will stop.	10000	20000

Sample Request

{

"config_name" : "my_setup", "asr_application" : "LexConnect", "log_voice" : "no",

"aggr_mode" : 1,

"total_timeout" : "20000"

}

3.24 Start ASR

This API starts the ASR by capturing the audio and sending it to the ASR application. The API does Voice Activity Detection and captures only the voice and not silence.

Request

GET	https://webserver/api/startasr i

Request Body (application/json)

Key

Description

Example

Default

conﬁg_name

REQUIRED | string

Unique name for the conﬁguration

“my_setup”

None

call_uuid

REQUIRED | string

Unique identiﬁer of the call.

‘e55f849a-84c0-43ec-9 da5-3928519dd44b’

Sample Request

{

"config_name" : "my_setup",

"call_uuid" : "e55f849a-84c0-43ec-9da5-3928519dd44b"

}

4 Appendix A: Change Log

4.1 Version 1.3.1 (Aug 13th 2020)

Added Hold and Unhold API
Cross-connect conferencing to enable High availability.
Playing TTS in conference bug fixed.
Inconsistent delivery of error messages via web event fixed.
Added status_code to every error web event.
Added event and status fields to every web event.

4.2 Version 1.3.2 (Aug 25th 2020)

The bridgecall API has been re-designed to handle multiple agents.
dded parkcall API.

4.3 Version 1.3.3 (Sep 6th 2020)

Added event_url option to all APIs
Added more error codes (123-127)
Support for https in playurl API
Added support for AWS polly

4.4 Version 1.3.9 (Feb 26th 2021)

Added support for ignoring initial silence.
Support for cloud based licensing.

4.5 Version 1.4.1 (April 23th 2021)

If the cloud license server is not accessible, 7 days temporary licenses are issued.
Http events to the event_url are sent from IraDialerAPI web service instead of dialer service.
Dialing threads now have their own pool.
Added call_quality event for each call for providing mos and quality values.
IraPass now supports HTTP proxy as well as Forward proxy.
WSGI server for the API web changed to cheroot.
Debian setup broken into irabase.deb, iradialer-light.deb and iracpa.deb.
TxPass discontinued, as IraPass also supports node-locked license.

4.6 Version 1.4.2 (May 4th 2021)

Patch for cross-connect gateway rebuild bug after a network disruption between AZs.
Additional error messages in hangup event for Chime and Twilio gateway.

4.7 Version 1.4.2.3 (May 22nd 2021)

WSGI server for the API web changed from cheroot to sanic ASGI.
Http event delivery enabled from iraDialer instead of web service.

4.8 Version 1.4.3.2 (July 14 2021)

Added multiconf API.
Added senddtmf API.
Five attempts will be made to deliver http events.
Event logging moved to iraDialer and logged using high speed spdlog.
Configuration setup cleaned up for consistency.
Excessive replication of transient states removed.
System health can be seen from the status web.
License reload can be forced via API.
Hive switched to core licensing.
Makecall request can specify dial timeout.
Application load balancing added to support more than two servers
Ringing event will deliver twilio call SID.

5.0 Version 1.5.0.0 (Feb 24 2023)

Added silence detection, to return SL if silence follows after initial AM/LV detection.
Added silence after the beep feature.

5.1 Version 1.5.0.0 (Mar 13 2023)

Upgraded the AMD engine to apiversion 1.1

5.2 Version 1.5.1.2 (August 17 2023)

1. Improved beep detection algorithm.

2. /status/check_license API has been added.

6 Appendix B: Status Code of errors

When the web event contains a status_code, it means an error has occurred. The status field will contain the detailed description. The status code will be one of the following:

Code	Status Code
100	Can't pick up CPA configuration. This happens if the dialer can’t find a matching CPA configuration for the call.
101	Could not initialize the analyser specified in the CPA configuration.
102	CPA initialization failed! This happens if RTP listener cannot be started.
103	File specified for playing was not found.
104	File play was interrupted.
105	Call disconnected while play was playing.
106	Error message returned by the media handler while playing a message.
107	The call_uuid mentioned in the API doesn’t exist.
108	The call_uuid mentioned in the API doesn’t exist anymore.
109	Tenant has used up all the available iraDial licenses [N/N].
110	All iraDial licenses have expired.
111	Tenant doesn't have any iraDial licenses installed.
112	Unable to use the iraDial licences.
113	Unknown error while trying to acquire iraDial license.
114	Call dialing failed. Check status for more details.
115	Call failed to originate, could be a throttling problem.
116	Record requested not found.
117	Call is in the conference, can't accept the DTMF.
118	Bridging into a brand new conference in the same dialer failed.
119	Bridging into an existing conference in the same dialer failed.
120	Bridging into the conference in another dialer failed.
121	Failed to move of the current conference before bridging
122	Failed to bridge into another dialer after moving out of current conference
123	Call Park failed since the call is already parked
124	Failed to park the call.
125	The requested API can only be called while in conference.
126	The requested action in the conference failed.
127	Error stopping play.
128	Invalid request.
129	Not able to set the CPA configuration
130	Not all parameters specified.
131	Unable to add a new call to the iraDialer.
132	Https error. Unable to send event over web.
133	No schema files found
134	Incorrectly formed json request
135	Request is not according to the schema
136	Null call_uuid/conf_uuid in the multiconf request
137	Call specified by call_uuid doesn’t exist or not in answered state
138	Send DTMF failed
200-235	Errors specific to getting DTMF. Check the status field for details.

6 Appendix C: Web callback events

Web Event	Description
originate	Dialing has been initiated
started	Call has been setup
ringing	Call is ringing
answered	Call is answered
hangup	Call is hang-up
cpa_configured	A new CPA configuration has been saved.
cpa_setup	CPA parameter has been loaded
cpa_detection	The CPA engine has detected a configured pattern
cpa_done	CPA process has ended
dtmf	An event related to dtmf, check status field for details
play_done	Play API completed playing.
error	Some error has occurred, check status_code field for the details
get_details	Reply to get_details API
parked	Call was moved out of the conference and parked
web_error	Unable to send event over the web.
CONF-add-member	New call is added to the conference
CONF-del-number	Call was removed from the conference
CONF-mute-member	Call was muted successfully
CONF-unmute-member	Call was unmuted successfully
CONF-deaf-member	Call was deafened successfully
CONF-undeaf-member	Call was un-deafened successfully
CONF-hold-member	Call was put to hold successfully
CONF-unhold-member	Call was removed from hold successfully
call_quality	Sent after the call ends, with mos and quality value

7 Appendix D: Epicode Hangup Causes

ITU-T Q.850 Code	SIP Equiv.	Enumeration	Cause	Description
0		UNSPECIFIED	Unspecified. No other cause codes applicable.	This is usually given by the router when none of the other codes apply. This cause usually occurs in the same type of situations as cause 1, cause 88, and cause 100.
1	404	UNALLOCATED_NUMBER	Unallocated (unassigned) number [Q.850 value 1]	This cause indicates that the called party cannot be reached because, although the called party number is in a valid format, it is not currently allocated (assigned).
2	404	NO_ROUTE_TRANSIT_NET	No route to specified transit network (national use) [Q.850]	This cause indicates that the equipment sending this cause has received a request to route the call through a particular transit network, which it does not recognize. The equipment sending this cause does not recognize the transit network either because the transit network does not exist or because that particular transit network, while it does exist, does not serve the equipment which is sending this cause.
3	404	NO_ROUTE_DESTINATION	No route to destination [Q.850]	This cause indicates that the called party cannot be reached because the network through which the call has been routed does not serve the destination desired. This cause is supported on a network dependent basis.
6		CHANNEL_UNACCEPTABLE	channel unacceptable [Q.850]	This cause indicates that the channel most recently identified is not acceptable to the sending entity for use in this call.
7		CALL_AWARDED_DELIVERED	call awarded, being delivered in an established channel [Q.850]	This cause indicates that the user has been awarded the incoming call, and that the incoming call is being connected to a channel already established to that user for similar calls (e.g. packet-mode x.25 virtual calls).
16		NORMAL_CLEARING	normal call clearing [Q.850]	This cause indicates that the call is being cleared because one of the users involved in the call has requested that the call be cleared. Under normal situations, the source of this cause is not the network.
17	486	USER_BUSY	user busy [Q.850]	This cause is used to indicate that the called party is unable to accept another call because the user busy condition has been encountered. This cause value may be generated by the called user or by the network. In the case of user determined user busy it is noted that the user equipment is compatible with the call.
18	408	NO_USER_RESPONSE	no user responding [Q.850]	This cause is used when a called party does not respond to a call establishment message with either an alerting or connect indication within the prescribed period of time allocated.
19	480	NO_ANSWER	no answer from user (user alerted) [Q.850]	This cause is used when the called party has been alerted but does not respond with a connect indication within a prescribed period of time. Note - This cause is not necessarily generated by Q.931 procedures but may be generated by internal network timers.
20	480	SUBSCRIBER_ABSENT	subscriber absent [Q.850]	This cause value is used when a mobile station has logged off, radio contact is not obtained with a mobile station or if a personal telecommunication user is temporarily not addressable at any user-network interface. Sofia SIP will normally raise USER_NOT_REGISTERED in such situations.
21	603	CALL_REJECTED	call rejected [Q.850]	This cause indicates that the equipment sending this cause does not wish to accept this call, although it could have accepted the call because the equipment sending this cause is neither busy nor incompatible. The network may also generate this cause, indicating that the call was cleared due to a supplementary service constraint. The diagnostic field may contain additional information about the supplementary service and reason for rejection.
22	410	NUMBER_CHANGED	number changed [Q.850]	This cause is returned to a calling party when the called party number indicated by the calling party is no longer assigned, The new called party number may optionally be included in the diagnostic field. If a network does not support this cause, cause no: 1, unallocated (unassigned) number shall be used.
23	410	REDIRECTION_TO_NEW_DESTINATION		This cause is used by a general ISUP protocol mechanism that can be invoked by an exchange that decides that the call should be set-up to a different called number. Such an exchange can invoke a redirection mechanism, by use of this cause value, to request a preceding exchange involved in the call to route the call to the new number.
25	483	EXCHANGE_ROUTING_ERROR		This cause indicates that the destination indicated by the user cannot be reached, because an intermediate exchange has released the call due to reaching a limit in executing the hop counter procedure. This cause is generated by an intermediate node, which when decrementing the hop counter value, gives the result 0.
27	502	DESTINATION_OUT_OF_ORDER	destination out of order [Q.850]	This cause indicates that the destination indicated by the user cannot be reached because the interface to the destination is not functioning correctly. The term "not functioning correctly" indicates that a signal message was unable to be delivered to the remote party; e.g. a physical layer or data link layer failure at the remote party, or user equipment off-line.
28	484	INVALID_NUMBER_FORMAT	invalid number format (address incomplete) [Q.850]	This cause indicates that the called party cannot be reached because the called party number is not in a valid format or is not complete.
29	501	FACILITY_REJECTED	facilities rejected [Q.850]	This cause is returned when a supplementary service requested by the user cannot be provide by the network.
30		RESPONSE_TO_STATUS_ENQUIRY	response to STATUS INQUIRY [Q.850]	This cause is included in the STATUS message when the reason for generating the STATUS message was the prior receipt of a STATUS INQUIRY.
31	480	NORMAL_UNSPECIFIED	normal, unspecified [Q.850]	This cause is used to report a normal event only when no other cause in the normal class applies.
34	503	NORMAL_CIRCUIT_CONGESTION	no circuit/channel available [Q.850]	This cause indicates that there is no appropriate circuit/channel presently available to handle the call.
38	503	NETWORK_OUT_OF_ORDER	network out of order [Q.850]	This cause indicates that the network is not functioning correctly and that the condition is likely to last a relatively long period of time e.g. immediately re-attempting the call is not likely to be successful.
41	503	NORMAL_TEMPORARY_FAILURE	temporary failure [Q.850]	This cause indicates that the network is not functioning correctly and that the condition is not likely to last a long period of time; e.g. the user may wish to try another call attempt almost immediately.
42	503	SWITCH_CONGESTION	switching equipment congestion [Q.850]	This cause indicates that the switching equipment generating this cause is experiencing a period of high traffic.
43		ACCESS_INFO_DISCARDED	access information discarded [Q.850]	This cause indicates that the network could not deliver access information to the remote user as requested, i.e. user-to-user information, low layer compatibility, high layer compatibility or sub-address as indicated in the diagnostic. It is noted that the particular type of access information discarded is optionally included in the diagnostic.
44	503	REQUESTED_CHAN_UNAVAIL	requested circuit/channel not available [Q.850]	This cause is returned when the other side of the interface cannot provide the circuit or channel indicated by the requesting entity.
45		PRE_EMPTED
47			resource unavailable, unspecified [Q.850]	This cause is used to report a resource unavailable event only when no other cause in the resource unavailable class applies.
50		FACILITY_NOT_SUBSCRIBED	requested facility not subscribed [Q.850	This cause indicates that the user has requested a supplementary service, which is available, but the user is not authorized to use.
52	403	OUTGOING_CALL_BARRED	outgoing calls barred	This cause indicates that although the calling party is a member of the CUG for the outgoing CUG call, outgoing calls are not allowed for this member of the CUG.
54	403	INCOMING_CALL_BARRED	incoming calls barred	This cause indicates that although the called party is a member of the CUG for the incoming CUG call, incoming calls are not allowed to this member of the CUG.
57	403	BEARERCAPABILITY_NOTAUTH	bearer capability not authorized [Q.850]	This cause indicates that the user has requested a bearer capability that is implemented by the equipment which generated this cause but the user is not authorized to use.
58	503	BEARERCAPABILITY_NOTAVAIL	bearer capability not presently available [Q.850]	This cause indicates that the user has requested a bearer capability which is implemented by the equipment which generated this cause but which is not available at this time.
63		SERVICE_UNAVAILABLE	service or option not available, unspecified [Q.850]	This cause is used to report a service or option not available event only when no other cause in the service or option not available class applies.
65	488	BEARERCAPABILITY_NOTIMPL	bearer capability not implemented [Q.850]	This cause indicates that the equipment sending this cause does not support the bearer capability requested.
66		CHAN_NOT_IMPLEMENTED	channel type not implemented [Q.850]	This cause indicates that the equipment sending this cause does not support the channel type requested
69	501	FACILITY_NOT_IMPLEMENTED	requested facility not implemented [Q.850]	This cause indicates that the equipment sending this cause does not support the requested supplementary services.
79	501	SERVICE_NOT_IMPLEMENTED	service or option not implemented, unspecified [Q.850]	This cause is used to report a service or option not implemented event only when no other cause in the service or option not implemented class applies.
81		INVALID_CALL_REFERENCE	invalid call reference value [Q.850]	This cause indicates that the equipment sending this cause has received a message with a call reference which is not currently in use on the user-network interface.
88	488	INCOMPATIBLE_DESTINATION	incompatible destination [Q.850]	This cause indicates that the equipment sending this cause has received a request to establish a call which has low layer compatibility, high layer compatibility or other compatibility attributes (e.g. data rate) which cannot be accommodated.
95		INVALID_MSG_UNSPECIFIED	invalid message, unspecified [Q.850]	This cause is used to report an invalid message event only when no other cause in the invalid message class applies.
96		MANDATORY_IE_MISSING	mandatory information element is missing [Q.850]	This cause indicates that the equipment sending this cause has received a message which is missing an information element which must be present in the message before that message can be processed.
97		MESSAGE_TYPE_NONEXIST	message type non-existent or not implemented [Q.850]	This cause indicates that the equipment sending this cause has received a message with a message type it does not recognize either because this is a message not defined of defined but not implemented by the equipment sending this cause.
98		WRONG_MESSAGE	message not compatible with call state or message type non-existent or not implemented. [Q.850]	This cause indicates that the equipment sending this cause has received a message such that the procedures do not indicate that this is a permissible message to receive while in the call state, or a STATUS message was received indicating an incompatible call state.
99		IE_NONEXIST	Information element / parameter non-existent or not implemented [Q.850]	This cause indicates that the equipment sending this cause has received a message which includes information element(s)/parameter(s) not recognized because the information element(s)/parameter name(s) are not defined or are defined but not implemented by the equipment sending the cause. This cause indicates that the information element(s)/parameter(s) were discarded. However, the information element is not required to be present in the message in order for the equipment sending the cause to process the message.
100		INVALID_IE_CONTENTS	Invalid information element contents [Q.850]	This cause indicates that the equipment sending this cause has received and information element which it has implemented; however, one or more fields in the I.E. are coded in such a way which has not been implemented by the equipment sending this cause.
101		WRONG_CALL_STATE	message not compatible with call state [Q.850]	This cause indicates that a message has been received which is incompatible with the call state.
102	504	RECOVERY_ON_TIMER_EXPIRE	recovery on timer expiry [Q.850]	This cause indicates that a procedure has been initiated by the expiration of a timer in association with error handling procedures. This is often associated with NAT problems. Ensure that "NAT Mapping Enable" is turned on in your ATA. If it is not NAT related it can sometimes be provider related, make sure to ensure another outbound provider does not solve the problem.
103		MANDATORY_IE_LENGTH_ERROR	parameter non-existent or not implemented - passed on (national use) [Q.850]	This cause indicates that the equipment sending this cause has received a message which includes parameters not recognized because the parameters are not defined or are defined but not implemented by the equipment sending this cause. The cause indicates that the parameter(s) were ignored. In addition, if the equipment sending this cause is an intermediate point, then this cause indicates that the parameter(s) were passed unchanged.
111		PROTOCOL_ERROR	protocol error, unspecified [Q.850]	This cause is used to report a protocol error event only when no other cause in the protocol error class applies.
127		INTERWORKING	Interworking, unspecified [Q.850]	This cause indicates that an interworking call (usually a call to SW56 service) has ended.
487	487	ORIGINATOR_CANCEL
500		CRASH
501		SYSTEM_SHUTDOWN
502		LOSE_RACE
503		MANAGER_REQUEST		This cause is used when you send an api command to make it hangup. For example uuid_kill <uuid>
600		BLIND_TRANSFER
601		ATTENDED_TRANSFER
602		ALLOTTED_TIMEOUT		This cause means that the server canceled the call because the destination channel took too long to answer.
603		USER_CHALLENGE
604		MEDIA_TIMEOUT
605		PICKED_OFF		This cause means the call was picked up by intercepting it from another extension (i.e. dialing **ext_number from another extension).
606		USER_NOT_REGISTERED		This means you tried to originate a call to a SIP user who forgot to register.
607		PROGRESS_TIMEOUT
609		GATEWAY_DOWN		Gateway is down (not answering on OPTIONS or SUBSCRIBE)