module Asterisk::AGI::Commands

Direct including types

Defined in:

asterisk/agi/commands.cr
asterisk/agi/exec.cr

Instance Method Summary

Instance Method Detail

def answer #

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


[View source]
def asyncagi_break #

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


[View source]
def channel_status(channelname : String? = nil) #

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>]


[View source]
def control_stream_file(filename : String, escape_digits : String, skipms : String? = nil, ffchar : String? = nil, rewchr : String? = nil, pausechr : String? = nil, offsetms : String? = nil) #

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


[View source]
def database_del(family : String, key : String) #

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


[View source]
def database_deltree(family : String, keytree : String? = nil) #

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


[View source]
def database_get(family : String, key : String) #

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


[View source]
def database_put(family : String, key : String, value : String) #

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


[View source]
def exec(application : String, **options) #

[View source]
def exec(application : String, options : Hash(String, String | Int64 | Float64)) #

[View source]
def exec(application : String, options : Array(String | Int64 | Float64)) #

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"}

[View source]
def exec(application : String, options : String) #

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>


[View source]
def get_data(file : String, timeout : String? = nil, maxdigits : String? = nil) #

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>]


[View source]
def get_full_variable(variablename : String, channel_name : String? = nil) #

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


[View source]
def get_option(filename : String, escape_digits : String, timeout : String? = nil) #

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


[View source]
def get_variable(variablename : String) #

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


[View source]
def gosub(context : String, extension : String, priority : String, optional_argument : String? = nil) #

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>]


[View source]
def hangup(channelname : String? = nil) #

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>]


[View source]
def noop #

Does nothing.

Description: Does nothing.

Runs on dead channel? Yes

Syntax: noop


[View source]
def receive_char(timeout : String) #

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


[View source]
def receive_text(timeout : String) #

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


[View source]
def record_file(filename : String, format : String, escape_digits : String, timeout : String, offset_samples : String? = nil, beep : String? = nil) #

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>]


[View source]
def say_alpha(number : String, escape_digits : String) #

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


[View source]
def say_date(date : String, escape_digits : String) #

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


[View source]
def say_datetime(time : String, escape_digits : String, format : String? = nil, timezone : String? = nil) #

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


[View source]
def say_digits(number : String, escape_digits : String) #

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


[View source]
def say_number(number : String, escape_digits : String, gender : String? = nil) #

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


[View source]
def say_phonetic(string : String, escape_digits : String) #

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


[View source]
def say_time(time : String, escape_digits : String) #

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


[View source]
def send_image(image : String) #

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>


[View source]
def send_text(text_to_send : String) #

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


[View source]
def set_autohangup(time : String) #

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>


[View source]
def set_callerid(number : String) #

Sets callerid for the current channel.

Description: Changes the callerid of the current channel.

Runs on dead channel? No

Syntax: set callerid <number>


[View source]
def set_context(desired_context : String) #

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


[View source]
def set_extension(new_extension : String) #

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


[View source]
def set_music(moh_class : String) #

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>


[View source]
def set_priority(priority : String) #

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


[View source]
def set_variable(variablename : String, value : String) #

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


[View source]
def speech_activate_grammar(grammar_name : String) #

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


[View source]
def speech_create(engine : String) #

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


[View source]
def speech_deactivate_grammar(grammar_name : String) #

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


[View source]
def speech_destroy #

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


[View source]
def speech_load_grammar(grammar_name : String, path_to_grammar : String) #

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


[View source]
def speech_recognize(prompt : String, timeout : String, offset : String? = nil) #

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


[View source]
def speech_set(name : String, value : String) #

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


[View source]
def speech_unload_grammar(grammar_name : String) #

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


[View source]
def stream_file(filename : String, escape_digits : String, sample_offset : String? = nil) #

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


[View source]
def tdd_mode #

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 {|}


[View source]
def verbose(message : String, level : String) #

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>


[View source]
def wait_for_digit(timeout : String) #

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>


[View source]