Asterisk AGI 详解

Introduction

The AGI facility allows you to launch scripts, written in just about any language, from an Asterisk dial plan. Communication between your script and Asterisk is via standard input and standard output.
拨号方案中，可以采用各种语言很方便的通过AGI接口编写实施脚本。脚本和Asterisk之间通过标准的输入输出进行交互。

Starting your script

Each item in an extension is of the form:

    exten => extension-number,priority,application,arguments

To launch an AGI script the application is 'agi' and the argument is the filename of your script. The script:
执行AGI脚本时，Application应用就是'agi'，参数是脚本的文件名，同时脚本需要满足以下条件

• must be executable 必须可执行，chomd 755
  
• must be located in /var/lib/asterisk/agi-bin  必须放置在指定目录
  
• must be specified complete with an extension 必须指定完整分机信息

For example to run a Python script named 'test.py' then a suitable extension item would be:

    exten => 1,2,agi,test.py

When your script runs, you get a message saying so on the asterisk console provided you have your 'verbosity' level set to 3 or higher. If your script isn't found (you mis-typed the name) you will get a message saying failed to execute ... no such file or directory. If your script isn't executable (you forgot to give it execute permission) you will get a message saying failed to execute ... permission denied.
脚本执行时，可以从控制台上得到不同基本的详细信息，例如，文件不能被执行，或者找不到文件等等。

In any case, don't pay too much attention to the console message saying agi script test.py completed returning 0. This simply indicated that executing (or attempting to execute) the script is done; it does NOT imply that the script executed successfully.
无论如何，不要在意控制台上输入的返回0，这仅仅表示脚本执行了，并不代表脚本执行成功。

Your script can issue messages to the Asterisk console by sending them to standard error. At least in the initial stages of developing an agi script it isn't a Bad Idea to have the script issue messages along the line of Hi, I'm starting now and Terminating normally just so you know your script ran and completed successfully.
通过向Asterisk控制台信息输出，可以得到AGI脚本的执行信息，至少在开发初期中，控制台信息输出是个好办法。

You can also use the agi VERBOSE command (documented below) to send messages to the console with the added advantage that you can suppress or enable such messages depending on the verbosity setting.
通过agi VERBOSE命令，可以将信息发送到asterisk控制台上，并且而通过verbosity设置可以关闭开启这个功能。

Passing arguments to your AGI script
传递参数到AGI脚本

Yes Virginia you can pass arguments to your AGI script. You do so by following the name of your script with a vertical bar then the text you want to pass in. Extending the above example, to pass in "yada" as an argument we get:
在脚本名称后紧跟竖线和需要传送的文本，就可以把需要的参数传入脚本

    exten => 1,2,agi,test.py|yada

AGI scripts *always* receive two arguments. The first argument is the full path to the script itself. The second argument is the stuff passed in from the "exten" line. It's that second argument we are concerned with here. A few things to note about the second argument:
AGI脚本总是接收2种参数，1是脚本的完整路径，2是拨号方案中'Exten'传递的参数，需要关注的就是第2中参数，有几点注意：

• If no argument is given on the "exten" line or if the argument given is empty, then the argument received is an empty string.
  如果exten语句种没有给定参数，或者参数值为空，那么接收到的参数为空字符串
  
• The argument received consists of everything on the line following the vertical bar up until a vertical bar, a semi-colon or a comma. That means the argument may contain spaces.
  接收的参数为紧跟在竖线后面的一行数据，到竖线、分号、逗号结束，这意味着参数可以包含很多间隔隔开。
• Quotes, single or double, are simply taken as part of the argument; they have no special effect.
  单引号，双引号作为参数的以部分，没有特殊效果
  
• By the time you get the argument any trailing spaces have been deleted but leading spaces are not deleted.
  得到参数时，会删除后面的空格，不会删除前面的空格

 

Communicating with Asterisk

In theory communicating with Asterisk is wonderfully simple:
与Asterisk通信是非常简单的

