Internal numbers of the IVR type (interactive voice menu) are used to configure the routing of calls inside the PBX using the information entered by the client on the phone keyboard using tone dialing.
To configure the voice menu, you must create an internal number by specifying the ivr value as the type. After that, it becomes possible to configure the voice menu via the API. The audio files that are required to configure the voice greeting are uploaded to the “Sound Files (/sound/)”resource.
The context is a pre-formed set of rules that can be referenced in the settings. Each context contains the following options:
start - describes the actions when entering the context;
timeout - describes the actions when a timeout occurs (the client did not make any choice during the specified period of time);
invalid – actions that occur when the client selects an option that is not configured.
In addition to the required context options, additional ones can be added (for example, what happens when you type the sequence "100"). All options perform the hangup (hang up) action by default, and this action must be overridden to set the required logic. The so-called "entry_context" is assigned to the IVR - it gets a call after coming to the voice menu. It can also be called the main context.
The type of voice greeting can be 'background' or 'foreground'. In the case of "background", the system is ready to accept the tone set at any time, and "foreground" obliges the user to listen to the recording until the end and only then make a choice (if the possibility of such a choice is configured).
Description of data structures
Name
Type
Mandatory
Default value
Description
Name
Type
Mandatory
Default value
Description
entry_context
long
none
0
ID of the main context
lifetime
long
none
0
The time (in seconds) after which the forced exit from the IVR occurs
lifetime_exp_action
string
none
Actions when exiting the IVR on the onset of lifetime:
'transfer' - transfer of the call (lifetime_exp_transfer_dst parameter);
'hangup' - hang up the phone
lifetime_exp_transfer_dst
string
none
Forwards to the specified number when the lifetime expires and lifetime_exp_action= 'transfer'
sleep_time
long
none
0
Time (in milliseconds) to start performing any actions after the call hits the IVR (it can be useful to avoid dropping the first words in the voice greeting after the connection is established)
vm_enabled
boolean
none
true
This option activates voice mail
vm_greeting
long
none
0
ID of the audio file that sounds like a voicemail greeting (relevant for vm_enabled)
vm_attach_file
boolean
none
true
A parameter that specifies whether to attach a file with a voice message when sending a receipt notification (relevant for vm_enabled)
vm_mailto
string
none
E-mail address for receiving notifications about a new voice message (multiple addresses separated by commas are possible; relevant for vm_enabled)
Name
Type
Mandatory
Default value
Description
Name
Type
Mandatory
Default value
Description
timeout
long
none
0
The time (in milliseconds) to wait for the start of the set after executing the last rule in the context option. When the time expires, go to the timeout option
allow_any_dial
boolean
none
true
This parameter determines whether any internal client number can be pre-dialed.
inter_digit_timeout
long
none
0
The time (in milliseconds) to wait for the next digit to be dialed. Upon expiration, the set is considered completed. For example, with "digit_len": 3, the set "30" will be accepted after inter_digit_timeout
name
string
none
Context name
digit_len
long
none
0
Client internal number length: after entering the specified number of digits, the input is considered complete (without the need to wait for "inter_digit_timeout"). Also defines the maximum length of a possible set by the client. For example, "digit_len": 3 allows you to type "7", "22", "300", but it doesn't let you select "4000"
Name
Type
Mandatory
Default value
Description
Name
Type
Mandatory
Default value
Description
digits
string
none
Adds a custom option to the standard context options (start, timeout, invalid). For example, the value "2" will set the ability to process the input of the number "2" after entering the context
Name
Type
Mandatory
Default value
Description
Name
Type
Mandatory
Default value
Description
action
string
none
Directly defines what needs to be done in this rule:
'transfer' – transfer the call to the number (s) from transfer_dst. The maximum possible number of forwarding numbers is 10. To simultaneously forward to a larger number of numbers, use the simple_transfer action;
'simple_transfer' - transfer the call (make a call forwarding) to the number (s) from the transfer_dst parameter. With this type of forwarding, the incoming call rules for the internal numbers listed in transfer_dst are not executed;
'hangup' - hang up the phone;
'play_sound' – play the greeting (sound and sound_type parameters);
'play_silence' – silence in background format (silence_time parameter);
'jump_to_context' – switch to another context (context and context_option parameters);
'play_digits' – play digits (the digits and play_digits_method parameters);
'play_digits_from_variable' – play the numbers contained in the variable (the play_digits_variable and play_digits_method parameters);
'record_digits' - write a set of digits to a variable (record_digits_variable, record_digits_max, and record_digits_sound parameters);
'set_variable' – set a variable in the channel (set_variable_name and set_variable_value parameters);
'transfer_from_variable' - transfer the call to the number contained in the variable (transfer_variable parameter);
'call_interactive' - Call Interactive function: make an HTTP request to a specific URL (call_interactive_url and call_interactive_method parameters);
'set_caller_id_number' - set the caller number for further redirects from the IVR (caller_id_number parameter);
'set_caller_id_name' - set the name of the caller for further forwarding from the IVR (caller_id_name parameter);
'quality_rate' - set a rule for evaluating the quality of the conversation (the main parameters for this action are sound and max_rate);
'voice_helper' - set the voice navigation rule (the main parameters for this action: sound, voice_helper_digits_max, voice_helper_rules, voice_helper_timeout). A description of the rule and parameters, as well as usage examples, are available on a separate page “Convert speech to text”
'start_record' – start recording the caller. Recording will stop when recording is enabled on any other extension.
digits
string
none
Speak the specified numbers (using the play_digits_method method), required when action= 'play_digits'
sound
long
none
0
The ID of the sound file to play is required when action= 'play_sound'
sound_type
string
none
Required if the sound ID is present. It can take the following values:
'background' – the user can make an additional set while the greeting sounds;
'foreground' – the user must listen to the greeting until the end
play_digits_method
string
none
Required when the digits option is set. May be:
'pronounced' – pronounce the digits as a single number;
'iterated' – say the numbers sequentially one after the other
Defines the method for analyzing the call source caller_id:
'matches' – must match (caller_id must be set);
'not_matches' – must not match (caller_id must be set);
'anonymous' - the source is hidden;
'any' – any source
caller_id
string
none
The rule will only work for calls whose source is determined by this field. The field is filled in as a PCRE regular expression. For example: "^(\+|)7812" will match all sources starting with "+7812" or "7812"
context_option
string
none
Defines the context option to go to when action= 'jump_to_context'
silence_time
long
none
0
The time (in milliseconds) when there are no sounds from the PBX, required when action= 'play_silence'
context
long
none
0
Specifies the ID of the other context to jump to, required when action= 'jump_to_context'
transfer_dst
string
none
Forwards to the specified number. If you need to forward to several numbers at the same time (simultaneous call), then these numbers are listed separated by a space (required for action= 'transfer')
set_variable_name
string
none
The name of the variable to be set. It must start with a Latin letter, and may contain Latin letters, numbers, and underscores. Required for action='set_variable'
set_variable_value
string
none
The value of the variable to be set. Required for action='set_variable'
match_variable_name
string
none
The name of the IVR variable whose value will be compared with the value specified by the match_variable_value parameter. If the values match, the rule is executed. The variable being compared can be set by the system (see the section "Preset variables in IVR"), or set by a context option rule of the set_variable type
match_variable_value
string
none
The value that will be compared with the value of the variable whose name is set by the match_variable_name parameter. If the values match, the rule is executed. Required if the match_variable_name parameter is set
transfer_variable
string
none
The name of the variable whose value will be used as the forwarding number. If the variable is not set, the action is not performed. The variable can be set using the set_variable, record_digits action, or using the Call Interactive function. Required when action='transfer_from_variable'
play_digits_variable
string
none
The name of the variable whose value will be used for playing numbers. If the variable is not set, the action is not performed. The variable can be set using the set_variable, record_digits action, or using the Call Interactive function. Required when action='play_digits_from_variable'
record_digits_variable
string
none
The name of the variable in which the entered digits will be written. Required when action='record_digits'
record_digits_max
string
none
The maximum number of entered digits to be written to the variable. Required when action='record_digits'
max_rate
long
none
5
Maximum conversation score (this parameter is only used for the quality_rate action)
record_digits_sound
long
none
0
ID of the sound file that can be played before writing the entered digits to the variable
call_interactive_url
string
none
The URL to which the HTTP request will be made by the Call Interactive function. Must start with http:// or https://. Required for action= 'call_interactive'
call_interactive_method
string
none
The method that will be used for the HTTP request by the Call Interactive function. It can take the value 'GET' or 'POST'. Required for action= 'call_interactive'
call_interactive_timeout
long
none
0
The time, in seconds, during which the system will wait for a response to the HTTP request of the Call Interactive function. If the called URL did not return a response after this time, the following rule is executed
caller_id_number
string
none
The number of the caller for further forwarding. This parameter can contain the names of variables previously set in other actions, as well as preset IVR variables (see the corresponding subsection). Variable names are specified in the format ${variable name}. Required when action='set_caller_id_number'
caller_id_name
string
none
The name of the caller for further forwarding. This parameter can contain the names of variables previously set in other actions, as well as preset IVR variables (see the corresponding subsection). Variable names are specified in the format ${variable name}. Required when action='set_caller_id_name'
id
long
none
0
Unique ID of the rule (within the internal number)
name
string
none
The name of the rule, not necessarily unique
final
boolean
none
true
This rule is the last one, and the subsequent ones do not need to be processed
hangup_cause
string
none
normal
The reason for the end of the call (the field can be ignored; present for backward compatibility)
record_digits_timeout
long
none
0
The time in seconds during which the entered digits will be recorded
transfer_timeout
long
none
0
The time in seconds during which the call will be transferred. If the time has elapsed and the transfer has not occurred, then the next rule is processed
call_status
string
none
any
The rule will work only if the status of the previous call (the innermost number or the previous forwarding rule) matches the value passed in this parameter:
‘no_answer'– there was no response (by timeout or some error occurred, except " SIP/2.0 486 Busy Here");
'busy' - the number is busy (received by SIP/2.0 486 Busy Here);
'any' – any result
play_sound_from_variable
boolean
none
false
The play_sound_from_variable parameter is available for the play_sound, quality_rate, and voice_helper rules. This system variable can store a greeting synthesized using the text_to_speech action in the "Call interactive" function. If there is no synthesized greeting, and the play_sound_from_variable parameter active, the default sound file specified in the sound parameter will be played
Variable name
Description
Variable name
Description
called_did
The public number (DID) to which the call came to the system. If the call is local, the variable contains the IVR number without the client prefix.
caller_id_name
Caller Name
caller_id_number
Caller ID number
Examples
For a client with a unique ID 12, you need to create a voice menu (IVR) with the number "071", when entering which the following rules apply:
Play the foreground music file "advertising.wav" 1 time;
Play the background music file "hello.wav" and, if the client does not select it, automatically transfer it to the internal number 050;
When dialing "1", the call is transferred to the mobile phone +7(987)6543210;
When you dial "2", the call is transferred to the internal number 002;
Allow direct dialing of three-digit internal numbers.
3. Create a context that will be the main one (entry_context):
System response:
Context ID "id": 1
4. Now you can bind this context as the main one to our IVR, at the same time we specify "sleep-time", which allows you to set a pause from the arrival of the call in the IVR before the start of any actions of the "entry_context" context":
System response:
5. As noted earlier, each context already has a “start” option. Let's configure it to play the foreground music file "advertising.wav":
6. Next, play the hello.wav file in the background by analogy:
7. Now, in the "Main Context" context, we will add the ability to process the selection " 1":
8. And we will indicate what action should be performed when selecting "1" - transfer to mobile +7(987)6543210:
9. By analogy, we will add a call to the internal number "002" by dialing "2":
10. If there is no choice, the call should be automatically transferred to the internal number "050". As already noted, there is a "timeout" option in the context, with which you can set this action:
11. As a result, you can view all the available context options: