设为首页 收藏本站
开启辅助访问 切换到宽版
注册会员 找回密码


星友 发表于 2009-1-3 22:22 | 显示全部楼层 |阅读模式
IntroductionThe 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.
Starting your scriptEach item in an extension is of the form:
exten => extension-number,priority,application,argumentsTo launch an AGI script the application is 'agi' and the argument is the filename of your script. The script:
  • 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.pyWhen 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.

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.

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|yadaAGI 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:
  • If no argument is given on the "exten" line or if the argument given is empty, then the argument received is an empty string.
  • 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 AsteriskIn theory communicating with Asterisk is wonderfully simple:
  • You write to standard output to send a command to Asterisk.
  • You read from standard input to get the reply from 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:
       agi_request: test.py
       agi_channel: Zap/1-1
       agi_language: en
       agi_type: Zap
       agi_context: default
       agi_extension: 3
       agi_priority: 1If 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.
  • The result returned by AGI commands is a text string, generally of the form:
    200 Result=<number>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.
Returns-1 on channel failure, or 0 if successful.


PurposeCause the channel to automatically hangup at <time> seconds in the future. If <time> is 0 then the autohangup feature is disabled on this channel.


NoteIf the channel is hungup prior to <time> seconds, this setting has no effect. |

CHANNEL STATUS [<channelname>]

PurposeReturn 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                           线路忙

ExamplesCHANNEL STATUSReturn the status of the current channel.

CHANNEL STATUS Zap/9-1Return the status of channel Zap/9-1

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

EXEC <application> <options>

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

ReturnsWhatever the application returns, or -2 on failure to find the application.

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

PurposePlays 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.

  • 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.

  • 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.
  • 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>

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

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

HANGUP [<channelname>]

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

ReturnsIf 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

ExamplesHANGUPHangup the current channel.

HANGUP Zap/9-1Hangup channel Zap/9-1

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

PurposeReceive a character of text from a connected channel. Waits up to <timeout> milliseconds for a character to arrive, or infinitely if <timeout> is zero.

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

NoteMost channels do not support the reception of text.

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

PurposeRecord 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.

  • The documentation in the code says on hangup the result is -1, however when I tried it the hangup result was
    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.
  • 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)

ExampleRECORD FILE baffy gsm 123 5000 beepRecord 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.

  • 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.
  • 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.

SAY DIGITS <digit string> <escape digits>

PurposeSay 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>.

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

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

PurposeSay 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>.

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

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

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

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

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

SEND TEXT "<text to send>"

PurposeSend the given text to the connected channel.

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

ExampleSEND TEXT "Hello world"

NoteMost channels do not support transmission of text.

SET CALLERID <caller ID specification>

PurposeChanges the caller ID of the current channel

ReturnsAlways returns 200 result=1

ExampleSET CALLERID "John Smith"<1234567>

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

PurposeSets the context for continuation upon exiting the application.

ReturnsAlways returns 200 result=0.

ExampleSET CONTEXT demo

  • 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.
  • 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.

SET EXTENSION <new extension>

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

ReturnsAlways returns 200 result=0.


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

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

ReturnsAlways returns 200 result=0.


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

PurposeSets a variable to the specified value. The variables so created can later be used by later using ${<variablename>}
in the dialplan.

ReturnsAlways returns 200 result=1.

ExampleSET VARIABLE station zap/3

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

  • Unlike most of Asterisk, variable names are case sensitive. The names 'Baffy' and 'baffy' refer to two separate and distinct variables.
  • 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.
  • 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.

STREAM FILE <filename> <escape digits>

PurposePlay 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可以积累返回用户的很多按键

ReturnsIf 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.

ExampleSTREAM FILE welcome #

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

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

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

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

ExampleTDD MODE on

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

PurposeSends <message> to the Asterisk console via the 'verbose' message system.
ReturnsAlways returns 1

ExampleVERBOSE Hello 3

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

  • <level> is the verbosity level in the range 1 through 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>

PurposeWaits 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.

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

ExampleWAIT 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.
水阳皿 发表于 2010-5-10 11:53 | 显示全部楼层
qq29391091 发表于 2010-6-21 16:12 | 显示全部楼层
andy20101314rq 发表于 2012-7-30 13:22 | 显示全部楼层

网站优化排名 qiyouseo.com
huneyqq 发表于 2013-3-21 10:09 | 显示全部楼层
您需要登录后才可以回帖 登录 | 注册会员


手机版|VoIP88 ( 粤ICP备11095982号   填写您的邮件地址,订阅我们的精彩内容:

GMT+8, 2019-8-23 22:38 , Processed in 0.132871 second(s), 23 queries .

Powered by VoIP88

© 2001-2017 VoIP88

快速回复 返回顶部 返回列表