P-R

From AstriPedia

Index P-R of Asterisk Applications

Contents 1 Page 2 Park 3 ParkAndAnnounce 4 ParkedCall 5 PauseQueueMember 6 Pickup 7 Playback 8 PlayTones 9 PrivacyManager 10 Progress 11 Queue 12 Random 13 Read 14 ReadFile 15 RealTime 16 RealTimeUpdate 17 Record 18 RemoveQueueMember 19 ResetCDR 20 ResponseTimeout 21 RetryDial 22 Return 23 Ringing

Page

Synopsis

Pages phones

Description

Page(Technology/Resource&Technology2/Resource2[|options])

Places outbound calls to the given technology / resource and dumps them into a conference bridge as muted participants. The original caller is dumped into the conference as a speaker and the room is destroyed when the original caller leaves. Valid options are:

d - full duplex audio

q - quiet, do not play beep to caller

Park

Synopsis

Park yourself

Description

Park():

Used to park yourself (typically in combination with a supervised transfer to know the parking space). This application is always registered internally and does not need to be explicitly added into the dialplan, although you should include the 'parkedcalls' context.

ParkAndAnnounce

Synopsis

Park and Announce

Description

ParkAndAnnounce(announce:template|timeout|dial|[return_context]):

Park a call into the parkinglot and announce the call over the console. announce template: colon separated list of files to announce, the word PARKED will be replaced by a say_digits of the ext the call is parked in timeout: time in seconds before the call returns into the return context. dial: The app_dial style resource to call to make the announcement. Console/dsp calls the console. return_context: the goto style label to jump the call back into after timeout. default=prio+1

ParkedCall

Synopsis

Answer a parked call

Description

ParkedCall(exten):

Used to connect to a parked call. This application is always registered internally and does not need to be explicitly added into the dialplan, although you should include the 'parkedcalls' context.

PauseQueueMember

Synopsis

Pauses a queue member

Description

PauseQueueMember([queuename]|interface[|options]):

Pauses (blocks calls for) a queue member. The given interface will be paused in the given queue. This prevents any calls from being sent from the queue to the interface until it is unpaused with UnpauseQueueMember or the manager interface. If no queuename is given, the interface is paused in every queue it is a member of. If the interface is not in the named queue, or if no queue is given and the interface is not in any queue, it will jump to priority n+101, if it exists and the appropriate options are set. The application will fail if the interface is not found and no extension to jump to exists. The option string may contain zero or more of the following characters:

'j' -- jump to +101 priority when appropriate.

This application sets the following channel variable upon completion:

PQMSTATUS The status of the attempt to pause a queue member as a

text string, one of

PAUSED | NOTFOUND

Example: PauseQueueMember(|SIP/3000)

Pickup

Synopsis

Directed Call Pickup

Description

Pickup(extension[@context]):

This application can pickup any ringing channel that is calling the specified extension. If no context is specified, the current context will be used.

Playback

Synopsis

Play a file

Description

Playback(filename[&filename2...][|option]):

Plays back given filenames (do not put extension). Options may also be included following a pipe symbol. The 'skip' option causes the playback of the message to be skipped if the channel is not in the 'up' state (i.e. it hasn't been answered yet). If 'skip' is specified, the application will return immediately should the channel not be off hook. Otherwise, unless 'noanswer' is specified, the channel will be answered before the sound is played. Not all channels support playing messages while still on hook. If 'j' is specified, the application will jump to priority n+101 if present when a file specified to be played does not exist. This application sets the following channel variable upon completion:

PLAYBACKSTATUS The status of the playback attempt as a text string, one of

SUCCESS | FAILED

PlayTones

Synopsis

Play a tone list

Description

PlayTones(arg):

Plays a tone list. Execution will continue with the next step immediately, while the tones continue to play. Arg is either the tone name defined in the indications.conf configuration file, or a directly specified list of frequencies and durations. See the sample indications.conf for a description of the specification of a tonelist. Use the StopPlayTones application to stop the tones playing.

PrivacyManager

Synopsis

Require phone number to be entered, if no CallerID sent

Description

PrivacyManager([maxretries[|minlength[|options]]]):

If no Caller*ID is sent, PrivacyManager answers the channel and asks the caller to enter their phone number. The caller is given 3 attempts to do so. The application does nothing if Caller*ID was received on the channel.

Configuration file privacy.conf contains two variables:

maxretries default 3 -maximum number of attempts the caller is allowed

to input a callerid.

minlength default 10 -minimum allowable digits in the input callerid number.

If you don't want to use the config file and have an i/o operation with every call, you can also specify maxretries and minlength as application parameters. Doing so supercedes any values set in privacy.conf. The option string may contain the following character:

'j' -- jump to n+101 priority after <maxretries> failed attempts to collect

the minlength number of digits.

The application sets the following channel variable upon completion: PRIVACYMGRSTATUS The status of the privacy manager's attempt to collect

a phone number from the user. A text string that is either:

SUCCESS | FAILED

Progress

Synopsis

Indicate progress

Description

Progress():

This application will request that in-band progress information be provided to the calling channel.

Queue

Synopsis

Queue a call for a call queue

Description

Queue(queuename[|options[|URL][|announceoverride][|timeout]]):

Queues an incoming call in a particular call queue as defined in queues.conf. This application will return to the dialplan if the queue does not exist, or any of the join options cause the caller to not enter the queue.

The option string may contain zero or more of the following characters:

     'd' -- data-quality (modem) call (minimum delay).
     'h' -- allow callee to hang up by hitting *.
     'H' -- allow caller to hang up by hitting *.
     'n' -- no retries on the timeout; will exit this application and
             go to the next step.
     'r' -- ring instead of playing MOH
     't' -- allow the called user transfer the calling user
     'T' -- to allow the calling user to transfer the call.
     'w' -- allow the called user to write the conversation to disk via Monitor
     'W' -- allow the calling user to write the conversation to disk via Monitor
 In addition to transferring the call, a call may be parked and then picked
 up by another user.
 The optional URL will be sent to the called party if the channel supports it.
 The timeout will cause the queue to fail out after a specified number of
 seconds, checked between each queues.conf 'timeout' and 'retry' cycle.
 This application sets the following channel variable upon completion:
     QUEUESTATUS    The status of the call as a text string, one of
            TIMEOUT | FULL | JOINEMPTY | LEAVEEMPTY | JOINUNAVAIL | LEAVEUNAVAIL

Random

Synopsis

Conditionally branches, based upon a probability

Description

Random([probability]:[context|]extension|]priority) probability := INTEGER in the range 1 to 100

