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

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

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

In features.conf you must configure the blindxfer or atxfer options in the featuremap section. The options are configureed with the DTMF character string you want to use for accessing the feature.

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

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.

See also

• https://wiki.asterisk.org/wiki/display/AST/Features - Features