分类： LINUX
2009-05-31 13:35:04
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之间通过标准的输入输出进行交互。
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'，参数是脚本的文件名，同时脚本需要满足以下条件
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设置可以关闭开启这个功能。
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中参数，有几点注意：
In theory communicating with Asterisk is wonderfully simple:
与Asterisk通信是非常简单的
A few things to note:
当脚本执行时，Asterisk会向脚本发送各种的信息，可以在做其他事情之前If you need the information provided then save it; otherwise feel free to throw it away.
通过标准输入获取这些信息，每项数据都是一行，发送完毕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
200 Result=although some commands return additional information after the number. If you send Asterisk an invalid command your result will be
510 Invalid or unknown commandAll 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.
Answer channel if not already in answer state.
如果通道不再应答状态，则应答该通道
-1 on channel failure, or 0 if successful.
Cause the channel to automatically hangup at
0
If the channel is hungup prior to
Return the status of the specified channel. If no channel name is specified, return the status of the current channel.
返回指定通道的状态，如果通道没有指定，返回当前通道状态
-1 There is no channel that matches the given
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 线路忙
CHANNEL STATUS
Return the status of the current channel.
CHANNEL STATUS Zap/9-1
Return the status of channel Zap/9-1
The
通道名称与asterisk控制台上 show channels命令显示的通道名字一致
Executes the specified Asterisk
带参数执行指定的Asterisk 应用
Whatever the application returns, or -2 on failure to find the application.
返回值-2表示执行错误，没有找到指定应用
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按键时立刻返回。
200 Result=where(timeout)
200 Result=and the number of digits returned will be equal to
200 Result=13* (timeout)This differs from other commands with return DTMF as numbers representing ASCII characters.
Fetch the value of a variable.
取得变量值
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.
SET VARIABLE Baffy "This is a test"200 result=1GET VARIABLE Baffy200 result=1 (This is a test)
Hangup the specified channel. If no channel name is given, hang up the current channel.
If the hangup was successful then the result is 200 result=1
If no channel matches the
HANGUP
Hangup the current channel.
HANGUP Zap/9-1
Hangup channel Zap/9-1
The
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 a character of text from a connected channel. Waits up to
从链接的通道上获取文本的字符，在超时时间内获取到达的字符，如果超时时间为0，则持续接收。
result=65
result=0 (timeout)
result=-1
Most channels do not support the reception of text.
大多数通道不支持接收文本
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滴'。
result=0 (hangup)
result=50 (dtmf)
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.
/var/lib/asterisk/sounds
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
播音给定的数字字符，当取消按键确认收到则命令结束，如果不需要取消按键，采用""带入函数
Zero if playback completes without a digit being received, or the
ASCII numerical representation of the digit pressed, or -1 on error or
hangup.
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 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
播音指定的数值。
Zero if playback completes without a digit being received, or the
ASCII numerical representation of the digit pressed, or -1 on error or
hangup.
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 the specified image on a channel. The image name should not should not include the extension.
Zero if the image is sent or if the channel does not support image transmission. Returns -1 only on error or hangup.
Send the given text to the connected channel.
0 if text is sent or if the channel does not support text transmission. Returns -1 only on error or hangup.
SEND TEXT "Hello world"
Most channels do not support transmission of text.
Changes the caller ID of the current channel
设置当前通道的主叫号码
Always returns 200 result=1
SET CALLERID "John Smith"<1234567>
This command will let you take liberties with the
这条命令可以按照规定格式任意修改主叫号码，格式：名字用双引号后面紧跟角括号里面的数字
Sets the context for continuation upon exiting the application.
设置应用结束后的context从而继续流程
Always returns 200 result=0.
SET CONTEXT demo
Set the extension to be used for continuation upon exiting the application.
Always returns 200 result=0.
SET EXTENSION 23
Set the priority to be used for continuation upon exiting the application.
Always returns 200 result=0.
SET PRIORITY 5
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.
Sets a variable to the specified value. The variables so created can later be used by later using ${
in the dialplan.
设置变量的初始值，变量将被创建，并在后面的拨号方案中以${变量名字}形式使用
Always returns 200 result=1.
SET VARIABLE station zap/3
Creates a variable named 'station' with the value 'zap/3'.
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可以积累返回用户的很多按键
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.
STREAM FILE welcome #
Plays the file 'welcome'. If the user presses the '#' key the playing stops and the command returns 200 result=35
Enable or disable TDD transmission/reception on the current channel.
在当前通道上启用关闭 TDD（分时双功模式）收发模式
1 if successful or 0 if the channel is not TDD capable.
TDD MODE on
The argument
Sends
通过Verbose向Asterisk控制台发送信息
Always returns 1
VERBOSE Hello 3
Sends the message "Hello" to the console if the current Asterisk verbosity level is set to 3 or greater.
Waits up to 'timeout' milliseconds for channel to receive a DTMF digit
-1 on channel failure, 0 if no digit is received in timeout or the numerical value of the ascii of the digit received.
Use -1 for the timeout value if you want the call to wait indefinitely.
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.