• You write to standard output to send a command to Asterisk.
  通过标准的输出，发送命令到Asterisk
  
• You read from standard input to get the reply from Asterisk.
  通过标准的输入，从Asterisk接收信息

A few things to note:

• At script startup time Asterisk sends various pieces of information to your script and you should read these items, via standard input, before doing much else. Each item is sent on a line terminated with a newline and the end of the list is indicated by an empty line. The list of items received will look something like this:
  

  当脚本执行时，Asterisk会向脚本发送各种的信息，可以在做其他事情之前
  通过标准输入获取这些信息，每项数据都是一行，发送完毕Asterisk会发送
  一个空行，表示结束。内容如下：
     agi_request: test.py
     agi_channel: Zap/1-1
     agi_language: en
     agi_type: Zap
     agi_callerid:
     agi_dnid:
     agi_context: default
     agi_extension: 3
     agi_priority: 1

  If you need the information provided then save it; otherwise feel free to throw it away.
  如果需要这些数据，就先保存起来，否则不用处理它
  
• Commands sent to Asterisk must be terminated with a newline character.
  命令发送到Asterisk必须以换行符结束
  
• The result returned by AGI commands is a text string, generally of the form:
  AGI命令返回文本字符串，如下格式
  

  200 Result=<number>

  although some commands return additional information after the number. If you send Asterisk an invalid command your result will be
  有时会在number数字后附加一些信息。如果向Asterisk发送了无效的命令，信息如下：
  

  510 Invalid or unknown command

  All commands return a result. Commands which don't really need to return a result return 0 as the number. Commands which do need to return a result return various values, as described under the heading 'Returns' below.
  所有的命令都有返回结果，不需要返回值的将返回数字0，需要返回值的在'Returns'后显示注解信息。

 

 

ANSWER

Purpose
目的

Answer channel if not already in answer state.
如果通道不再应答状态，则应答该通道

Returns

-1 on channel failure, or 0 if successful.

 

AUTOHANGUP <time>

Purpose

Cause the channel to automatically hangup at <time> seconds in the future. If <time> is 0 then the autohangup feature is disabled on this channel.
在指定时间自动通道挂机，如果时间为0，则该命令在此通道上无效

Returns

0

Note

If the channel is hungup prior to <time> seconds, this setting has no effect. |
如果挂机发生在设定事件之前，此设置无效

 

CHANNEL STATUS [<channelname>]

Purpose

Return the status of the specified channel. If no channel name is specified, return the status of the current channel.
返回指定通道的状态，如果通道没有指定，返回当前通道状态

Returns

-1 There is no channel that matches the given <channelname>   没有匹配的通道
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                           线路忙

Examples

CHANNEL STATUS

Return the status of the current channel.

CHANNEL STATUS Zap/9-1

Return the status of channel Zap/9-1

Note

The <channelname> to use is the same as the channel names reported by the Asterisk console 'show channels' command.
通道名称与asterisk控制台上 show channels命令显示的通道名字一致

 

EXEC <application> <options>

Purpose

Executes the specified Asterisk <application> with given <options>.
带参数执行指定的Asterisk 应用

Returns

Whatever the application returns, or -2 on failure to find the application.
返回值-2表示执行错误，没有找到指定应用

 

GET DATA <filename> [<timeout> [<max digits>]]

Purpose

Plays the given file and receives DTMF data. This is similar to STREAM FILE, but this command can accept and return many DTMF digits, while STREAM FILE returns immediately after the first DTMF digit is detected.
播放指定的语音文件，同时获取DTMF按键信号，与STREAMFILE类似，但此命令能够接收到多个DTMF按键，而STREAMFILE在接收到第一个DTMF按键时立刻返回。

Returns

• If the command ended due to timeout then the result is of the form

      200 Result=<digits> (timeout)

  where <digits> will be zero or more ASCII characters depending on what the user pressed.
  
  
• If the command ended because the maximum number of digits were entered then the result is of the form

      200 Result=<digits>

  and the number of digits returned will be equal to <max digits>.
  
  
