Skip to end of metadata
Go to start of metadata

Digium phones used with or without DPMA


users.conf as a means of configuration of Asterisk for use with Digium phones is not supported.

Send To, Transfer To and Dial Voicemail

Digium phones, when configured, have specific "to Voicemail" functionality that appears on a dedicated softkey during incoming calls.  


Versions of firmware prior to 1.4 had voicemail dialing and transferring capability mapped to a special softkey inside the contacts application, as controlled by the "has_voicemail" contacts option. This option has been replaced by dedicated <action> definitions as documented on the Smart BLF page and its examples.

For DPMA, this functionality is controlled by the "send_to_vm" phone configuration option in res_digium_phone.conf. This option is enabled by default by DPMA. It is disabled by default for phones provisioned manually. To enable manually-provisioned phones to use this functionality, the send_to_vmail keymap must be enabled. Further, the Send and Transfer capability require the use of Asterisk 12, Asterisk 11, Certified Asterisk 1.8 or the 10-digiumphones branch - due to the DIVERSION header support requirement.

Incoming Calls

On an incoming call, Digium phones present four softkeys to the user:

  1. Answer - which causes the phone to answer the incoming call
  2. Ignore - which causes the phone to send a 603 REJECT back to Asterisk
  3. Transfer - which allows the callee to transfer the caller to a different extension
  4. Send VM - which allows the callee to transfer the caller directly to the callee's voicemail box.

When the Send VM softkey is pressed, the phone sends a DIVERSION header to Asterisk that contains a REDIRECTING reason "send_to_vm."

Dialplan example

The following presents a dialplan example of using the DIVERSION header and the X-Digium-Call-Feature header to handle Send to VM, Transfer to VM, and Direct VM dial.

Example: Example dialplan for Send To, Transfer To, and Dial Voicemail
exten => 301,1,NoOp()
same => n,GotoIf($["${REDIRECTING(reason)}" = "send_to_vm" | "${PJSIP_HEADER(read,X-Digium-Call-Feature)}" = "feature_send_to_vm"]?vm:notvm)
same => n(vm),Voicemail(301)
same => n,Hangup()
same => n(notvm),Dial(PJSIP/301,20)
same => n,Dial(PJSIP/301home,20)
same => n,Voicemail(301)

The first step in this example performs no operation.

The second step in this example performs a GotoIf. If true, it jumps to the "vm" priority label. If false, it jumps to the "notvm" priority label. Two cases are evaluated. The first case:

${REDIRECTING(reason)}" = "send_to_vm"

checks for the presence of the "send_to_vm" DIVERSION header. This occurs when the phone user performs a Send To or a Transfer to Voicemail. The second case:

${PJSIP_HEADER(read,X-Digium-Call-Feature)}" = "feature_send_to_vm"

checks for the presence of the "feature_send_to_vm" X-Digium-Call-Feature header. This occurs when the phone user directly dials a contact's voicemail from the Contacts application.
If either case is true, meaning that the phone user wanted to either Send To, Transfer To, or directly dial another user's voicemail box, then the dialplan will jump to the "vm" priority. If both cases are false, the dialplan will jump to the "notvm" priority.

The third step is the "vm" priority label. It calls voicemail box 301.

The fourth step follows the vm priority label. If the vm priority label is reached, because the call was supposed to go to a destination, and we've completed the voicemail application from the third step, this step explicitly hangs up the call - not normally necessary, but included for the sake of completion.

The fifth step is the "notvm" priority label. It calls SIP peer 301.

The sixth step in this example, the Dialing of PJSIP endpoint 301home, will be reached if the callee, on an incoming call, presses the "Ignore" softkey. In that case, the caller has called extension 301 without a DIVERSION or X-Digium-Call-Feature header, so the dialplan has proceeded to Dial PJSIP endpoint 301. Asterisk receives a 603 REJECT when the callee presses the Ignore softkey. Asterisk then continues in the dialplan to the next step, which in this case is dialing a different PJSIP endpoint, 301home.

The seventh step calls the voicemail application, but only after the call has also completed the sixth step of dialing PJSIP endpoint 301home.

Intercom and Monitor

The Intercom and Monitor softkeys inside a contacts details have been replaced by the use of defined Smart BLF <action>s.  The older behavior of defining can_monitor and / or can_intercom has been deprecated.  For more information about using <action>s to achieve this functionality, please read the Smart BLF examples.

Dialplan example

The following presents a dialplan example of using the X-Digium-Call-Feature headers to handle Intercom and Monitor functionality.

