module Asterisk::AGI::Commands

Answer channel

Description: Answers channel if not already in answer state. Returns '-1' on channel failure, or '0' if successful.

Runs on dead channel? No

Syntax: answer

See also: #hangup

Interrupts Async AGI

Description: Interrupts expected flow of Async AGI commands and returns control to previous source (typically, the PBX dialplan).

Runs on dead channel? Yes

Syntax: asyncagi break

See also: #hangup

Returns status of the connected channel.

Description: Returns the status of the specified <channelname>. If no channel name is given then returns the status of the current channel. Return values:

0 - Channel is down and available.
1 - Channel is down, but reserved.
2 - Channel is off hook.
3 - Digits (or equivalent) have been dialed.
4 - Line is ringing.
5 - Remote end is ringing.
6 - Line is up.
7 - Line is busy.

Runs on dead channel? No

Syntax: channel status [<channelname>]

Sends audio file on channel and allows the listener to control the stream.

Description: Send the given file, allowing playback to be controlled by the given digits, if any. Use double quotes for the digits if you wish none to be permitted. If offsetms is provided then the audio will seek to offsetms before play starts. Returns '0' if playback completes without a digit being pressed, or the ASCII numerical value of the digit if one was pressed, or '-1' on error or if the channel was disconnected. Returns the position where playback was terminated as endpos. It sets the following channel variables upon completion: ${CPLAYBACKSTATUS}: Contains the status of the attempt as a text string

SUCCESS
USERSTOPPED
REMOTESTOPPED
ERROR

${CPLAYBACKOFFSET}: Contains the offset in ms into the file where playback was at when it stopped. '-1' is end of file. ${CPLAYBACKSTOPKEY}: If the playback is stopped by the user this variable contains the key that was pressed.

Runs on dead channel? No

Syntax: control stream file <filename> <escape_digits> [<skipms>] [<ffchar>] [<rewchr>] [<pausechr>] [<offsetms>]

See also: #get_option, #control_stream_file

Removes database key/value

Description: Deletes an entry in the Asterisk database for a given <family> and <key>. Returns '1' if successful, '0' otherwise.

Runs on dead channel? Yes

Syntax: database del <family> <key>

See also: #database_get, #database_put, #database_deltree

Removes database keytree/value

Description: Deletes a <family> or specific <keytree> within a <family> in the Asterisk database. Returns '1' if successful, '0' otherwise.

Runs on dead channel? Yes

Syntax: database deltree <family> [<keytree>]

See also: #database_get, #database_put, #database_del

Gets database value

Description: Retrieves an entry in the Asterisk database for a given <family> and <key>. Returns '0' if <key> is not set. Returns '1' if <key> is set and returns the variable in parenthesis. Example return code: 200 result=1 (testvariable)

Runs on dead channel? Yes

Syntax: database get <family> <key>

See also: #database_put, #database_del, #database_deltree

Adds/updates database value

Description: Adds or updates an entry in the Asterisk database for a given <family>, <key>, and <value>. Returns '1' if successful, '0' otherwise.

Runs on dead channel? Yes

Syntax: database put <family> <key> <value>

See also: #database_get, #database_del, #database_deltree

Extends syntax of the #exec command

Examples:

Asterisk native AGI command synbtax:

exec "Dial", "SIP/200,30,tT"

Command options as an array:

exec "Dial", "SIP/200", "30", "tT"

Options as named tuple or hash:

NOTE key name in such cas it not important; basically following implementation of #exec just make it user-friendly. What is important is the order of options, they should follow syntax of the calling Asterisk command.

exec "Dial", {destination: "SIP/200", duration: 30, options: "tT"}
exec "Dial", {destination => "SIP/200", duration => 30, options => "tT"}

Executes a given Application

Description: Executes <application> with given <options>. Returns whatever the <application> returns, or '-2' on failure to find <application>.

Runs on dead channel? Yes

Syntax: exec <application> <options>

Prompts for DTMF on a channel