• In either case what you get are actual ASCII characters. For example if the user pressed the one key, the three key and then the star key, the result would be

      200 Result=13* (timeout)

  This differs from other commands with return DTMF as numbers representing ASCII characters.

Notes

• Don't give an extension with the filename.
  音频文件名称命名不要与分机相同
  
• Asterisk looks for the file to play in /var/lib/asterisk/sounds
  
• If the user doesn't press any keys then the message plays, there is <timeout> milliseconds of silence then the command ends.
  如果用户没有按键，声音播放完毕后，静默<超时时间>，然后命令结束
  
• The user has the opportunity to press a key at any time during the message or the post-message silence. If the user presses a key while the message is playing, the message stops playing. When the first key is pressed a timer starts counting for <timeout> milliseconds. Every time the user presses another key the timer is restarted. The command ends when the counter goes to zero or the maximum number of digits is entered, whichever happens first.
  在播放音频和静默时间内，用户可以按键打断，按键将停止播放音频，超时时间计时从用户第一个按键开始计时，每次按键重新计时，当用户按键复合最大按键数量或超时时间结束，命令结束
  
• If you don't specify a time out then a default timeout of 2000 is used following a pressed digit. If no digits are pressed then 6 seconds of silence follow the message.
  如果没有定义超时时间，缺省的时间为按键后20秒，如果没有按键，静默6秒后命令结束
  
• If you want to specify <max digits> then you *must* specify a <timeout> as well.
  如果想定义最大按键，最好定义超时时间
  
• If you don't specify <max digits> then the user can enter as many digits as they want.
  如果没有定义最大按键，用户可以按任意多的按键
  
• Pressing the # key has the same effect as the timer running out: the command ends and any previously keyed digits are returned. A side effect of this is that there is no way to read a # key using this command.
  按#号箭的效果相当于超时时间结束，命令终止并返回#号建前面的按键，不能获取到#号建本身
  

 

GET VARIABLE <variablename>

Purpose

Fetch the value of a variable.
取得变量值

Returns

Returns 0 if the variable hasn't been set. Returns 1 followed by the value of the variable in parenthesis if it has been set.

Example

SET VARIABLE Baffy "This is a test"200 result=1GET VARIABLE Baffy200 result=1 (This is a test)

 

HANGUP [<channelname>]

Purpose

Hangup the specified channel. If no channel name is given, hang up the current channel.

Returns

If the hangup was successful then the result is 200 result=1

If no channel matches the <channelname> you specified then the result is 200 result=-1

Examples

HANGUP

Hangup the current channel.

HANGUP Zap/9-1

Hangup channel Zap/9-1

Notes

The <channelname> to use is the same as the channel names reported by the Asterisk console 'show channels' command.
<channelname>与控制台上'show channels'命令显示的通道名字相同

With power comes responsibility. Hanging up channels other than your own isn't something that is done routinely. If you are not sure why you are doing so, then don't.

 

RECEIVE CHAR <timeout>

Purpose

Receive a character of text from a connected channel. Waits up to <timeout> milliseconds for a character to arrive, or infinitely if <timeout> is zero.
从链接的通道上获取文本的字符，在超时时间内获取到达的字符，如果超时时间为0，则持续接收。

Returns

• If a character is received, returns the ASCII value of the character as a decimal number. For example if the character 'A' is received the result would be
  如果一个字符串到达，以10进制数字的方式返回字符的ASCII码，例如A的返回值为：65
  

      result=65

• If the channel does not support text reception or if the no character arrives in <timeout> milliseconds then the result is
  如果通道不支持文本接收，或者在超时时间内没有字符被接收，结果如下
  

      result=0 (timeout)

• On error or failure the result is

      result=-1

Note

Most channels do not support the reception of text.
大多数通道不支持接收文本

 

RECORD FILE <filename> <format> <escape digits> <timeout> [BEEP]

Purpose

