Skip to end of metadata
Go to start of metadata

Digium phones when used with the DPMA

SIP Configuration

Configuration of a phone via the Digium Phone module for Asterisk alone is not enough to enable calling between the phone and Asterisk. As with any SIP device that connects to Asterisk, each Digium phone needs a corresponding entry in Asterisk's SIP configuration, i.e. sip.conf. Asterisk provides two types of entities within SIP: peers and friends. Use of either type is permissible, when configuring a Digium phone; however, use of the peer type means that Asterisk will not correctly match incoming calls where more than one SIP identity is assigned to the same phone (IP address). General practice then means that the friend type is the most flexible - as it matches on the From: username, whereas peer matches on IP and port (unless insecure=port has been set).

A minimum SIP.conf entry for a Digium phone then would look like:

SIP Configuration Entry Example
type = friend ; Use of "friend" is good practice, generally
nat = force_rport ; Good security practice dictates enabling nat support by default in both the general and individual phone sections
host = dynamic ; Dynamic in this case since the device is registering with us
secret = UseGoodPasswords ; Always use good passwords
disallow = all ; Good practice dictates disallowing codecs first, and then allowing only the ones we want
allow = g722 ; 16kHz at 64kbps
allow = ulaw ; 8kHz at 64kbps, North America
allow = alaw ; 8kHz at 64kbps, Worldwide
allow = g726 ; 8kHz at 32kbps
allow = g729 ; 8kHz at 8kbps - NOTE: This codec should not generally be enabled without installing Digium's G.729 transcoding module for Asterisk
allow = slin ; 8kHz at 128kbps - NOTE: This codec should generally not be used outside of a LAN
allow = slin16 ; 16kHz at 256kbps - NOTE: This codec should generally not be used outside of a LAN
context = myfancycontext ; The context that incoming calls from this device will arrive into
mailbox = mydigiumphone@default ; The voicemail box associated with the Digium phone

Additionally, as Digium phones make use of the out-of-call messaging capabilities within Asterisk, certain modifications to the [general] section of Asterisk's SIP configuration file must be made as well:

  1. Out of call messages must be accepted
  2. The context for out of call messages should be "dpma_message_context"
  3. Message Request authentication must be disabled

Thus, the settings are:

SIP General Section Requirements
accept_outofcall_message = yes
outofcall_message_context = dpma_message_context
auth_message_requests = no

Additionally, use of the callcounter SIP configuration option is required for BLF state to properly operate. Thus:

Additional SIP General Section Requirements

callcounter may also be specified per-peer, instead of generally.


1.0.0-beta1 versions of require that outofcall_message_context be set to phone_context. Versions after 1.0.0-beta1 default to dpma_message_context and have a corresponding configuration option in res_digium_phone.conf. If phone applications and provisioning are not working properly, please check the setting of outofcall_message_context.

Voicemail Configuration

All Digium Phones are provided with a Msgs hard button which calls the Voicemail application (visible in the list of Applications on the phone as well). When a Digium phone is not connected to the Digium Phone module for Asterisk, the Voicemail application simply dials a SIP URI, as configured, like any other SIP phone. However, if the Digium phone is connected to the DPMA and Asterisk is correctly configured, then the Msgs button will instead load a Visual Voicemail application that provides an enhanced user experience.

To configure Asterisk correctly, simply ensure that a mailbox entry in Asterisk's Voicemail configuration (voicemail.conf) matches the mailbox configuration parameter for a Digium Phone in res_digium_phone.conf, e.g.:

Voicemail Configuration Example for Voicemail Application
[fancycontext] ; The voicemail context name
100 => 12345,Bob Bobby, ; The mailbox, its password, the person's name, and their e-mail address
Digium Phones Configuration Example for Voicemail Application
[MyPhone] ; The identifier
type=phone ; A phone
mailbox=100@fancycontext ; Sets mailbox to mailbox 100 in the fancycontext of voicemail.conf
; Other Phone options, not the following fake ones, go here


When used in combination with the DPMA, Digium phones provide both a parking application as well as one-touch parking. The parking application allows the phone to retrieve a list of all parking lots present on the Asterisk server, along with the calls that are currently parked in each lot. From this list then, a phone may retrieve any parked call. The one-touch parking feature is a softkey on the phone's display that appears when a call is connected. The softkey transfers the connected call (attended or blind) to whatever parking lot extension the phone is configured to use.

In attended transfer mode, once the parking operation is completed, Asterisk will play a prompt back to the parker, indicating the lot number to which the call was parked, and the phone will hang up. That lot number may then be dialed in order to retrieve the call, or one may use the phone's Parking application to browse and directly retrieve a parked call.

