Appendix B. AGI Commands

ANSWER

Answers the current channel if not already answered .

Returns -1 upon failure, or 0 upon success.

CHANNEL STATUS [ channel ]

Returns the status of the specified channel . If none is given, returns the status of the current channel. Here is what the status codes mean:

0: Channel is on hook and available.

1: Channel is on hook, but reserved.

2: Channel is off the hook but no digits have been dialed .

3: Digits have been dialed.

4: The line connected to this channel is ringing.

5: A called line connected to this channel is ringing.

6: A called line connected to this channel has a call in progress.

7: A called line connected to this channel is busy.

DATABASE DEL family key

Deletes a value in the Asterisk database for the specified family and key.

Returns 1 if successful, 0 if not.

DATABASE DELTREE family [ keytree ]

Deletes a family or and/or keytree within a family in the Asterisk database.

Returns 1 if successful, 0 if not.

DATABASE GET family key

Retrieves a value in the Asterisk database for the specified family and key.

Returns 0 if key does not exist. Returns 1 and the requested value in parentheses if key exists, as in this example:

 200 result=1 (value) 

DATABASE PUT family key value

Creates or updates a value in the Asterisk database for the specified family, key.

Returns 1 if successful or 0 if not.

EXEC command options

Executes the specified dial-plan command with given options . The options are to be given in the syntax appropriate for the command. Commands are listed in Chapter 17.

Returns the same value as the called command would normally return, or -2 if the command is invalid.

GET DATA file [ timeout ] [ maxdigits ]

Streams the specified sound file and receives DTMF digits on the current channel.

Returns the digits received from the channel, if any

GET VARIABLE variable

Gets a variable from the current context and extension.

Returns 0 if variable is null or 1 if variable has a value. Also returns the variable in parentheses, as in the following return code:

 200 result=1 (value) 

HANGUP [ channel ]

Hangs up the specified channel or the current channel if none is given.

Returns 1.

RECEIVE CHAR timeout

Waits for a character of text on the current channel. Specify a timeout of 0 to wait indefinitely.

Returns the decimal (8-bit) ASCII value of the character if one is received, 0 if the channel does not support text, or -1 if the channel is hung up.

RECORD FILE filename format ' digits ' timeout [ beep ]

Records the sound on the current channel to a file until the specified digit sequence is received. Format can be wav , WAV , or gsm . timeout specifies the maximum recording length. beep will cause a beep to be played before recording begins.

Returns -1 only on error.

SAY NUMBER number ' digits '

Say the specified number, stopping if the specified digits are received on the channel.

Returns 0 if playback completes, the ASCII decimal value of the digit if one was received, or -1 on error.

SEND TEXT " text "

Sends text on the current channel, if it's supported by the connected device. Don't forget to use quotes around text .

Returns -1 only on hangup, otherwise always returns 0, even if the device doesn't support text.

SET CALLERID number

Changes the caller ID of the current channel to number .

Returns 1.

SET CONTEXT context

Sets the context in which to return when the AGI program is complete.

Returns nothing.

SET EXTENSION extension

Sets the extension to which to return when the AGI program is complete.

Returns nothing.

SET PRIORITY priority

Sets the priority in which to return when the AGI program is complete.

Returns nothing.

SET VARIABLE variable value

Sets the value of the specified variable to value .

Returns 1.

STREAM FILE file ' digits '

Streams the specified sound file, allowing playback to be interrupted by the given digits . Don't include the file extension in the filename.

Returns 0 if playback completes without receiving a digit, the ASCII decimal value of the digit if one was received, or -1 on error.

TDD MODE on off

Enables or disables TDD transmission/ reception on a channel. TDD is a signaling protocol used to assist deaf phone users in communicating via text messages.

Returns 1 if successful, 0 if not.

VERBOSE message level

Sends the specified message to the console via verbose logging. level is the verbosity level, from 1 to 4.

Returns 1.

WAIT FOR DIGIT timeout

Waits a maximum of timeout milliseconds for a dialed digit on the current channel. If timeout is -1, the AGI program will wait indefinitely for a dialed digit.

Returns -1 on failure, 0 if no digit is received, or the decimal (8-bit) ASCII value of the digit if one is received.