Call Interactive

Owned by esnata (Unlicensed)
Last updated: Oct 13, 2022 by Evgeniy
6 min read

You can test API methods on the interactive API browser page and without writing code
Some of the resources described on the page may not be available by default due to the type of application (see Creating and authorizing applications).

The Call Interactive function allows you to initiate an HTTP request to a specified URL and process the response to it. A constant set of parameters is passed with the request, containing information about the call. These parameters are located in the request string (for the GET method) or in the request body (for the POST method). The URL and the request method can be set when configuring the Voice Menu (/ivr/) context option action or in Client (/client/, /client_info/)(phone terminal manual number input call).

Call Interactive Configuration

To configure the Call Interactive function, you need to specify two parameters: The URL to which the system will make a request, and the method (GET or POST). When the GET method is selected, the request parameters containing information about the call will be passed in the request string, and when the POST method is selected, they will be passed in the request body.

Request parameters Call interactive IVR

Name

Type

Description

Name

Type

Description

EventType

string

Event type, always set to call_interactive

CallID

string

Unique call ID

CallerIDNum

string

Caller ID number

CallerIDName

string

Caller Name

CalledDID

string

External called number. Present if available

CalledExtension

string

IVR number in extended format (for example: yyyy*zzz)

CalledExtensionID

integer

ID of the internal number of the ‘IVR' type in the system

CallStatus

string

Call status, always set to ANSWER

CallFlow

string

Call flow, always set to IN

CallerExtension

string

The name of the internal number making the IVR call. Present only on an internal call

CallerExtensionID

integer

ID of the internal number making the IVR call. Present only on an internal call

CalledNumber

string

The number that the caller dialed. Can be an external number (for example: 003258422544), the IVR number in the extended format (for example: 0003*001) or a short IVR number (for example: 001).

CallAPIID

string

The call ID. It is automatically generated and saved throughout the entire call, regardless of whether it is translated or not.

Optional request parameters

May be present in the call_interactive request

Name

Type

Description

Name

Type

Description

voice_navigator_DTMF

string

Dialing from a phone terminal during the voice menu rule action='voice_helper'

voice_navigator_STT

string

Contains voice recognition during the voice menu rule action='voice_helper'

It can be used to create voice robots in combination with voice navigation to control the logic after the received recognition.

 

Имя

Тип

Описание

Имя

Тип

Описание

quality_rate

string

Conversation Rating (/quality rate/)

Request parameters Call interactive phone terminal calling

 

Имя

Тип

Описание

Имя

Тип

Описание

EventType

string

Event type, always set to call_interactive

CallID

string

Unique call ID

CallerIDNum

string

Caller ID number

CallerIDName

string

Caller Name

CallFlow

string

Call flow, always set to  OUT

CallerExtension

string

The name of the internal number making the call. 

CallerExtensionID

integer

ID of the internal number making the IVR call.

CalledNumber

string

The number that the caller dialed. Can be changed with SetToNum action

CallAPIID

string

The call ID. It is automatically generated and saved throughout the entire call, regardless of whether it is translated or not

 

Request Example

http://mysite.com/myscript?CalledExtensionID=145&CalledNumber=332&CallID=5205dc5cc5a411e5ab9eb3691b90ea15&CallerIDNum=000%2A306&CallerExtensionID=134&CallerExtension=000%2A306&CallFlow=IN&CalledExtension=000%2A332&CallAPIID=3584705175%3A5205dc5cc5a411e5ab9eb3691b90ea15&CallerIDName=000%2A306&CallStatus=ANSWER

Variables in the query string

Additional parameters contained in the URL can be passed in the request string. These can take both static values and the values of variables set in the IVR earlier. In order to use the variable value in the URL, you must use the format $varname, where varname is the name of the required variable.

If the GET request method is selected, the parameters containing the call information will be added to the existing URL parameters.

Example of a URL with static parameters:

http://mysite.com/myscript?param1=value1&param2=value2

Example of a URL with variable parameters:

http://mysite.com/myscript?param1=$var&param2=$var2

Response structure

The response to the Call Interactive request is optional and is required if you need to perform an action.
The response to the request must be formed in XML format and have the following structure:

where Action can be one of the actions listed below.

Up to 10 actions are allowed in a single response, exceptions to this rule are the actions: hangup, SimpleTransfer, TTS (Text to speech) - after these actions, the rest will be ignored.

Options for action Call interactive IVR

Hangup

Ends the call immediately.

Pause

Pauses the call for the number of seconds specified by the length attribute of the Pause tag. If the value is not specified, the default is 10.

SetVar

Sets the value of the variable for the IVR. The variable name must be contained in the name attribute of the SetVar tag, and the value must be the content of this tag.

Jump

Jumps to the specified option of the specified IVR context. The context ID and option are set by the context and option attributes of the Jump tag.

SetCallerId

Specifies the caller number and caller name in the IVR environment. The number and name are set by the name and number attributes of the SetCaller tag.

PlaySound

Plays a sound whose file name is set by the content of the PlaySound tag. The file name can be obtained from the API as the filename parameter the “Sound files (/sound/)” resource. The where attribute of the PlaySound tag specifies the type of audio playback: foreground or background. When playing the background type, you can enter numbers in a variable whose name is specified in the digitvar attribute of the PlaySound tag.

SimpleTransfer

Calling through the simple transfer forwarding rule ignores the internal number settings and the internal number forwarding rules. The answer is similar to the pre-defined simple transfer rule. It is possible to specify both one and several numbers (NUM1, NUM2) separated by commas, spaces should not be present. The default rule is final (final='yes'), including if final is not specified, except if final="no" is specified.

The timeout parameter sets the call response time in seconds. If the timeout is specified incorrectly or this parameter is omitted, the system timeout will be used. Also, if necessary, you can add the parameter early_media="True" (in this format), in which case early media will not be ignored.

TTS — Text to speech

It only works when the speech_to_text function is activated in the client configuration (this setting is only available to the platform administrator)

The lang parameter is the text reading language. If the language is not specified, the default language will be used – Russian (ru-RU). Options are also available:

  • en-US – English;

  • tr-TR – Turkish.

If the language is specified, the voice parameter is checked by the condition of matching the voice in the list below. If the language is not specified or is not listed, the default language will be used.

The speed parameter is the speed of reading the text. Only available from the following range:
[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9, 3.0]

To convey homograph words, use the "+" sign before the stressed vowel: d+esert, des+ert.
To mark a pause between words, use the "-" sign.
The recommended maximum string length is 500 characters

The play_now parameter can take the values "true" or "false". Informs you whether to play the synthesized greeting immediately. You can postpone the playing of the greeting by using the additional parameter save_to_var= "true".
Playing a greeting from a variable is available in the play_sound, quality_rate, and voice_helper voice menu rules.
Possible combinations:

  • play_now= "true", save_to_var= "false" - the greeting will be played immediately;

  • play_now= "true", save_to_var= "true" - the greeting will be played immediately, and it can also be used further in the IVR logic;

  • play_now= "false", save_to_var= "true" - the greeting will not be played, but it can be used further in the IVR logic;

  • play_now= "false", save_to_var= "false" – nothing will be played, such a response to Call Interactive will be ignored.

Options for action Call interactive phone terminal calling

Hangup

Ends the call immediately.

SetAni

Set ani (ani means automatic number identification). Value must contain did from External Number (/did/).

SetToNum

Change the number that the caller dialed.