Asterisk features
Overview
Asterisk features 내용 정리.
Basic
Asterisk 는 DTMF 을 통해서 동작하는 기능을 설정할 수 있도록 지원한다(a.k.a feature codes).
크게 다음과 같은 기능들을 지원한다.
- Feature Code Call Transfers
- One-touch Features
- Call Pickup
- Built-in Dynamic Features
- Custom Dynamic Features
- Call Parking
Feature Code Call Transfers
Call transfer 란, 하나의 party에서 다른 party 로 연결을 시도하는 것을 의미한다. Call transfer 에는 크게 다음과 같은 타입이 있다
- Blind transfer
- Blind transfer 는 목표가 되는 party 의 상황을 신경쓰지않고 transfer 를 하는 것을 의미한다.
- A blind or unsupervised transfer is where the initiating party is blind to what is happening after the transfer. They are removed from the process as soon as they initiate the transfer. It is a sort of "fire and forget" transfer.
- Attended transfer
- Attended transfer 는 목표가 되는 party 의 상황에 따라 transfer 를 결정하는 것을 의미한다. 먼저 목표 party 에 전화를 건 다음, 준비가 되었을 때 transfer 를 시도하는 것이다.
- Variations on attended transfer behavior.
- An attended or supervised transfer happens when one party transfer another party to a new location by first dialing the transfer destination and only completing the transfer when ready. The initiating party is attending or supervising the transfer process by contacting the destination before completing the transfer. This is helpful if the transfer initiator wants to make sure someone answers or is ready at the destination.
Configuring Transfer Features
Transfer feature 를 사용하기 위해서는 다음 세가지 조건들이 충족되어야 한다.
- The transfer type must be enabled and assigned a DTMF digit string in features.conf or per channel - see Dynamic DTMF Features.
- The channel must allow the type of transfer attempted. This can be configured via the Application invoking the channel such as Dial or Queue.
- The channels involved must be answered and bridged.
Enabling blind or attended transfers
features.conf 파일의 featuremap 섹션에서 blindxfer 혹은 atxfer 옵션을 설정해야 한다. blindxfer 는 blind transfer, atxfer 는 attended transfer 설정이다. 사용하고자하는 DTMF 문자열을 설정해주면 된다.
[featuremap] blindxfer = #1 atxfer = *2
Now that you have the feature enabled you need to configure the dialplan such that a particular channel will be allowed to use the feature.
As an example if you want to allow transfers via the Dial application you can use two options, "t" or "T".
- t : Allow the called party to transfer the calling party by sending the DTMF sequence defined in features.conf. This setting does not perform policy enforcement on transfers initiated by other methods.
- T : Allow the calling party to transfer the called party by sending the DTMF sequence defined in features.conf. This setting does not perform policy enforcement on transfers initiated by other methods.
Setting these options for Dial in extensions.conf would look similar to the following.
exten = 102,1,Dial(PJSIP/BOB,30,T)
- The same arguments("t" and "T") work for the Queue and Dial application.
The Asterisk should be restarted or relevant modules should be reloaded for changes to take effect.
Feature codes for attended transfer control
There are a few additional feature codes related to attended transfers. These features allow you to vary the behavior of an attended transfer on command. They are all configured in the 'general' section of features.conf.
- Aborting an attended transfer
- Dialing the atxerabort code aborts an attended transfer. Otherwise there is no way to abort an attended transfer.
- Completing an attended transfer
- Dialing the atxfercomplete code completes an attended transfer and drops out of the call without having to hang up.
- Completing an attended transfer as a three-way bridge
- Dialing the atxferthreeway code completes an attended transfer and enters a bridge with both of the other parties.
- Swapping between the transferee and destination
- Dialing the atxferswap code swaps you between bridges with either party before the transfer is complete. This allows you to talk to either party one at a time before finalizing the attended transfer.
Example
[general] atxferabort = *3 atxfercomplete = *4 atxferthreeway = *5 atxferswap = *6
Configuring attended transfer callbacks
By default Asterisk will call back the initiator or the transfer if they hang up before the target answers and the answer timeout is reached. There are a few options for configuring this behavior.
- No answer timeout
- atxfernoanswertimeout allows you to define the timeout for attended transfers. This is the amount of time (in seconds) Asterisk will attempt to ring the target before giving up.
- Dropped call behavior
- atxferdropcall allows you to change the default callback behavior. The default is 'no' which results in Asterisk calling back the initiator of a transfer when they hang up early and the attended transfer times out. If set to 'yes' then the transfer target channel will be immediately transferred to the channel being transferred as soon as the initiator hangs up.
- Loop delay timing
- atxferloopdelay sets the number of seconds to wait between callback retries. This option is only relevant when atxferdropcall=no (or is undefined).
- Number of retries for callbacks
- atxfercallbackretries sets the number of times Asterisk will try to send a failed attended transfer back to the initiator. The default is 2.
Example
[general] atxfernoanswertimeout = 15 atxferdropcall = no atxferloopdelay = 10 atxfercallbackretries = 2
Behavior Options
These options are configured in the "[general]" section of features.conf.
- General transfer options
;transferdigittimeout = 3 ; Number of seconds to wait between digits when transferring a call ; (default is 3 seconds)
- Attended transfer options
;xfersound = beep ; to indicate an attended transfer is complete ;xferfailsound = beeperr ; to indicate a failed transfer ;transferdialattempts = 3 ; Number of times that a transferer may attempt to dial an extension before ; being kicked back to the original call. ;transferretrysound = "beep" ; Sound to play when a transferer fails to dial a valid extension. ;transferinvalidsound = "beeperr" ; Sound to play when a transferer fails to dial a valid extension and is out of retries.
- TransferContext
Blind 혹은 Attended transfer 를 할 경우, transfer 할 때 사용될 context 를 지정해주어야 한다. __TRANSFER_CONTEXT channel variable 에 지정해주면 된다<ref>http://network.programming4.us/forums/t/10613.aspx</ref>.
exten => s,1,Set(__TRANSFER_CONTEXT=TransferContext)
Basic Transfer Examples
In the previous section, we configured #1 and *2 as our features codes. We also passed the "T" argument to the Dial application at 102 to allow transfers by the calling party.
Our hypothetical example includes a few devices.
- PJSIP/ALICE at extension 101
- PJSIP/BOB at extension 102
- PJSIP/CATHY at extension 103
Making a blind transfer
For blind transfers we configured the #1 feature code.
Example
- ALICE dials extension 102 to call BOB - ALICE decides to transfer BOB to extension 103, so she dials #1. Asterisk will play the audio prompt "transfer". - ALICE enters the digits 103 for the destination extension. - Asterisk immediately hangs up the channel between ALICE and BOB. Asterisk creates a new channel for BOB that is dialing extension 103.
Making an attended transfer
For attended transfer we configured *2 as our feature code.
Example
- ALICE dials extension 102 to call BOB and BOB answers. - ALICE decides to transfer BOB to extension 103, so she dials *2. Asterisk plays the audio prompt "transfer". - ALICE enters the digits 103 for the destination extension. Asterisk places BOB on hold and creates a channel for ALICE to dial CATHY. - CATHY answers : ALICE and CATHY talk. ALICE decides to complete the transfer and hang up the phone. - Asterisk immediately hangs up the channel between ALICE and BOB. Asterisk plays a short beep tone to CATHY and then bridges the channels for BOB and CATHY.
One-Touch Features
Once configured these features can be activated with only a few or even one keypress on a user's phone. They are often called "one-touch" or "one-step" features.
All of the features are configured via options in the featuremap section of features.conf and require arguments to be passed to the applications invoking the target channel.
Available Features
- automon : (One-touch Recording) Asterisk will invoke Monitor on the current channel.
- automixmon : (One-touch Recording) Has the same behavior as automon, but uses MixMonitor instead of Monitor.
- disconnect : (One-touch Disconnect) When this code is detected on a channel that channel will be immediately hung up.
- parkcall : (One-touch Parking) Sets a feature code for quickly parking a call.
- Most parking options and behavior are configured in res_parking.conf in Asterisk 12 and newer.
Enabling the Features
Configuration of features.conf
the options are configured in features.conf in the featuremap section. They use typical Asterisk configuration file syntax.
[featuremap] automon = *1 automixmon = *3 disconnect = *0 parkcall = #72
Assign each option the DTMF character string that you want users to enter for invoking the feature.
Dialplan application options
For each feature there are a pair of options that can be set in the Dial or Queue applications. the two options enable the feature on either the calling party channel. If heither option of a pair are set then you will not be able to use the related feature on the channel.
- automon
- W : Allow the calling party to enable recording of the call.
- w : Allow the called party to enable recording of the call.
- automixmon
- X : Allow the calling party to enable recording of the call.
- x : Allow the called party to enable recording of the call.
- disconnect
- H : Allow the calling party to hang up the channel.
- h : Allow the called party to hang up the channel.
- parkcall
- K : Allow the calling party to enable parking of the call.
- k : Allow the called party to enable parking of the call.
Example
Set the option as you would any application option. exten = 101,1,Dial(PJSIP/ALICE,30,X)
This would allow the calling party, the party dialing PJSIP/ALICE, to invoke recording on the channel.
Using the Feature
One you have configured features.conf and the option in the application then you only have to enter the feature code on your phone's keypad during a call.
Call Pickup
Call pickup allows you to answer a call while it is ringing another phone or group of phones(other than the phone you are sitting at).
Requesting to pickup a call is done by two basic methods.
- by dialplan using the Pickup or PickupChan applications.
- by dialing the extension defined for pickupexten configured in features.conf.
Which calls can be picked up is determined by configuration and dialplan.
Call pickup support added in Asterisk 11
Dialplan Applications and Functions
Pickup Application
The Pickup application has three ways to select calls for pickup.
PickupChan Application
The PickupChan application tries to pickup the specified channels given to it.
CHANNEL Function
The CHANNEL function allows the pickup groups set on a channel to be changed from the defaults set by the channel driver when the channel was created.
callgroup/namedcallgroup
The CHANNEL(callgroup) option specifies which numeric pickup groups that this channel is a member.
same => n,Set(CHANNEL(callgroup)=1,5-7)
The CHANNEL(namedcallgroup)option specifies which named pickup groups that this channel is a member.
same => n,Set(CHANNEL(namedcallgroup)=engineering,sales)
For this option to be effective, you must set it on the outgoing channel. There are a couple of ways
- You can use the setvar option available with several channel driver configuration files to set the pickup groups.
- You can use a pre-dial handler.
pickupgroup/namedpickupgroup
The CHANNEL(pickupgroup) option specifies which numeric pickup groups this channel can pickup.
same => n,Set(CHANNEL(pickupgroup)=1,6-8)
The CHANNEL(namedpickupgroup) option specifies which named pickup groups this channel can pickup.
same => n,Set(CHANNEL(namedpickupgroup)=engineering,sales)
For this option to be effective, you must set it on the channel before executing the Pickup application or calling the pickupexten.
- You can use the setvar option available with several channel driver configuration files to set the pickup groups.
Configuration Options
The pickupexten request method selects calls using the numeric and named call groups. The ringing channels have the callgroup assigned when the channel is created by the channel driver or set by the CHANNEL(callgroup) or CHANNEL(namedcallgroup) dialplan function.
Class picked up using pickupexten can hear an optional sound file for success and failure.
- The current channel drivers that support calling the pickupexten to pickup a call are: chan_dahdi/analog, chan_mgcp, chan_misdn, chan_sip, chan_unistim and chan_pjsip.
/etc/asterisk/features.conf pickupexten = *8 ; Configure the pickup extension. (default is *8) pickupsound = beep ; to indicate a successful pickup (default: no sound) pickupfailsound = beeperr ; to indicate that the pickup failed (default: no sound)
Numeric call pickup groups
A numeric callgroup and pickupgroup can be set to a comma separated list of ranges(e.g., 1-4) or numbers that can have a value of 0 to 63. There can be a maximum of 64 numeric groups.
SYNTAX callgroup=[number[-number][,number[-number][,...]]] pickupgroup=[number[-number][,number[-number][,...]]]
- callgroup : specifies which numeric pickup groups that this channel is a member.
- pickupgroup : specifies which numeric pickup groups this channel can pickup.
Configuration example callgroup=1,5-7 pickupgroup=1
Configuration should be supported in several channel drivers, including:
- chan_dahdi.conf
- misdn.conf
- mgcp.conf
- sip.conf
- unistim.conf
- pjsip.conf
pjsip.conf uses snake case:
Configuration in pjsip.conf call_group=1,5-7 pickup_group=1
Named call pickup groups
A named callgroup and pickupgroup can be set to a comma separated list of case sensitive name strings. The number of named groups is unlimited. The number of named groups you can specify at once is limited by the line length supported.
SYNTAX namedcallgroup=[name[,name[,...]]] namedpickupgroup=[name[,name[,...]]]
- namedcallgroup : specifies which named pickup groups that this channel is a member.
- namedpickupgroup : specifies which named pickup groups this channel can pickup.
Configuration Example namedcallgroup=engineering,sales,netgroup,protgroup namedpickupgroup=sales
Configuration should be supported in several channel drivers, including:
- chan_dahdi.conf
- misdn.conf
- sip.conf
- pjsip.conf
pjsip.conf uses snake case :
named_call_group=engineering,sales,netgroup,protgroup named_pickup_group=sales
You can use named pickup groups in parallel with numeric pickup groups. For example, the named pickup group '4' is not the same as the numeric pickup group '4'.
Named pickup groups are new with Asterisk 11.
Built-in Dynamic Features
The FEATURE and FEATUREMAP dialplan functions allow you to set some features.conf options on a per channel basis.
- To see what options are currently supported, look at the FEATURE and FEATUREMAP function descriptions. These functions were added in Asterisk 11.
- At this time the functions do not work with custom features. Those are set with a channel variable as described in the Custom Dynamic Features section.
Set the parking time of this channel to be 100 seconds if it is parked.
exten => s,1,Set(FEATURE(parkingtime)=100) same => n,Dial(SIP/100) same => n,Hangup()
Set the DTMF sequence for attended transfer on this channel to *9.
exten => s,1,Set(FEATUREMAP(atxfer)=*9) same => n,Dial(SIP/100,,T) same => n,Hangup()
Custom Dynamic Features
Asterisk allows you to define custom features mapped to Asterisk application. You can then enable these features dynamically, on a per-channel basis by using a channel variable.
Defining the Features
Custom features are defined in the applicationmap section of the features.conf file.
[applicationmap] <FeatureName> = <DTMF_sequence>,<ActivateOn>[/<ActivatedBy>],<Application>[,<AppArguments>[,MOH_Class]] <FeatureName> = <DTMF_sequence>,<ActivateOn>[/<ActivatedBy>],<Application>[,"<AppArguments>"[,MOH_Class]] <FeatureName> = <DTMF_sequence>,<ActivateOn>[/<ActivatedBy>],<Application>([<AppArguments>])[,MOH_Class]
- FeatureName : This is the name of the feature used when setting the DYNAMIC_FEATURES variable to enable usage of this feature.
- DTMF_sequence : This is the key sequence used to activate this feature.
- ActivateOn : This is the channel of the call that the application will be executed on. Valid values are "self" and "peer". "self" means run the application on the same channel that activated the feature. "peer" means run the application on the oppisite channel from the one that has activated the feature.
- ActivatedBy : ActivatedBy is no longer honored. The feature is activated by which channel DYNAMIC_FEATURES includes the feature is on. Use predial to set different values of DYNAMIC_FEATURES on the channels. Historic values are: "caller", "callee", and "both".
- Application : This is the application to execute.
- AppArguments : These are the arguments to be passed into the application. If you need commas in your arguments, you should use either the second or third syntax, above.
- MOH_Class : This is the music on hold class to play while the idle channel waits for the feature to complete. If left blank, no music will be played.
Application Mapping
The applicationmap is not intended to be used for all Asterisk applications. When applications are used in extensions.conf, they are executed by the PBX core. In this case, these applications are executed outside of the PBX core, so it does 'not' make sense to use any application which has any concept of dialplan flow. Examples of this would be things like Goto, Background, WaitExten, and many more. The exeptions to this are Gosub and Macro routines which must complete for the call to continue.
Enabling these features means that the PBX needs to stay in the media flow and media will not be re-directed if DTMF is sent in the media stream.
Example Feature Definitions
Here we have defined a few custom features to five you an idea of how the configuration looks.
features.conf
[applicationmap]
playmonkeys => #9,peer,Playback,tt-monkeys
retrieveinfo => #8,peer,Set(ARRAY(CDR(mark),CDR(name))=${ODBC_FOO(${CALLERID(num)})})
pauseMonitor => #1,self/callee,Pausemonitor
unpauseMonitor => #3,self/callee,UnPauseMonitor
Example feature descriptions:
- playmonkeys : Allow both the caller and callee to play tt-monkeys to the bridged channel.
- retrieveinfo : Set arbitrary channel variables based upon CALLERID number(Note that the application argument contains commas).
- pauseMonitor : Allow the callee to pause monitoring on their channel.
- unpauseMonitor : Allow the callee to unpause monitoring on their channel.
Enabling Features
After you define a custom feature in features.conf you must enable it on a channel by setting the DYNAMIC_FEATURES channel variable.
DYNAMIC_FEATURES accepts as an argument a list of hash -sign delimited feature names.
extensions.conf Set(__DYNAMIC_FEATURES=playmonkeys#pauseMonitor#unpauseMonitor)
- The two leading underscores allow these feature settings to be on the outbound channels, as well. Otherwise, only the original channel will have access to these features.
Call Parking
Some organizations have the need to facilitate calls to employees who move around the office a lot or who don't necessarily sit at a desk all day. In Asterisk, it is possible to allow a call to be put on hold at one location and then picked up from a different location such that the conversation can be continued from a device other than the one from which call was originally answered. This concept is known as call parking.
Call parking is a feature that allows a participant in a call to put the other participants on hold while they themselves hang up. When parking, the party that initiates the park will be told a parking space, which under standard configuration doubles as an extension. This extension, or parking space, serves as the conduit for accessing the parked call. At this point, as long as the parking space is known, the parked call can be retrieved from a different location/device from where it was originally answered.
Call Parking Configuration Files and Module
In versions of Asterisk prior to Asterisk 12, call parking was considered an Asterisk core feature and was configured using features.conf. However, Asterisk 12 underwent vast architectural changes, several of which were directed at call parking support. Because the amount of changes in Asterisk 12 was quite extensive, they have been omitted from the document.
In a nutshell, Asterisk 12 reloated its supprt for call parking from the Asterisk core into a separate, loadable module, res_parking. As a result, configuration for call parking was also moved to res_parking.conf. Configuration for call parking through features.conf for versions of Asterisk and beyond, is no longer supported. Additionally, support for the ParkAndAnnounce application was relocated to the res_parking module and the app_parkandannounce module was removed.
Before we move any further, there is one more rather important detail to address regarding configuration for res_parking
- res_parking ueses the configuration framework. If an invalid configuration is supplied, res_parking will fail to load or fail to reload. Previously, invalid configurations would generally be accepted, with certain errors resulting in individually disabled parking lots.
Example Configurations
Basic Call Parking/Retrieval Scenario
This is a basic scenario that only requires minimal adjustments to the following configuration files.
- res_parking.conf
- features.conf
- extensions.conf
In this scenario, our dialplan contains an extension to accept calls from the outside. Let's assume that the extension the caller dialed was: 5555001. The handler will then attempt to dial the alice extension, using k option.
Sadly for our caller, the alice extension answers the call and immediately after saying, "Hello world!", sends the DTMF digits to invoke the call parking feature without giving the caller a chance to speak. The alice extension quickly redeems itself by using the GoTo application to navigate to the 701 extension in the parkedcalls context to retrieve the parked call. But, since the next thing the calice extension does is hangup on our caller, I am beginning to think the alice extension doesn't want to be bothered.
In summary:
- Outside caller dials 5555001.
- Alice picks up the device and says "Hello World!".
- Alice presses the one touch parking DTMF combination.
- Alice then dials the extension that the call was parked to ( 701 ) to retrieve the call.
- Alice says, "Goodbye", and disconnects the caller.
res_parking.conf [general] parkext => 700 ; Sets the default extension used to park calls. Note: This option ; can take any alphanumeric string. parkpos => 701-709 ; Sets the range of extensions used as the parking lot. Parked calls ; may be retrieved by dialing the numbers in this range. Note: These ; need to be numeric, as Asterisk starts from the start position and ; increments with one for the next parked call. context => parkedcalls ; Sets the default dialplan context where the parking extension and ; the parking lot extensions are created. These will be automatically ; generated since we have specified a value for the 'parkext' option ; above. If you need to use this in your dialplan (extensions.conf), ; just include it like: include => parkedcalls. parkingtime => 300 ; Specifies the number of seconds a call will wait in the parking ; lot before timing out. In this example, a parked call will time out ; if it is not un-parked before 300 seconds (5 minutes) elapses. findslot => next ; Configures the parking slot selection behavior. For this example, ; the next free slot will be selected when a call is parked.
features.conf [featuremap] parkcall => #72 ; Parks the call (one-step parking). For this example, a call will be ; automatically parked when an allowed party presses the DTMF digits, ; #·7·2. A party is able to make use of this when the the K/k options ; are used when invoking the Dial() application. For convenience, the ; values of this option are defined below: ; K - Allow the calling party to enable parking of the call. ; k - Allow the called party to enable parking of the call.
extensions.conf [globals] ; Extension Maps 5001=alice ; Maps 5001 to a local extension that will emulate ; a party pressing DTMF digits from a device. ;5001=PJSIP/sip:alice@127.0.0.1:5060 ; What a realistc mapping for the alice device would look like. ; Realistically, 'alice' would map to a channel for a local device that would receive the call, therefore ; rendering this extension unnecessary. However, for the purposes of this demonstration, the extension is ; presented to you to show that sending the sequence of DTMF digits defined in the 'parkcall' option in ; 'features.conf' is the trigger that invokes the one-step parking feature. [parking-example] include => parkedcalls exten => alice,1,NoOp(Handles calls to alice.) same => n,Answer() same => n,Playback(hello-world) same => n,SendDTMF(#72w) same => n,Goto(parkedcalls,701,1) same => n,Playback(vm-goodbye) same => n,Hangup() [from-outside] exten => 5555001,1,NoOp(Route to a local extension.) ; Dials the device that is mapped to the local resource, alice, giving the recipient of the call the ability ; to park it. Assuming the value of LocalExtension is 5001, the Dial() command will look like: Dial(alice,,k) same => n,Dial(PJSIP/alice) same => n,Hangup()
Basic Handling for Call Parking Timeouts
Next we will move on to explain how to handle situations where a call is parked but is not retrieved before the value specified as the parkingtime option elapses. Just like the scenario above, this is a basic that only requires minimal adjustments to the following configuration files.
- res_parking.conf
- features.conf
- extensions.conf
Like before, our dialplan contains an extension to accept calls from the outside. Again, let's assume that the extension the caller dialed was: 555001. The handler will then attempt to dial to alice extension, using the k option.
Sadly for our caller, the alice extension answers the call and immediately sends the DTMF digits to invoke the call parking feature without giving the caller a chance to speak. Unlike in the previous scenario, however, the alice extension does not retrieve the parked call. Our sad caller is now even more sad.
After a period of 300 seconds, or 5 minutes (as defined in the parkingtime option in res_parking.conf), the call will time out. Because we told Asterisk to return a timed-out parked call to the party that originally parked the call(comebacktoorigin=yes), Asterisk will attempt to call alice using an extension automagically created in the special context, park-dial.
Unfortunately, the alice extension has no time to be bothered with us at this moment, so the call is not answered. After a period of 20 seconds, elapses (the value specified for the combackdialtime option in res_parking.conf), Asterisk finally gives up and the t extension in the park-dial context is executed. Our caller is then told "Goodbye" before being disconnected.
In summary:
- Outside caller dials 5555001.
- Alice picks up the device and says "Hello World!"
- Alice presses the one touch parking DTMF combination.
- The parked call times out after 300 seconds.
- Asterisk sends the call to the origin, or the alice extension.
- A period of 20 seconds elapses without an answer.
- Asterisk sends the call to t extension in the park-dial context.
- Our caller hears, "Goodbye", before being disconnected.
res_parking.conf
[general]
parkext => 700 ; Sets the default extension used to park calls. Note: This option
; can take any alphanumeric string.
parkpos => 701-709 ; Sets the range of extensions used as the parking lot. Parked calls
; may be retrieved by dialing the numbers in this range. Note: These
; need to be numeric, as Asterisk starts from the start position and
; increments with one for the next parked call.
context => parkedcalls ; Sets the default dialplan context where the parking extension and
; the parking lot extensions are created. These will be automatically
; generated since we have specified a value for the 'parkext' option
; above. If you need to use this in your dialplan (extensions.conf),
; just include it like: include => parkedcalls.
parkingtime => 300 ; Specifies the number of seconds a call will wait in the parking
; lot before timing out. In this example, a parked call will time out
; if it is not un-parked before 300 seconds (5 minutes) elapses.
findslot => next ; Configures the parking slot selection behavior. For this example,
; the next free slot will be selected when a call is parked.
comebackdialtime=20 ; When a parked call times out, this is the number of seconds to dial
; the device that originally parked the call, or the PARKER
; channel variable. The value of 'comebackdialtime' is available as
; the channel variable 'COMEBACKDIALTIME' after a parked call has
; timed out. For this example, when a parked call times out, Asterisk
; will attempt to call the PARKER for 20 seconds, using an extension
; it will automatically create in the 'park-dial' context. If the
; party does not answer the call during this period, Asterisk will
; continue executing any remaining priorities in the dialplan.
comebacktoorigin=yes ; Determines what should be done with a parked call if it is not
; retrieved before the time specified in the 'parkingtime' option
; elapses. In the case of this example where 'comebacktoorigin=yes',
; Asterisk will attempt to return the parked call to the party that
; originally parked the call, or the PARKER channel variable, using
; an extension it will automatically create in the 'park-dial'
; context.
features.conf [featuremap] parkcall => #72 ; Parks the call (one-step parking). For this example, a call will be ; automatically parked when an allowed party presses the DTMF digits, ; #·7·2. A party is able to make use of this when the the K/k options ; are used when invoking the Dial() application. For convenience, the ; values of this option are defined below: ; K - Allow the calling party to enable parking of the call. ; k - Allow the called party to enable parking of the call.
extensions.conf [globals] ; Extension Maps 5001=alice ; Maps 5001 to a local extension that will emulate ; a party pressing DTMF digits from a device. ;5001=PJSIP/sip:alice@127.0.0.1:5060 ; What a realistc mapping for the alice device would look like. ; Realistically, 'alice' would map to a channel for a local device that would receive the call, therefore ; rendering this extension unnecessary. However, for the purposes of this demonstration, the extension is ; presented to you to show that sending the sequence of DTMF digits defined in the 'parkcall' option in ; 'features.conf' is the trigger that invokes the one-step parking feature. [parking-example] include => parkedcalls exten => alice,1,NoOp(Handles calls to alice.) same => n,Answer() same => n,Playback(hello-world) same => n,SendDTMF(#72w) same => n,Wait(300) same => n,Hangup() [from-outside] exten => 5555001,1,NoOp(Route to a local extension.) ; Dials the device that is mapped to the local resource, alice, giving the recipient of the call the ability ; to park it. Assuming the value of LocalExtension is 5001, the Dial() command will look like: Dial(alice,,k) same => n,Dial(PJSIP/alice) same => n,Hangup() [park-dial] ; Route here if the party that initiated the call parking cannot be reached after a period of time equaling the ; value specified in the 'comebackdialtime' option elapses. exten => t,1,NoOp(End of the line for a timed-out parked call.) same => n,Playback(vm-goodbye) same => n,Hangup()
Custom Handling for Call Parking Timeouts
Finally, we will move on to explain how to handle situations where upon a parked call session timing out, it is not desired to return to the parked call to the device from where the call was originally parked. (This might be handy for situations where you have a dedicated receptionist or service desk extension to handle incoming call traffic). Just like the previous two examples, this is a basic scenario that only requires minimal adjustments to the following configuration files.
- res_parking.conf
- features.conf
- extensions.conf
Like before, our dialplan contains an extension to accept calls from the outside. Again, let's assume that the extension the caller dialed was: 5555001. The handler will then attempt to dial the alice extension, using the k option.
Sadly for our caller, the alice extension answers the call and immediately sends the DTMF digits to invoke the call parking feature without giving the caller a chance to speak. Just like in the previous scenario, the alice extension does not retrieve the parked call. Maybe the alice extension is having a bad day.
After a period of 300 seconds, or 5 minutes (as defined in the parkingtime option in res_parking.conf), the call will time out. Because we told Asterisk to send a timed-out parked call to the parkedcallstimeout context (comebacktoorigin=no), we are able to bypass the default logic that directs Asterisk to returning the call to the person who initiated the park. In our example, when a parked call enters our s extension in our parkedcallstimeout context, we only play a sound file to the caller and hangup the call, but this is where you could do any custom logic like returning the call to a different extension, or performing a lookup of some sort.
In summary:
- Outside caller dials 5555001.
- Alice picks up the device and says "Hello World!".
- Alice presses the one touch parking DTMF combination.
- The parked call times out after 300 seconds.
- Asterisk sends the call to the s extension in our parkedcallstimeout.
- Our caller hears, "Goodbye", before being disconnected.
res_parking.conf [general] [default] parkext => 700 ; Sets the default extension used to park calls. Note: This option ; can take any alphanumeric string. parkpos => 701-709 ; Sets the range of extensions used as the parking lot. Parked calls ; may be retrieved by dialing the numbers in this range. Note: These ; need to be numeric, as Asterisk starts from the start position and ; increments with one for the next parked call. context => parkedcalls ; Sets the default dialplan context where the parking extension and ; the parking lot extensions are created. These will be automatically ; generated since we have specified a value for the 'parkext' option ; above. If you need to use this in your dialplan (extensions.conf), ; just include it like: include => parkedcalls. parkingtime => 300 ; Specifies the number of seconds a call will wait in the parking ; lot before timing out. In this example, a parked call will time out ; if it is not un-parked before 300 seconds (5 minutes) elapses. findslot => next ; Configures the parking slot selection behavior. For this example, ; the next free slot will be selected when a call is parked. comebacktoorigin=no ; Determines what should be done with a parked call if it is not ; retrieved before the time specified in the 'parkingtime' option ; elapses. ; ; Setting 'comebacktoorigin=no' (like in this example) is for cases ; when you want to perform custom dialplan logic to gracefully handle ; the remainder of the parked call when it times out. comebackcontext=parkedcallstimeout ; The context that a parked call will be routed to in the event it ; times out. Asterisk will first attempt to route the call to an ; extension in this context that matches the flattened peer name. If ; no such extension exists, Asterisk will next attempt to route the ; call to the 's' extension in this context. Note: If you set ; 'comebacktoorigin=no' in your configuration but do not define this ; value, Asterisk will route the call to the 's' extension in the ; default context.
features.conf [featuremap] parkcall => #72 ; Parks the call (one-step parking). For this example, a call will be ; automatically parked when an allowed party presses the DTMF digits, ; #·7·2. A party is able to make use of this when the the K/k options ; are used when invoking the Dial() application. For convenience, the ; values of this option are defined below: ; K - Allow the calling party to enable parking of the call. ; k - Allow the called party to enable parking of the call.
extensions.conf [globals] ; Extension Maps 5001=alice ; Maps 5001 to a local extension that will emulate ; a party pressing DTMF digits from a device. ;5001=PJSIP/sip:alice@127.0.0.1:5060 ; What a realistc mapping for the alice device would look like. ; Realistically, 'alice' would map to a channel for a local device that would receive the call, therefore ; rendering this extension unnecessary. However, for the purposes of this demonstration, the extension is ; presented to you to show that sending the sequence of DTMF digits defined in the 'parkcall' option in ; 'features.conf' is the trigger that invokes the one-step parking feature. [parking-example] include => parkedcalls exten => alice,1,NoOp(Handles calls to alice.) same => n,Answer() same => n,Playback(hello-world) same => n,SendDTMF(#72w) same => n,Wait(300) same => n,Hangup() [from-outside] exten => 5555001,1,NoOp(Route to a local extension.) ; Dials the device that is mapped to the local resource, alice, giving the recipient of the call the ability ; to park it. Assuming the value of LocalExtension is 5001, the Dial() command will look like: Dial(alice,,k) same => n,Dial(PJSIP/alice) same => n,Hangup() [parkedcallstimeout] exten => s,1,NoOp(This is all that happens to parked calls if they time out.) same => n,Playback(vm-goodbye) same => n,Hangup()
References
<references />