Baixe Asterisk & CentOS M04 e outras Notas de estudo em PDF para Eletrônica, somente na Docsity!
This is the Title of the Book, eMatter Edition
Appendix B APPENDIX B
Application Reference
AbsoluteTimeout( ) Sets the maximum number of seconds a call may last
AbsoluteTimeout( length )
Sets the absolute time limit of a call to length seconds. Calls lasting longer than length seconds will be sent to the T (absolute timeout) extension, if it exists. Otherwise, the channel will be hung up.
If length is set to zero ( 0 ), the timeout is disabled.
Each time AbsoluteTimeout( ) runs, it overrides the previous timeout setting. Asterisk starts the timeout countdown at the time the application is called, not at the time the call starts.
; limit calls to ex-girlfriend to 300 seconds exten => 123,1,AbsoluteTimeout(300) exten => 123,2,Dial(${EX-GIRLFRIEND}) exten => T,1,Playback(im-sorry) exten => T,2,Playback(vm-goodbye) exten => T,3,Hangup( )
See Also
DigitTimeout( ), ResponseTimeout( ), the T extension
AddQueueMember( ) Dynamically adds queue members to the specified call queue
AddQueueMember( queuename [, interface [, penalty ]])
Dynamically adds the specified interface to an existing queue named queuename , as speci- fied in queues.conf. If specified, penalty sets the penalty for queues to use this member. Members with a lower penalty are called before members with a higher penalty.
If interface is already a member of the queue and there exists an n+101 priority (where n is the number of the current priority), the call will continue at that priority. Otherwise, it will return an error.
Calling AddQueueMember( ) without an interface argument will use the interface that the caller is currently using.
This is the Title of the Book, eMatter Edition
230 |^ Appendix B: Application Reference
; add SIP/3000 to the techsupport queue, with a penalty of 1 exten => 123,1,AddQueueMember(techsupport,SIP/3000,1)
See Also
RemoveQueueMember( ), queues.conf
ADSIProg( ) Loads an ADSI script into an ADSI-capable phone
ADSIProg( script )
Programs an Analog Display Services Interface (ADSI) phone with the given script. If none is specified, the default script, asterisk.adsi , is used. The path for the script is relative to the Asterisk configuration directory (usually /etc/asterisk/ ). You may also provide the full path to the script.
To get the CPE ID and other information from your ADSI-capable phone, use the GetCPEID( ) application.
; program the ADSI phone with the telcordia-1.adsi script exten => 123,1,ADSIProg(telcordia-1.adsi)
See Also
GetCPEID( ), adsi.conf
AgentCallbackLogin( ) Enables agent login with callback
AgentCallbackLogin([ AgentNo ][,[ options ][ exten ]@ context ])
Allows a call agent identified by AgentNo to log into the call queue system, to be called back when a call comes in for that agent.
When a call comes in for the agent, Asterisk calls the specified exten (with an optional context ).
The options argument may contain the letter s, which causes the login to be silent.
; silently log in as agent number 42, and have Asterisk ; call SIP/400 when a call comes in for this agent exten => 123,1,AgentCallbackLogin(42,s,SIP/400)
See Also
AgentLogin( )
AgentLogin( ) Allows a call agent to log into the system
AgentLogin([ AgentNo ][, options ])
Logs the current caller into the call queue system as a call agent (optionally identified by AgentNo ). While logged in, the agent can receive calls and will hear a beep on the line when a new call comes in. The agent can hang up the call by pressing the asterisk (*) key.
This is the Title of the Book, eMatter Edition
232 |^ Appendix B: Application Reference
with the AGI program on STDIN and STDOUT. The specified arguments are passed to the AGI program.
The program must be set as executable in the underlying filesystem. The program path is relative to the Asterisk AGI directory, which by default is /var/lib/asterisk/agi-bin/.
If you want to run an AGI when no channel exists (such as in an h extension), use the DeadAGI( ) application instead. You may want to use the FastAGI( ) application if you want to do AGI processing across the network.
If you want access to the inbound audio stream from within your AGI program, use EAGI( ) instead of AGI( ). Inbound audio can then be read in on file descriptor number three.
Returns -1 on hangup or if the program requested a hangup, or 0 on non-hangup exit.
; call the demo AGI program exten => 123,1,AGI(agi-test) exten => 123,2,EAGI(eagi-test)
See Also
DeadAGI( ), FastAGI( ), Chapter 9
AlarmReceiver( ) Provides support for receiving alarm reports from a burglar or fire alarm panel
AlarmReceiver( )
Emulates an alarm receiver, and allows Asterisk to receive and decode special data from fire and/or burglar alarm panels. At this time, only the Ademco Contact ID format is supported.
When called, AlarmReceiver( ) will handshake with the alarm panel, receive events, vali- date them, handshake them, and store them until the panel hangs up. Once the panel hangs up, the application will run the command line specified by the eventcmd setting in alarmreceiver.conf and pipe the events to the standard input of the application. alarmre- ceiver.conf also contains settings for DTMF timing and for the loudness of the acknowledgment tones.
This application is not guaranteed to be reliable, so don’t depend on it unless you have extensively tested it. If you use this application with- out extensive testing, you may be putting your life and property at great risk.
This application always returns 0.
; set up Asterisk to answer a call from a supported fire alarm panel exten => s,1,AlarmReceiver( )
See Also
alarmreceiver.conf
This is the Title of the Book, eMatter Edition
Authenticate( ) |^233
Answer( ) Answers a channel, if it is ringing
Answer( )
Causes Asterisk to answer the channel if it is currently ringing. If the current channel is not ringing, this application does nothing.
It is usually a good idea to use Answer( ) on the channel before calling any other applica- tions, unless you have a very good reason not to. Most applications require that the channel be answered before they are called, and may not work correctly otherwise.
Returns 0 unless it tries to answer the channel and fails.
exten => 123,1,Answer( ) exten => 123,2,Wait(1) exten => 123,3,Playback(tt-weasels)
See Also
Hangup( )
AppendCDRUserField( ) Appends a value to the user field of the Call Detail Record
AppendCDRUserField( value )
Appends value to the user field of the Call Detail Record (CDR). The user field is often used to store arbitrary data about the call, which may not be appropriate for any of the other fields.
Always returns 0.
; set the user field to 'abcde' exten => 123,1,SetCDRUserField(abcde) ; now append 'xyz' exten => 123,1,AppendCDRUserField(xyz)
See Also
SetCDRUserField( ), ForkCDR( ), NoCDR( ), ResetCDR( )
Authenticate( ) Requires that the caller enter a correct password before continuing
Authenticate( password [, options ])
Requires a caller to enter a given password in order to continue execution of the next priority in the dialplan. Authenticate( ) gives the caller three chances to enter the password correctly. If the password is not correctly entered after three tries, the channel is hung up.
If password begins with the / character, it is interpreted as a file that contains a list of valid passwords (one per line). Passwords may also be stored in the Asterisk database (AstDB); see the d option below.
A set of options may be provided, consisting of one or more of the letters in the following list.
This is the Title of the Book, eMatter Edition
CallingPres( ) |^235
BackgroundDetect( ) Plays a file in the background and detects talking
BackgroundDetect( filename [, sil [, min [, max ]]])
Similar to Background( ), but attempts to detect talking.
During the playback of the file, audio is monitored in the receive direction. If a period of non-silence that is greater than min milliseconds yet less than max milliseconds and is followed by silence for at least sil milliseconds occurs, the audio playback is aborted and processing jumps to the talk extension, if available.
If unspecified, sil , min , and max default to 1,000 ms, 100 ms, and infinity, respectively.
Returns -1 on hangup, and 0 on successful playback completion with no exit conditions.
exten => 123,1,BackgroundDetect(tt-monkeys) exten => 123,2,Playback(im-sorry) exten => talk,1,Playback(yes-dear)
See Also
Playback( ), Background( )
Busy( ) Indicates a busy condition to the channel
Busy([ timeout ])
Requests that the channel indicate the busy condition and then waits for the user to hang up or for the optional timeout (in seconds) to expire.
This application only signals a busy condition to the bridged channel. Each particular channel type has its own way of communicating the busy condition to the caller. You can use Playtones(busy) to play a busy tone to the caller.
Always returns -1.
exten => 123,1,Playback(im-sorry) exten => 123,2,Playtones(busy) exten => 123,3,Busy( )
See Also
Congestion( ), Progress( ), Playtones( )
CallingPres( ) Changes the presentation for the Caller ID
CallingPres( presentation )
Changes the presentation parameters for the Caller ID on a Q931 PRI connection. These parameters should be set before placing an outgoing call. The argument presentation controls two things: whether or not the person being called can view the Caller ID informa- tion (known as presentation ), and whether or not the Caller ID information has been verified by an authoritative source (known as screening ).
This is the Title of the Book, eMatter Edition
236 |^ Appendix B: Application Reference
This application has been replaced by the SetCallerPres( ) applica- tion, which is easier to use and less dependent on the internal Zaptel structures.
This application takes the call presentation setting and the screening setting and combines them into one number. The values themselves are defined in the ITU Q931 standard, as shown in Tables B-1 and B-2.
Bits 3, 4, 5, and 8 should all be set to zero ( 0 ). Please note that the bits are numbered from most significant to least significant, like this: 87654321.
; set presentation to: ; Presentation Allowed (00000000) ; Network Provided (00000011) ; ------------------ ---------- ; Result = 3 (bitwise AND) (00000011) exten => 123,1,CallingPres(3) exten => 123,2,Dial(Zap/g1/8885551212)
; set presentation to: ; Presentation Restricted (00100000) ; User-provided, verified, and passed (00000001) ; ------------------ ---------- ; Result = 33 (bitwise AND) (00100001) exten => 124,1,CallingPres(33) exten => 124,2,Dial(Zap/g1/8885551213)
See Also
SetCallerPres( ), SetCallerID( )
Table B-1. Screening is controlled by bits 2 and 1
Bit 2 Bit 1 Explanation 0 0 Caller ID information was provided by the user, and not screened. 0 1 Caller ID information was provided by the user, and successfully verified. 1 0 Caller ID information was provided by the user, and verification failed. 1 1 Caller ID information was provided by the network.
Table B-2. Presentation is controlled by bits 7 and 6
Bit 7 Bit 6 Explanation 0 0 Presentation of the Caller ID information is allowed. 0 1 Presentation of the Caller ID information is restricted. 1 0 The number is not available due to interworking. 1 1 Reserved.
This is the Title of the Book, eMatter Edition
238 |^ Appendix B: Application Reference
exten => 123,3,Dial(${AVAILORIGCHAN}/5551212) ; if we go to priority 101, then neither Zap/1 nor Zap/2 is available exten => 123,3,Playback(all-circuits-busy-now)
CheckGroup( ) Checks the number of channels in a particular group
CheckGroup( max [@ category ])
Checks to see if the total number of channels in the current channel’s group exceeds the max argument. If the number does not exceed max , the application continues to the next priority. If the number of channels in the group is higher than max , and priority n+ exists (where n is the current priority), execution continues at that priority. Otherwise, the application terminates and -1 is returned.
When the optional category argument is passed, this application checks the total number of channels in the group category. See SetGroup( ) for more information about categories.
exten => 123,1,SetGroup(support) exten => 123,2,CheckGroup(5) ; if there are less than five calls in the support group exten => 123,3,Dial(${SUPPORT}) ; if there are more than five calls in the support group exten => 123,103,Playback(im-sorry)
See Also
SetGroup( ), GetGroupCount( ), GetGroupMatchCount( )
Congestion( ) Indicates congestion on the channel
Congestion([ timeout ])
Requests that the channel indicate congestion and then waits for the user to hang up or for the optional timeout (in seconds) to expire.
This application only signals congestion; it doesn’t actually play a congestion tone to the user. You can use Playtones(congestion) to play a congestion tone to the caller.
Always returns -1.
; if the Caller ID is 555-1234, always play congestion exten => 123,1,GotoIf($[${CALLERIDNUM} = 5551234]?5:2) exten => 123,2,Playtones(congestion) exten => 123,3,Congestion( ) exten => 123,4,Hangup( ) exten => 123,5,Dial(Zap/1)
See Also
Busy( ), Progress( ), Playtones( )
This is the Title of the Book, eMatter Edition
Cut( ) |^239
ControlPlayback( ) Plays a file, with the ability to fast forward and rewind the file
ControlPlayback( filename [, skipms [, ffchar [, rewchar [, stopchar [, pausechr ]]]]])
Plays back a given filename (without the file extension), while allowing the caller to move forward and backward through the file by pressing ffchar and rewchar. By default, you can use * and # to rewind and fast-forward the playback of the file. If stopchar is specified, the application will stop playback when stopchar is pressed. If the file does not exist, the appli- cation jumps to priority n+101, if present (where n is the current priority number).
The skipms option specifies how far forward or backward to jump in the file with each press of ffchar or rewchar.
A pausechr option may also be specified, which will pause playback of the file. Pressing pausechr again will continue the playback of the file.
Returns -1 if the channel was hung up during playback.
; allow the caller to control the playback of this file exten => 123,1,ControlPlayback(tt-monkeys|3000|#||5|0)*
See Also
Playback( ), Background( )
Curl( ) Loads an external URL and assigns the result to a variable
Curl( URL [, postdata ])
Downloads the given URL and assigns it to the channel variable named CURL. If specified, the postdata argument is passed to the URL as an HTTP POST. Curl( ) is often used to signal external applications of dialplan events.
Returns 0 , or -1 on fatal errors.
; post the Caller ID number and unique call ID to a URL exten => 123,1,Curl(http://localhost/test. php,CallerID=${CALLERID}&UniqueCallID={$UNIQUEID}) ; now use the NoOp( ) application to print the result to the Asterisk console exten => 123,2,NoOp(${CURL})
Cut( ) Assigns part of one variable to another variable
Cut( newvar = varname , delimiter , fieldspec )
Cuts an existing variable named varname into several pieces, and assigns one or more of the pieces to a new variable named newvar.
The delimiter argument is the character on which to cut varname. It defaults to -.
fieldspec is the number of the field you want to assign to newvar. Fields are counted starting with 1. The fieldspec may be specified as a range (with - ) or a group of ranges and fields (with &). If more than one field is selected, Cut( ) leaves the delimiter between the fields.
This is the Title of the Book, eMatter Edition
DeadAGI( ) |^241
Always returns 0.
; create a couple of entries in the AstDB exten => 123,1,DBput(test/blue) exten => 123,2,DBput(test/green) ; now delete the key family named test exten => 123,3,DBdeltree(test)
See Also
DBdel( ), DBput( ), DBget( )
DBget( ) Retrieves a key from the AstDB
DBget( varname = family / key )
Retrieves a key value from the Asterisk database and stores it in the variable specified by varname. If the requested key is not found, control jumps to priority n+101 (where n is the current priority), if it exists.
Always returns 0.
; put an entry in the AstDB exten => 123,1,DBput(test/color=blue) ; now retrieve it and assign it to a variable exten => 123,2,DBget(COLOR=test/color)
See Also
DBdel( ), DBdeltree, DBput( )
DBput( ) Stores a value in the AstDB
DBput( family / key = value )
Stores the given value in the corresponding family and key in the AstDB.
Always returns 0.
; put an entry in the AstDB exten => 123,1,DBput(test/color=blue)
See Also
DBdel( ), DBdeltree, DBget( )
DeadAGI( ) Executes an AGI-compliant script on a dead (hung-up) channel
DeadAGI( program , args )
Executes an AGI-compliant program on a dead (hung-up) channel. AGI allows Asterisk to launch external programs written in almost any language to control a telephony channel, play audio, read DTMF digits, and so on by communicating with the AGI protocol on STDIN and STDOUT. The arguments specified by args will be passed to the program.
This is the Title of the Book, eMatter Edition
242 |^ Appendix B: Application Reference
This application has been written specifically for dead channels, as the normal AGI inter- face doesn’t work correctly if the channel has been hung up.
Use the show agi command on the command-line interface to list all of the available AGI commands.
Returns -1 if the application requested a hangup, or 0 on a non-hangup exit.
exten => h,1,DeadAGI(agi-test)
See Also
AGI( ), FastAGI( )
Dial( ) Attempts to connect channels
Dial( tech / username : password @ hostname / extension , ring-timeout , flags )
Allows you to connect together all of the various channel types.*^ Dial( ) is the most impor- tant application in Asterisk—you’ll want to read through this section a few times.
Any valid channel type (such as SIP, IAX2, H.323, MGCP, Local, or Zap) is acceptable to Dial( ), but the parameters that need to be passed to each channel will depend on the information the channel type needs to do its job. For example, a SIP channel will need a network address and user to connect to, whereas a Zap channel is going to want some sort of phone number.
When you specify a channel type that is network-based, you can pass the destination host (name or IP address), username, password, and remote extension as part of the options to Dial( ), or you can refer to the name of a channel entry in the appropriate .conf file; all the required information will then need to be obtained from that file. The username and pass- word can be replaced with the name contained within square brackets ([]) of the channel configuration file. The hostname is optional.
This is a valid Dial statement:
exten => s,1,Dial(SIP/sake:arigato@thathostoverthere.tld)
This is effectively identical:
exten => s,1,Dial(SIP/some_SIP_friend)
but will work only if there is a channel defined in sip.conf as [some_SIP_friend], whose channel definition contains fromuser=sake, password=arigato, and host=thathostoverthere.tld.
An extension number is often attached after the address information, like this:
exten => s,1,Dial(IAX2/user:pass@otherend.com/ 500 )
This asks the far end to connect the call to extension 500 in the context in which the channel arrived. The extension is not required by Dial( ), as the information in the remote
- The fact that Asterisk will happily connect IAX, SIP, H.323, Skinny, PRI, FX(O/S), and anything else is amaz- ing, but possibly the most amazing of all is the Local channel. By allowing a single Dial( ) command to con- nect to multiple Local channels, one Dial( ) event can trigger a multitude of completely independent and unique actions in other parts of the dialplan. The power of this concept is truly revolutionary and has to be experienced to be believed.
This is the Title of the Book, eMatter Edition
244 |^ Appendix B: Application Reference
r Indicates ringing to the calling party, without passing any audio until the call is answered. This flag is not normally required to indicate ringing, as Asterisk will signal ringing if a channel is actually being called.
m[ class ] Provides music to the calling party until the call is answered. You may also optionally indicate the Music on Hold class.
M( x [ ^arg ])
Executes the macro x upon the connection of a call, optionally passing arguments delimited by ^. The macro can also set the MACRO_RESULT channel variable to one of the following: ABORT Hangs up both legs of the call CONGESTION Acts as if the line encountered congestion BUSY Acts as if the line was busy (goes to n+101, where n is the current priority) CONTINUE Hangs up the called party and continues on in the dialplan
GOTO:^^ Transfers the call to the specified destination
h Allows the called user to hang up the channel by pressing *.
H Allows the calling user to hang up the channel by pressing *.
C Resets the Call Detail Record for the call. Since the CDR time is set to when you Answer( ) the call, you may wish to reset the CDR so the end user is not billed for the time prior to the Dial( ) application being invoked.
P[( x )] Sets the privacy mode, optionally specifying x as the family/key value in the local AstDB. Useful for accepting calls based on a blacklist (explicitly denying calls from listed numbers) or whitelist (explicitly accepting calls from listed numbers). See also LookupBlacklist( ).
g Goes on in the context if the destination channel hangs up.
G( context ^ extension ^ priority ) Transfers both parties to the specified destination, if the call is answered.
A( x ) Plays an announcement to the called party; x is the filename of the sound file to play as the announcement.
D([ called ][: calling ]) Sends DTMF digits after the call has been answered, but before the call is bridged. The called parameter is passed to the called party, and the calling parameter is passed to the calling party. Either parameter may be used individually.
L( x [: y ][: z ]) Limits the call to x milliseconds, warning when y milliseconds are left and repeating every z milliseconds until the limit is reached. The x parameter is required; the y and z
This is the Title of the Book, eMatter Edition
Dial( ) |^245
parameters are optional. The following special variables may also be set to provide additional control: LIMIT_PLAYAUDIO_CALLER=yes|no Specifies whether to play sounds to the caller LIMIT_PLAYAUDIO_CALLEE=yes|no Specifies whether to play sounds to the callee LIMIT_TIMEOUT_FILE= filename Specifies which file to play when time is up LIMIT_CONNECT_FILE= filename Specifies which file to play when call begins LIMIT_WARNING_FILE= filename Specifies the file to play if the argument y is defined
n Prevents jumping to priority n+101 (where n is the number of the current priority) if all channels are deemed busy.
A call may also be parked instead of being transferred (which is done with the t or T flags). Calls are normally parked by transferring them to extension 700, but that’s configurable in the features.conf file.
The Dial( ) application sets the following variables upon exiting:
DIALEDTIME The total time elapsed from execution of Dial( ) until completion.
ANSWEREDTIME The total time elapsed during the call.
DIALSTATUS The status of the call, set as one of the following values: CHANUNAVAIL The channel is unavailable. CONGESTION The channel returned a congestion signal, usually indicating that it was unable to complete the connection. NOANSWER The channel did not answer in the time indicated by the ring-timeout option. BUSY The dialed channel is currently busy. ANSWER The channel answered the call. CANCEL The call was cancelled. ; dial a seven-digit number on Zap channel 4 exten => 123,1,Dial(Zap/4/2317154)
; dial the same number, but this time only have it ring for 10 seconds ; before continuing on with the dialplan
This is the Title of the Book, eMatter Edition
DISA( ) |^247
If the user enters 0 (zero) and there exists an extension o (the lowercase letter o) in the current context, the call control will go to that extension. Entering * will exit similarly, but to the a extension, much like Voicemail( )’s behavior.
Returns 0 unless the user hangs up.
*exten => ,1,Directory(default,incoming) exten => #,1,Directory(default,incoming,f)
See Also
voicemail.conf
DISA( ) Direct Inward System Access: allows inbound callers to make outbound calls
DISA( password [, context [, callerid [, mailbox [@ vmcontext ]]]]) DISA( password-file [, callerid [, mailbox [@ vmcontext ]]])
Allows outside callers to obtain an “internal” system dial tone and to place calls from it as if they were placing calls from within the switch. The user is given a dial tone, after which she should enter her passcode, followed by the pound sign (#). If the passcode is correct, the user is then given a system dial tone on which a call may be placed.
Obviously, this type of access has serious security implications, and extreme care must be taken not to compromise the security of your phone system.
The password argument is a numeric passcode that the user must enter to be able to make outbound calls. Using this syntax, all callers to this extension will use the same password. To allow users to use DISA( ) without a password, put the string “no-password” instead of the password.
The context argument specifies the context in which the user will be dialing. If no context is specified, the DISA( ) application defaults the context to disa.
The callerid argument specifies a new Caller ID string that will be used on the outbound call.
The mailbox argument is the mailbox number (and optional voicemail context, vmcontext ) of a voicemail box. The caller will hear a stuttered dial tone if there are any new messages in the specified voicemail box.
Additionally, you may use an alternate syntax and pass the name of a global password file instead of the password and context arguments. On each line, the file may contain either a passcode, or a passcode and context, separated by a pipe character (|). If a context is not specified, the application defaults to the context named disa.
If the user login is successful, the application parses the dialed number in the specified context.
; allow outside callers to call 1-800 numbers, as long ; as they know the passcode. Set their Caller IDs to make ; it appear that they are dialing from within the company [incoming]
This is the Title of the Book, eMatter Edition
248 |^ Appendix B: Application Reference
exten => 123,1,DISA(4569,disa,"Company ABC" <(234) 123-4567>)
[disa] exten => _1800NXXXXXX,1,Dial(Zap/4/${EXTEN})
DumpChan( ) Dumps information about the calling channel to the console
DumpChan([ min_verbose_level ])
Displays information about the calling channel, as well as a listing of all channel variables. If min_verbose_level is specified, output is displayed only when the verbosity level is currently set to that number or greater.
Always returns 0.
exten => s,1,Answer( ) exten => s,2,DumpChan( ) exten => s,3,Background(enter-ext-of-person)
DUNDiLookup( ) Looks up a phone number using DUNDi
DUNDiLookup( number [, context [, options ]])
Looks up the given phone number in the context specified, or in the reserved e164 context if not specified. On completion, the variables ${DUNDTECH} and ${DUNDDEST} will contain the appropriate technology and destination to access the number. If no answer was found, and the priority n+101 (where n is the current priority) exists, execution will continue at that priority.
The options argument is currently ignored.
Returns -1 if the channel is hung up during the lookup, or 0 otherwise.
; look up a number via DUNDi, and dial it exten => 123,1,DUNDiLookup(8885551212) exten => 123,2,Dial(${DUNDITECH}/${DUNDDEST}) ; if DUNDi lookup fails, dial it on a Zap channel instead exten => 123,102,Dial(Zap/4/1888551212)
See Also
ENUMLookup( )
EAGI( )
See AGI( ).