Description: Stream the given <file>, and receive DTMF data. Returns the digits received from the channel at the other end.

Runs on dead channel? No

Syntax: get data <file> [<timeout>] [<maxdigits>]

Evaluates a channel expression

Description: Returns '0' if <variablename> is not set or channel does not exist. Returns '1' if <variablename> is set and returns the variable in parenthesis. Understands complex variable names and builtin variables, unlike GET VARIABLE. Example return code: 200 result=1 (testvariable)

Runs on dead channel? Yes

Syntax: get full variable <variablename> [<channel name>]

See also: #get_variable, #set_variable

Stream file, prompt for DTMF, with timeout.

Description: Behaves similar to STREAM FILE but used with a timeout option.

Runs on dead channel? No

Syntax: get option <filename> <escape_digits> [<timeout>]

See also: #stream_file, #control_stream_file

Gets a channel variable.

Description: Returns '0' if <variablename> is not set. Returns '1' if <variablename> is set and returns the variable in parentheses. Example return code: 200 result=1 (testvariable)

Runs on dead channel? Yes

Syntax: get variable <variablename>

See also: #get_full_variable, #set_variable

Cause the channel to execute the specified dialplan subroutine.

Description: Cause the channel to execute the specified dialplan subroutine, returning to the dialplan with execution of a Return().

Runs on dead channel? No

Syntax: gosub <context> <extension> <priority> [<optional-argument>]

Hangup a channel.

Description: Hangs up the specified channel. If no channel name is given, hangs up the current channel

Runs on dead channel? No

Syntax: hangup [<channelname>]

Does nothing.

Description: Does nothing.

Runs on dead channel? Yes

Syntax: noop

Receives one character from channels supporting it.

Description: Receives a character of text on a channel. Most channels do not support the reception of text. Returns the decimal value of the character if one is received, or '0' if the channel does not support text reception. Returns '-1' only on error/hangup.

Runs on dead channel? No

Syntax: receive char <timeout>

See also: #receive_text

Receives text from channels supporting it.

Description: Receives a string of text on a channel. Most channels do not support the reception of text. Returns '-1' for failure or '1' for success, and the string in parenthesis.

Runs on dead channel? No

Syntax: receive text <timeout>

See also: #receive_char, #send_text

Records to a given file.

Description: Record to a file until a given dtmf digit in the sequence is received. Returns '-1' on hangup or error. The format will specify what kind of file will be recorded. The <timeout> is the maximum record time in milliseconds, or '-1' for no <timeout>. <offset samples> is optional, and, if provided, will seek to the offset without exceeding the end of the file. <beep> can take any value, and causes Asterisk to play a beep to the channel that is about to be recorded. <silence> is the number of seconds of silence allowed before the function returns despite the lack of dtmf digits or reaching <timeout>. <silence> value must be preceded by 's=' and is also optional.

Runs on dead channel? No

Syntax: record file <filename> <format> <escape_digits> <timeout> [<offset_samples>] [<beep>] [<s=silence>]

Says a given character string.

Description: Say a given character string, returning early if any of the given DTMF digits are received on the channel. Returns '0' if playback completes without a digit being pressed, or the ASCII numerical value of the digit if one was pressed or '-1' on error/hangup.

Runs on dead channel? No

Syntax: say alpha <number> <escape_digits>

See also: #say_digits, #say_number, #say_phonetic, #say_date, #say_time, #say_datetime

Says a given date.

Description: Say a given date, returning early if any of the given DTMF digits are received on the channel. Returns '0' if playback completes without a digit being pressed, or the ASCII numerical value of the digit if one was pressed or '-1' on error/hangup.

Runs on dead channel? No

Syntax: say date <date> <escape_digits>

See also: #say_alpha, #say_digits, #say_number, #say_phonetic, #say_time, #say_datetime

Says a given time as specified by the format given.

Description: Say a given time, returning early if any of the given DTMF digits are received on the channel. Returns '0' if playback completes without a digit being pressed, or the ASCII numerical value of the digit if one was pressed or '-1' on error/hangup.