Read

Synopsis

Read a variable

Description

Read(variable[|filename][|maxdigits][|option][|attempts][|timeout])

Reads a #-terminated string of digits a certain number of times from the user in to the given variable.

 filename   -- file to play before reading digits.
 maxdigits  -- maximum acceptable number of digits. Stops reading after
               maxdigits have been entered (without requiring the user to
               press the '#' key).
               Defaults to 0 - no limit - wait for the user press the '#' key.
               Any value below 0 means the same. Max accepted value is 255.
 option     -- may be 'skip' to return immediately if the line is not up,
               or 'noanswer' to read digits even if the line is not up.
 attempts   -- if greater than 1, that many attempts will be made in the
               event no data is entered.
 timeout    -- if greater than 0, that value will override the default timeout.

Read should disconnect if the function fails or errors out.

ReadFile

Synopsis

ReadFile(varname=file,length)

Description

ReadFile(varname=file,length) Varname - Result stored here. File - The name of the file to read. Length - Maximum number of characters to capture.

RealTime

Synopsis

Realtime Data Lookup

Description

Use the RealTime config handler system to read data into channel variables.

RealTime(<family>|<colmatch>|<value>[|<prefix>])

All unique column names will be set as channel variables with optional prefix to the name. e.g. prefix of 'var_' would make the column 'name' become the variable ${var_name}

RealTimeUpdate

Synopsis

Realtime Data Rewrite

Description

Use the RealTime config handler system to update a value

RealTimeUpdate(<family>|<colmatch>|<value>|<newcol>|<newval>)

The column <newcol> in 'family' matching column <colmatch>=<value> will be updated to <newval>

Record

Synopsis

Record to a file

Description Record(filename.format|silence[|maxduration][|options])

Records from the channel into a given filename. If the file exists it will be overwritten.

- 'format' is the format of the file type to be recorded (wav, gsm, etc).
- 'silence' is the number of seconds of silence to allow before returning.
- 'maxduration' is the maximum recording duration in seconds. If missing
or 0 there is no maximum.
- 'options' may contain any of the following letters:
    'a' : append to existing recording rather than replacing
    'n' : do not answer, but record anyway if line not yet answered
    'q' : quiet (do not play a beep tone)
    's' : skip recording if the line is not yet answered
    't' : use alternate '*' terminator key instead of default '#'

If filename contains '%d', these characters will be replaced with a number incremented by one each time the file is recorded. A channel variable named RECORDED_FILE will also be set, which contains the final filemname.

Use 'show file formats' to see the available formats on your system

User can press '#' to terminate the recording and continue to the next priority.

If the user should hangup during a recording, all data will be lost and the application will teminate.

RemoveQueueMember

Synopsis

Dynamically removes queue members

Description

RemoveQueueMember(queuename[|interface[|options]]):

Dynamically removes interface to an existing queue If the interface is NOT in the queue and there exists an n+101 priority then it will then jump to this priority. Otherwise it will return an error The option string may contain zero or more of the following characters:

      'j' -- jump to +101 priority when appropriate.
 This application sets the following channel variable upon completion:
    RQMSTATUS      The status of the attempt to remove a queue member as a
                    text string, one of
          REMOVED | NOTINQUEUE | NOSUCHQUEUE
Example: RemoveQueueMember(techsupport|SIP/3000)

ResetCDR

Synopsis

Resets the Call Data Record

Description

ResetCDR([options]):

This application causes the Call Data Record to be reset.

Options:

w -- Store the current CDR record before resetting it.

a -- Store any stacked records.

v -- Save CDR variables.

ResponseTimeout

Synopsis

Set maximum timeout awaiting response

Description

ResponseTimeout(seconds):

This will set the maximum amount of time permitted to wait for an extension to dialed (see the WaitExten application), before the timeout occurs. If this timeout is reached, dialplan execution will continue at the 't' extension, if it exists. ResponseTimeout has been deprecated in favor of Set(TIMEOUT(response)=timeout)

RetryDial

Synopsis

Place a call, retrying on failure allowing optional exit extension.

Description

RetryDial(announce|sleep|retries|dialargs):

This application will attempt to place a call using the normal Dial application. If no channel can be reached, the 'announce' file will be played. Then, it will wait 'sleep' number of seconds before retying the call. After 'retires' number of attempts, the calling channel will continue at the next priority in the dialplan. If the 'retries' setting is set to 0, this application will retry endlessly. While waiting to retry a call, a 1 digit extension may be dialed. If that extension exists in either the context defined in ${EXITCONTEXT} or the current one, The call will jump to that extension immediately. The 'dialargs' are specified in the same format that arguments are provided to the Dial application.

Return

Synopsis

Return from gosub routine

Description

Return() Jumps to the last label on the stack, removing it.

Ringing

Synopsis

Indicate ringing tone

Description

Ringing():

This application will request that the channel indicate a ringing tone to the user.