In blind transfer mode, the default, once a park is completed, the phone will display a text message on its screen, indicating the lot number in which the call was parked, and the phone will hang up. One may then use the phone's Parking application to browse and directly retrieve a parked call.


Asterisk enables call parking by default with the features.conf parameters:

Features Configuration Example for Parking Application
parkext => 700 ; The extension to dial to park calls
parkpos => 701-720 ; The extensions onto which calls are parked
context => parkedcalls ; The default parking lot context

The corresponding res_digium_phone.conf configuration parameters are:

Digium Phones Configuration Example for Parking Application
parking_exten=700 ; The extension to program the phone to dial when a call is parked using the park softkey
parking_transfer_type=blind ; The type of parking to perform, blind or attended.

BLF Subscription to a Parking slot

BLF keys on phones are commonly tied to slots in Parking Lots, such that when a caller is waiting in a particular slot, e.g. 701, the lamp for a BLF tied to that parking slot is lit and the user may press the BLF button to retrieve the parked call from the lot.

Tying the status of a BLF lamp to the activity of a parking slot does not require setting the parking_exten, but it does require enabling Asterisk's parking feature, as well as a proper dialplan hint and a proper subscription URI on the Digium phone.


If parking_exten is not configured for a Digium phone, then the DPMA will not enable the one-touch parking feature of the Digium phone.

Dialplan hint

An example dialplan hint for watching status of a parking slot is:


Remember to include the context to which calls are parked into the same dialplan context as the Digium phone, as well as the Hint

Dialplan Example for Parking slot Hint
include => parkedcalls
exten => 701,hint,park:701@parkedcalls
Contacts subscribe_to URI

An example contacts XML file subscribe_to URI for watching parking slot 701:

Contacts Subscription URI for parking slot 701

User Presence

When used with the DPMA, Digium Phones are capable of seeing both device status and user presence. Device status is simply the device state one can subscribe to over SIP SUBSCRIBE, that maps directly to a hint in the diaplan. User presence is an entirely new concept to Asterisk, and expands upon the usage of dialplan hints, allowing them to represent both device state and user presence at the same time. Digium Phones not connected to the DPMA are capable of only Available and DND (Phone returns 486 to Asterisk) status. Digium Phones using the DPMA are capable of much more, with a Status application that allows users to change their presence on the server, opening up new methods for call routing based on user-presence, and not merely device presence.

Defining User Presence in Asterisk

The fundamentals of how user presence is represented in Asterisk mirrors the concepts currently used with device state. Device state changes are triggered by device state providers.

Example Device State provider mapped to extension.

Using the same pattern, user presence is changed by a CustomPresence user presence provider. A CustomPresence provider works in the same way a Custom device state provider does. CustomPresence providers are both defined and updated using a dialplan function, PRESENCE_STATE().

Example Device State and Presence State providers mapped to a single extension.

Manipulating User Presence through Dialplan and AMI

PRESENCE_STATE() Dialplan Function

User presence information is modified through the use of the PRESENCE_STATE() dialplan function. This function allows a custom user presence provider's information to be both read and written via the dialplan and AMI.

Write Syntax
Valid State Values
Valid Options
Read Syntax
Valid read fields arguments
Valid read options
Dialplan Examples
Dialplan Write Examples

Example1: Set Batman's state to "Away" with the subtype "In the batcave" with the message, "Making a new batch of batarangs".

Example2: Building on example1, now set Batman's state to "extended away" with no subtype while maintaining the message "Making a new batch of batarangs"

Example3: Setting the state as available without providing a subtype or message string. This will clear any previous message strings.

Example4: Set complex subtype and message strings using base64 encoding.

Dialplan Read Examples
Read Examples
AMI Examples

Example1: Setting both the user state and message using SetVar action in conjunction with PRESENCE_STATE() dialplan function.

Example2: Setting state information that must be base64 encoded because it contains newlines and/or commas.

Example3: Reading user state and message using GetVar action.

Example4: Reading subtype and message fields as base64 values.

User Presence in the DPMA

The DPMA does all of the user presence manipulation of the CustomPresence providers behind the scenes. Phones subscribe to a set of user extensions to receive both device state and user presence updates. The DPMA is in change of defining the hints the phones subscribe to, and mapping those hints to the correct device state and presence state providers. When a phone user updates their user presence, the DPMA internally updates that user's CustomPresence provider to reflect the change using the PRESENCE_STATE() dialplan function. This results in any watcher of the hint mapped to that CustomPresence provider receiving an update indicating the new user presence.

  • No labels