Runs on dead channel? No

Syntax: say datetime <time> <escape_digits> [<format>] [<timezone>]

See also: #say_alpha, #say_digits, #say_number, #say_phonetic, #say_date, #say_time

Says a given digit string.

Description: Say a given digit string, returning early if any of the given DTMF digits are received on the channel. Returns '0' if playback completes without a digit being pressed, or the ASCII numerical value of the digit if one was pressed or '-1' on error/hangup.

Runs on dead channel? No

Syntax: say digits <number> <escape_digits>

See also: #say_alpha, #say_number, #say_phonetic, #say_date, #say_time, #say_datetime

Says a given number.

Description: Say a given number, returning early if any of the given DTMF digits are received on the channel. Returns '0' if playback completes without a digit being pressed, or the ASCII numerical value of the digit if one was pressed or '-1' on error/hangup.

Runs on dead channel? No

Syntax: say number <number> <escape_digits> [<gender>]

See also: #say_alpha, #say_digits, #say_phonetic, #say_date, #say_time, #say_datetime

Says a given character string with phonetics.

Description: Say a given character string with phonetics, returning early if any of the given DTMF digits are received on the channel. Returns '0' if playback completes without a digit pressed, the ASCII numerical value of the digit if one was pressed, or '-1' on error/hangup.

Runs on dead channel? No

Syntax: say phonetic <string> <escape_digits>

See also: #say_alpha, #say_digits, #say_number, #say_date, #say_time, #say_datetime

Says a given time.

Description: Say a given time, returning early if any of the given DTMF digits are received on the channel. Returns '0' if playback completes without a digit being pressed, or the ASCII numerical value of the digit if one was pressed or '-1' on error/hangup.

Runs on dead channel? No

Syntax: say time <time> <escape_digits>

See also: #say_alpha, #say_digits, #say_number, #say_phonetic, #say_date, #say_datetime

Sends images to channels supporting it.

Description: Sends the given image on a channel. Most channels do not support the transmission of images. Returns '0' if image is sent, or if the channel does not support image transmission. Returns '-1' only on error/hangup. Image names should not include extensions.

Runs on dead channel? No

Syntax: send image <image>

Sends text to channels supporting it.

Description: Sends the given text on a channel. Most channels do not support the transmission of text. Returns '0' if text is sent, or if the channel does not support text transmission. Returns '-1' only on error/hangup.

Runs on dead channel? No

Syntax: send text <text to send>

See also: #receive_text

Autohangup channel in some time.

Description: Cause the channel to automatically hangup at <time> seconds in the future. Of course it can be hungup before then as well. Setting to '0' will cause the autohangup feature to be disabled on this channel.

Runs on dead channel? No

Syntax: set autohangup <time>

Sets callerid for the current channel.

Description: Changes the callerid of the current channel.

Runs on dead channel? No

Syntax: set callerid <number>

Sets channel context.

Description: Sets the context for continuation upon exiting the application.

Runs on dead channel? No

Syntax: set context <desired context>

See also: #set_extension, #set_priority

Changes channel extension.

Description: Changes the extension for continuation upon exiting the application.

Runs on dead channel? No

Syntax: set extension <new extension>

See also: #set_context, #set_priority

Enable/Disable Music on hold generator

Description: Enables/Disables the music on hold generator. If <class> is not specified, then the 'default' music on hold class will be used. This generator will be stopped automatically when playing a file. Always returns '0'.

Runs on dead channel? No

Syntax: set music {on|off} <class>

Set channel dialplan priority.

Description: Changes the priority for continuation upon exiting the application. The priority must be a valid priority or label.

Runs on dead channel? No

Syntax: set priority <priority>

See also: #set_context, #set_extension

Sets a channel variable.

Description: Sets a variable to the current channel.

Runs on dead channel? Yes

Syntax: set variable <variablename> <value>

See also: #get_variable, #get_full_variable

Activates a grammar.

Description: Activates the specified grammar on the speech object.