Record sound to a file until an acceptable DTMF digit is received or a specified amount of time has passed. Optionally the file BEEP is played before recording begins.
录制通道内的声音，生成文件，直到接收到DTMF确认结束按键，或者超时时间结束。在录制声音时，可以选择在录制前提示'BEEP滴'。

Returns

• The documentation in the code says on hangup the result is -1, however when I tried it the hangup result was
  源代码文档中描述挂机返回结果为-1，但实际测试结果为0（hangup）
  

      result=0 (hangup)

• If an error occurs then the result is -1. This can happen, for example, if you ask for a non-existent format.
  如果有错误发生，返回值为-1，例如没有可生成的语音文件格式
  
• If the user presses an acceptable escape digit then the result is a number representing the ASCII digit pressed. For example if recording terminated because the user pressed the '2' key the result is

      result=50 (dtmf)

Example

RECORD FILE baffy gsm 123 5000 beep

Record sound in gsm format to file 'baffy.gsm'. Play a beep before starting to record. Stop recording if user presses '1', '2' or '3', after five seconds of recording, or if the user hangs up.

Notes

• Don't put an extension on the filename; the filename extension will be created based on the <format> specified.
  
• The file will be created in

  /var/lib/asterisk/sounds

  
  
• <format> specifies what kind of file will be recorded. GSM is a commonly used format. To find out what other formats are supported start Asterisk with at a verbosity level of at least 2 (-vvc) and look for the messages that appear saying "== Registered file format <whatever>'. Most but not all registered formats can be used, for example, Asterisk can read but not write files in 'mp3' format.
  录音格式有很多种，GSM是常用的一种，可以在控制台上（高等级模式，至少2个V）查看注册到系统的文件格式，但不是所有的注册文件格式都可以使用，例如Asterisk可以读取但不能生成mp3文件格式
  
• If you don't want ANY digits to terminate recording then specify "" instead of a digit string. To change the above example so no digits terminate recording use RECORD FILE baffy gsm "" 5000 beep
  如果不需要任何按键确认录音结束，使用""代替确认按键字符
  
• <timeout> is the maximum record time in milliseconds, or -1 for no timeout. When this document was written [Nov 2002] I was unable to get <timeout> to work; this command always kept recording until I pressed an escape digit or hung up, as if -1 had been specified for timeout. A patch to correct this has been submitted but has not yet shown up in the CVS tree.
  超时时间是定义的最大录音时间周期，或者为-1即没有超时时间。在此文档2002年11月编写的时候，超时时间还不能正常工作。
  

 

SAY DIGITS <digit string> <escape digits>

Purpose

Say the given digit string, returning early if any of the given DTMF escape digits are received on the channel. If no DTMF digits are to be received specify "" for <escape digits>.
播音给定的数字字符，当取消按键确认收到则命令结束，如果不需要取消按键，采用""带入函数

Returns

Zero if playback completes without a digit being received, or the ASCII numerical representation of the digit pressed, or -1 on error or hangup.

Example

SAY DIGITS 123 78#

The digits 'one', 'two', 'three' are spoken. If the user presses the '7', '8' or '#' key the speaking stops and the command ends. If the user pressed no keys the result would be 200 result=0. If the user pressed the '#' key then the result would be 200 result=35.

 

SAY NUMBER <number> <escape digits>

Purpose

Say the given number, returning early if any of the given DTMF escape digits are received on the channel. If no DTMF digits are to be accepted specify "" for <escape digits>.
播音指定的数值。

Returns

Zero if playback completes without a digit being received, or the ASCII numerical representation of the digit pressed, or -1 on error or hangup.

Example

SAY NUMBER 123 789

The phrase 'one hundred twenty three' is spoken. If the user presses the '7', '8' or '9' key the speaking stops and the command ends. If the user pressed no keys the result would be 200 result=0. If the user pressed the '#' key then the result would be 200 result=35.

 

SEND IMAGE <image>

Purpose

Send the specified image on a channel. The image name should not should not include the extension.