exten => _[1-2]XX,1,NoOp()
same => n,GotoIf($["${PJSIP_HEADER(read,X-Digium-Call-Feature)}" = "feature_monitor"]?monitor:notmonitor)
same => n(notmonitor),GotoIf($["${PJSIP_HEADER(read,X-Digium-Call-Feature)}" = "feature_intercom"]?intercom:notintercom)
same => n,(intercom)Dial(PJSIP/${EXTEN},20,b(handler-intercom^addheader^1))
same => n,Hangup()
same => n(notintercom),Dial(PJSIP/${EXTEN},20)
same => n,Hangup()
same => n(monitor),ChanSpy(PJSIP/${EXTEN},q)
same => n,Hangup()

exten => addheader,1,Set(PJSIP_HEADER(add,Alert-Info)=<intercom>)

Connected Line Updates

Digium phones support connected line updates using the P-Asserted Identity method. Connected line updates allow for dynamic caller id updates during call transfers. To enable Digium phones to receive and send updates, the SIP peer for the Digium phone must be setup using the trustrpid and sendrpid configuration options. Further, unless you are taking advantage of the Connected Line function, you will need to explicitly set a Caller ID for the PJSIP endpoint. Here is a basic example:

callerid=Malcolm Davenport
context = testing
disallow = all
allow = g722
trust_id_inbound = yes
send_pai = yes

Alternate Host / Failover

Digium phones, beginning with phone firmware 1.1 and DPMA 1.3, support simultaneous registration to two hosts. In the event that the primary host is unreachable, calls are be placed to the secondary host instead. When the primary host is down, only call services are supported on the alternate system; status, voicemail, parking, queues, etc. are not functional. Registration to the alternate host is done over normal SIP registration, not via DPMA, so no res_digium_phone entry for the phone is required, only PJSIP (pjsip.conf) configuration.

When the primary host is unavailable, the phone will display a failover icon in 20-30 seconds. When the primary host becomes available again, the phone will switch back to it once the phone detects its availability. In DPMA, registration to this alternate host is controlled via the alternate_registration_address and alternate_registration_port network options. If those options are present, the phone will apply that alternate host to all internal lines. For phones manually provisioned via XML, see the host_alternate XML configuration parameter.


Ringtones loaded onto Digium phones using DPMA or using XML provisioning should be 16-bit, 16kHz raw signed linear audio files. .wav files are not acceptable. If a .wav file is used, distortion may be heard in the audio as the phone plays back the ringtone. In order to generate a raw signed linear audio file from a .wav file, the sox utility, or any other audio manipulation utility that can handle .wav and raw signed linear files can be used.

To convert a .wav file into an appropriate signed linear file, using the sox utility, the following command-line example should be used:

sox -V myfile.wav -t raw -r 16000 -s -w -c 1 myfile.sln

Downsampling higher bitrate files, e.g. 48kHz, to lower bitrate files, e.g. 16kHz as used for ringtones, is acceptable. Upsampling lower bitrate files to higher bitrates, e.g. 8kHz to 16kHz, will produce files that do not sound pleasing.

Asterisk SIP Debug, Phone Startup

From a chat session:

2:54:13 PM malcolmd: Asterisk should see a SIP MESSAGE packet from the phone with X-Digium-AppServer-RequestType: Handshake
12:54:33 PM malcolmd: we'll send a 202 back to the phone if everything is good
12:55:00 PM malcolmd: then we'll send a SIP MESSAGE back to the phone with X-Digium-AppServer-ResponseType: HandshakeResponse
12:55:09 PM malcolmd: then we should see a 200 from the phone
12:55:42 PM malcolmd: then, the phone will send us a SIP MESSAGE with X-Digium-AppServer-RequestType: ConfigRequest
12:55:51 PM malcolmd: then we'll send back a 202 to the phone
12:56:09 PM malcolmd: then we'll send a SIP MESSAGE to the phone with X-Digium-AppServer-ResponseType: ConfigResponse
12:57:13 PM malcolmd: that may take several SIP MESSAGE packets
12:57:56 PM malcolmd: we'll get a 200 OK from the phone for each of them (probably after all of the ConfigResponse packets have gone out, maybe a dozen packets)
12:58:19 PM malcolmd: then the phone will send us a SIP MESSAGE with X-Digium-AppServer-RequestType: FileRequest
12:58:36 PM malcolmd: then we'll send it a 202 Accepted
1:01:01 PM malcolmd: then we'll do the dance of sending SIP MESSAGE X-Digium-AppServer-RequestType: FileResponse packets to the phone, again maybe lots of packets, and the phone sending back 200 OK packets

Other Stuff

We use AES-128-CBC for crypto between phones and DPMA.

  • No labels