There are several handler routines available to allow you to customize behavior for the different states of a call. Handler routines execute outside of the normal dialplan execution flow. It makes no sense to use the Hangup application in any of them and you must return from all of them. Most of the handlers operate from within the Dial application’s control.

Pre-dial handlers

The purpose of these routines is to setup a channel to place a call. The pre-dial routines can be run on the calling and called channels. See the Dial application documentation.

For the calling channel, you can do anything to the calling channel except hangup because you are still within the Dial application’s control. You might wonder why you would even need a pre-dial routine on the calling channel when you could do all the calling channel setup before executing the Dial application. The main reason is to eliminate a window of opportunity when using the LOCK and UNLOCK functions with Dial.

exten = _X.,1,NoOp()
same = n,NoOp(${LOCK(one_at_a_time)})
; Check if it is allowable to dial the endpoint
same = n,GotoIf($[my_allowable_check]?:lost_race)
same = n,Dial(PJSIP/100,,B(release_lock))
same = n,Hangup()

same = n(release_lock),NoOp(Caller pre-dial routine)
same = n,NoOp(${UNLOCK(one_at_a_time)})
same = n,Return

same = n(lost_race),NoOp(The extension is unavailable)
same = n,NoOp(${UNLOCK(one_at_a_time)})
same = n,Hangup()

• You have control of the media stream to and from the calling channel.
• There are no additional restrictions to using an AGI for these routines.

For the called channel, you can only setup the channel. At this point, the channel exists but is not connected to anything nor has the call been placed. Do your channel setup and return.

• There are no additional restrictions to using an AGI for these routines.

Redirecting interception handlers

This routine normally executes on the calling channel because the called channel has indicated that the call is being diverted, forwarded, or redirected to somewhere else. The purpose of this routine is to get the REDIRECTING party information setup as you want and then return. On return the updated redirecting party information is sent to the channel driver.

• You do not have control of the media.
• You should be quick about it.
• You can use an AGI for these routines. However, AGI’s by their nature are slower than normal dialplan.

Pre-bridge handlers

At this point the called channel has answered and all other called channels that were dialed have been hung up. The called channel is about to be bridged with the calling channel.

The main use of this routine is to give the called person an opportunity to decide if he even wants to talk to the caller. You have control of the media stream with the called party. You cannot hangup the channel in the routine because you must return. If you want to abort bridging the call with the channel you must set a return value as documented by the Dial application. You need to remember that the caller is waiting to be connected the entire time you are in this routine.

• You have control of the media stream to and from the called party.
• You can use an AGI for these routines. However, since you have control of the media, the AGI will eat any frames between actions which may not be desirable.

Connected-line interception handlers

At this point the channels are bridged together and may have been talking for awhile.

The purpose of this routine is to get the CONNECTEDLINE party information setup as you want and then return. On return the updated party information is sent to the channel driver. The bridged peer has changed identity likely because of a transfer.

• You do not have control of the media.
• You need to be quick about it or you risk causing a noticeable interruption to the media.
• You can use an AGI for these routines. However, AGI’s by their nature are slower than normal dialplan.

Dynamic DTMF features associated with dialplan routines

At this point the channels are bridged together and may have been talking for awhile.

Dynamic features allow you to execute dialplan routines when you press a DTMF key sequence associated with a Gosub. See the features.conf.sample file for documentation on how to configure the functionality.

• You have control of the media stream to and from the channel.
• You can use an AGI for these routines. However, since you have control of the media, the AGI will eat any frames between actions which may not be desirable.

Hangup handlers

At this point the channel is hungup and you should only be gathering information about the call for further processing later. You should not be doing extensive post call analysis at this time because you are delaying the channel technology hangup sequence. You have the same restrictions with the h extension.

• There are no additional restrictions to using an AGI for these routines.