Returns

Zero if the image is sent or if the channel does not support image transmission. Returns -1 only on error or hangup.

Notes

• Asterisk looks for the image in /var/lib/asterisk/images
  
• Most channels do not support the transmission of images.

 

SEND TEXT "<text to send>"

Purpose

Send the given text to the connected channel.

Returns

0 if text is sent or if the channel does not support text transmission. Returns -1 only on error or hangup.

Example

SEND TEXT "Hello world"

Note

Most channels do not support transmission of text.

 

SET CALLERID <caller ID specification>

Purpose

Changes the caller ID of the current channel
设置当前通道的主叫号码

Returns

Always returns 200 result=1

Example

SET CALLERID "John Smith"<1234567>

Notes

This command will let you take liberties with the <caller ID specification> but the format shown in the example above works well: the name enclosed in double quotes followed immediately by the number inside angle brackets.
这条命令可以按照规定格式任意修改主叫号码，格式：名字用双引号后面紧跟角括号里面的数字

• If there is no name then you can omit it.
  如果没有名字，可以省略
  
• If the name contains no spaces you can omit the double quotes around it.
  如果名字中没有空格，可以省略双引号
  
• The number must follow the name immediately; don't put a space between them.
  号码必须紧跟名字，而且中间不能有空格
  
• The angle brackets around the number are necessary; if you omit them the number will be considered to be part of the name.
  数字两边的角括号是必须的，如果省略他，会被认为号码是名字的一部分
  

 

SET CONTEXT <new context>

Purpose

Sets the context for continuation upon exiting the application.
设置应用结束后的context从而继续流程

Returns

Always returns 200 result=0.

Example

SET CONTEXT demo

Notes

• Setting the context does NOT automatically reset the extension and the priority; if you want to start at the top of the new context you should set extension and priority yourself.
  设置context不会自动重设extension和priority，如果想从头开始执行，需要手动设置extension和priority
  
• If you specify a non-existent context you receive no error indication (the result returned is still 'result=0') but you do get a warning message on the Asterisk console.
  如果设置了不存在的context，没有任何错误提示，在控制台上将不会收到任何警告信息，仍然返回result=0
  

 

SET EXTENSION <new extension>

Purpose

Set the extension to be used for continuation upon exiting the application.

Returns

Always returns 200 result=0.

Example

SET EXTENSION 23

Note

• Setting the extension does NOT automatically reset the priority. If you want to start with the first priority of the extension you should set the priority yourself.
  
• If you specify a non-existent extension you receive no error indication (the result returned is still 'result=0') but you do get a warning message on the Asterisk console.

 

SET PRIORITY <new priority number>

Purpose

Set the priority to be used for continuation upon exiting the application.

Returns

Always returns 200 result=0.

Example

SET PRIORITY 5

Note

If you specify a non-existent priority you receive no error indication of any sort: the result returned is still 'result=0' and no warning is issued on the Asterisk console.

 

SET VARIABLE <variablename> <value>

Purpose

Sets a variable to the specified value. The variables so created can later be used by later using ${<variablename>}
in the dialplan.
设置变量的初始值，变量将被创建，并在后面的拨号方案中以${变量名字}形式使用

Returns

Always returns 200 result=1.

Example

SET VARIABLE station zap/3

Creates a variable named 'station' with the value 'zap/3'.

Notes

• Unlike most of Asterisk, variable names are case sensitive. The names 'Baffy' and 'baffy' refer to two separate and distinct variables.
  与Asterisk的大多数变量不同，agi的变量是大小写敏感的。
  
  
• If the value being assigned contains spaces then put it inside double quotes.
  变量在赋值的时候，如果值中包含空格，必须加双引号
  
  