Runs on dead channel? No

Syntax: speech activate grammar <grammar name>

See also: #speech_create, #speech_set, #speech_destroy, #speech_load_grammar, #speech_unload_grammar, #speech_deactivate_grammar, #speech_recognize

Creates a speech object.

Description: Create a speech object to be used by the other Speech AGI commands.

Runs on dead channel? No

Syntax: speech create <engine>

See also: #speech_set, #speech_destroy, #speech_load_grammar, #speech_unload_grammar, #speech_activate_grammar, #speech_deactivate_grammar, #speech_recognize

Deactivates a grammar.

Description: Deactivates the specified grammar on the speech object.

Runs on dead channel? No

Syntax: speech deactivate grammar <grammar name>

See also: #speech_create, #speech_set, #speech_destroy, #speech_load_grammar, #speech_unload_grammar, #speech_activate_grammar, #speech_recognize

Destroys a speech object.

Description: Destroy the speech object created by 'SPEECH CREATE'.

Runs on dead channel? Yes

Syntax: speech destroy

See also: #speech_create, #speech_set, #speech_load_grammar, #speech_unload_grammar, #speech_activate_grammar, #speech_deactivate_grammar, #speech_recognize

Loads a grammar.

Description: Loads the specified grammar as the specified name.

Runs on dead channel? No

Syntax: speech load grammar <grammar name> <path to grammar>

See also: #speech_create, #speech_set, #speech_destroy, #speech_unload_grammar, #speech_activate_grammar, #speech_deactivate_grammar, #speech_recognize

Recognizes speech.

Description: Plays back given <prompt> while listening for speech and dtmf.

Runs on dead channel? No

Syntax: speech recognize <prompt> <timeout> [<offset>]

See also: #speech_create, #speech_set, #speech_destroy, #speech_load_grammar, #speech_unload_grammar, #speech_activate_grammar, #speech_deactivate_grammar

Sets a speech engine setting.

Description: Set an engine-specific setting.

Runs on dead channel? No

Syntax: speech set <name> <value>

See also: #speech_create, #speech_destroy, #speech_load_grammar, #speech_unload_grammar, #speech_activate_grammar, #speech_deactivate_grammar, #speech_recognize

Unloads a grammar.

Description: Unloads the specified grammar.

Runs on dead channel? Yes

Syntax: speech unload grammar <grammar name>

See also: #speech_create, #speech_set, #speech_destroy, #speech_load_grammar, #speech_activate_grammar, #speech_deactivate_grammar, #speech_recognize

Sends audio file on channel.

Description: Send the given file, allowing playback to be interrupted by the given digits, if any. Returns '0' if playback completes without a digit being pressed, or the ASCII numerical value of the digit if one was pressed, or '-1' on error or if the channel was disconnected. If musiconhold is playing before calling stream file it will be automatically stopped and will not be restarted after completion. It sets the following channel variables upon completion: ${PLAYBACKSTATUS}: The status of the playback attempt as a text string.

SUCCESS
FAILED

Runs on dead channel? No

Syntax: stream file <filename> <escape_digits> [<sample offset>]

See also: #control_stream_file, #get_option

Toggles TDD mode (for the deaf).

Description: Enable/Disable TDD transmission/reception on a channel. Returns '1' if successful, or '0' if channel is not TDD-capable.

Runs on dead channel? No

Syntax: tdd mode {|}

Logs a message to the asterisk verbose log.

Description: Sends <message> to the console via verbose message system. <level> is the verbose level (1-4). Always returns '1'

Runs on dead channel? Yes

Syntax: verbose <message> <level>

Waits for a digit to be pressed.

Description: Waits up to <timeout> milliseconds for channel to receive a DTMF digit. Returns '-1' on channel failure, '0' if no digit is received in the timeout, or the numerical value of the ascii of the digit if one is received. Use '-1' for the <timeout> value if you desire the call to block indefinitely.

Runs on dead channel? No

Syntax: wait for digit <timeout>