• If you want double quotes inside the value then you have to escape them. For example to create a variable CID whose value is "John Doe"<555-1212> you could use:
  如果值中有双引号，需要去避免它，采用下面的格式
  SET VARIABLE CID "/"John Doe /"<555-1212>
  
  Be aware that the language you are using may eat the backslash before it gets passed to Asterisk; you may have to use two backslashes or otherwise tell the language that, yes, you really do want a backslash in the string you are sending.
  需要注意的是，开发语言可能会吃掉传递给asterisk的反斜线，因此需要使用2个反斜线，或者明确的告诉开发语言，字符串中的反斜线真正的含义。
  
  
  
• These variables live in the channel Asterisk creates when you pickup a phone and as such they are both local and temporary. Variables created in one channel can not be accessed by another channel. When you hang up the phone, the channel is deleted and any variables in that channel are deleted as well.
  这些变量仅仅以本地的临时的形式在接通电话时产生，并在于asterisk的通道。在一个通道上产生的变量不能被其他通道访问，当挂机时，通道删除，同时变量也删除。
  

 

STREAM FILE <filename> <escape digits>

Purpose

Play the given audio file, allowing playback to be interrupted by a DTMF digit. This command is similar to the GET DATA command but this command returns after the first DTMF digit has been pressed while GET DATA can accumulated any number of digits before returning.
播放指定的语音文件，允许按键终止播放，这命令与GET DATA类似，但只返回用户的第一个按键，GET DATA可以积累返回用户的很多按键

Returns

If playback finished with no acceptable digit being pressed the result is zero. If an acceptable digit was pressed the result is the decimal representation of the pressed digit. If the channel was disconnected or an error occurred the result is -1.

Example

STREAM FILE welcome #

Plays the file 'welcome'. If the user presses the '#' key the playing stops and the command returns 200 result=35

Note

• Don't give an extension with the filename.
  
• Asterisk looks for the file to play in /var/lib/asterisk/sounds
  
• Use double quotes if the message should play completely. For example to play audio file 'welcome' without allowing interruption by digits use: STREAM FILE welcome ""
  如果需要语音文件完整播放，需要定义中断按键为""
  

 

TDD MODE <setting>

Purpose

Enable or disable TDD transmission/reception on the current channel.
在当前通道上启用关闭 TDD（分时双功模式）收发模式

Returns

1 if successful or 0 if the channel is not TDD capable.

Example

TDD MODE on

Note

The argument <setting> can be 'on' or 'tdd' to enable tdd mode. It can also be 'mate' which apparently sets some unspecified tdd mode. If it is anything else ('off' for example) then tdd mode is disabled.

 

VERBOSE <message> [<level>]

Purpose

Sends <message> to the Asterisk console via the 'verbose' message system.
通过Verbose向Asterisk控制台发送信息

Returns

Always returns 1

Example

VERBOSE Hello 3

Sends the message "Hello" to the console if the current Asterisk verbosity level is set to 3 or greater.

Notes

• <level> is the verbosity level in the range 1 through 4.
  <level>是显示信息的详细程度，范围1-4
  
  
• If your message contains spaces, then enclose it in double quotes.
  如果输出的信息包含空格，需要用双引号引起真个信息
  
  
• The Asterisk verbosity system works as follows. The Asterisk user gets to set the desired verbosity at startup time or later using the console 'set verbose' command. Messages are displayed on the console if their verbose level is less than or equal to desired verbosity set by the user. More important messages should have a low verbose level; less important messages should have a high verbose level.
  Asterisk信息输出工作方式：在Asterisk启动的时候设置level，或者使用控制台命令‘set verbose’信息显示将按照设定的级别显示，重要信息需要低级别，一般信息需要高级别即可
  

 

WAIT FOR DIGIT <timeout>

Purpose

Waits up to 'timeout' milliseconds for channel to receive a DTMF digit

Returns

-1 on channel failure, 0 if no digit is received in timeout or the numerical value of the ascii of the digit received.

Note

Use -1 for the timeout value if you want the call to wait indefinitely.

Example

WAIT FOR DIGIT 3000

If the user didn't press a digit within three seconds then the response is 200 result=0. If the user pressed the 9 digit the response is 200 result=57.