- Digium phones when used with the DPMA
- Digium phones used with or without the DPMA
Digium phones when used with the DPMA
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:
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:
- Out of call messages must be accepted
- The context for out of call messages should be "dpma_message_context"
- Message Request authentication must be disabled
Thus, the settings are:
Additionally, use of the callcounter SIP configuration option is required for BLF state to properly operate. Thus:
callcounter may also be specified per-peer, instead of generally.
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.:
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:
The corresponding res_digium_phone.conf configuration parameters are:
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.
An example dialplan hint for watching status of a parking slot is:
Contacts subscribe_to URI
An example contacts XML file subscribe_to URI for watching parking slot 701:
Handling multiple parking lots
Beginning with the 1.4 release of the DPMA, Digium phones can be explicitly told which lots, inside of the Parking application, to present to the user. This is accomplished with the new "parking" phone application type within the DPMA configuration. Presented here is an example of configuring three phones, A, B, and C, to view one (A and B) or multiple (C) lots. Note that the Park softkey must still be mapped to park within a single lot only.
Begin by configuring res_digium_phone.conf. We will specify two parking applications, one that is tied to lot parkinglot_sales and another that is tied to parkinglot_support.
Then, still within res_digium_phone.conf, each of our three phones is configured to look at a particular lot. Phone C sees both lots.
Asterisk's feature.conf, which controls the built-in Parking feature of Asterisk, needs definitions for the lots parkinglot_salse and parkinglot_support.
Then, in extensions.conf, defined contexts for the parking lots:
And in the extension in which the Digium phones exist, included those contexts:
Thus, Phone A has a softkey that transfers to 800 and it can see other people parked in the "Sales" lot.
Phone B has a softkey that transfers to 850 and it can see other people parked in the "Support" lot.
Phone C has a softkey that transfers to 800 and it can see people parked in either lot.
When used with the DPMA, Digium phones can perform one touch call recording. Enabled in res_digium_phone.conf by the record_own_calls phone configuration parameter, one touch call recording presents a "Record" softkey on the phone's interface whenever the phone is on a call. If activated by the user, Asterisk begins recording both legs of the current call at the server-side and the softkey changes to "Stop Record." Pressing the "Stop Record" softkey directs Asterisk to cease recording the call, and the softkey returns to the "Record" state. Pressing the softkey again at this state will initiate a second, and separate recording session.
Recorded calls are stored by Asterisk in the Cust5 voicemail folder. This folder may be accessed directly by dialing the standard Asterisk voicemail application or by pressing the "Msgs" key on the phone, browsing to the folder list and selecting the "Recordings" folder. The "Recordings" folder, as presented by the Messaging application is mapped directly to the Cust5 folder by the DPMA. Recorded calls may be listened to, moved to other folders, or forwarded to other users on the system.
Call Queues Application
Digium phones, when used with the DPMA, have a built-in Queues application that allows for interaction with Asterisk's app_queue queue application. The Queues application on the phone is configured in the phone configuration section of res_digium_phone.conf by applying a queue application type to the configuration. The queue application has a number of parameters to control the queue, the member's name, the member's location, permission level, and login/out extensions.
The application, when loaded on the phone, provides 3 levels of permission: status, overview and details; each of which encompasses the previous permission's capabilities. The status view allows agents to manipulate their Pause status and their login/logout status on a per-queue basis or for all queues. The overview level allows agents or managers to also view, per queue, the number of members logged in / total assigned to a queue, the number of members on a call, the number of callers waiting, the total number of calls into the queue, the number of answered calls, and the number of abandoned calls. Additional statistical information within the overview section of the application is only available when Digium phones are used with Switchvox. The details level allows agents or managers to also view, per queue, the total number of waiting calls, the number of available/total members, the callers waiting in a queue with position and wait time, and the members on-call status.
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.
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().
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.
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.
PRESENCE_STATE Read 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.
DPMA Read Status Diaplan Example
In this example, the User Presence of device 100 is evaluated for the dnd and the xa (Extended Away) status. In the event that either of those statuses is true, the dialplan will route to the "dnd" label. In the even that both are false, the dialplan will route to the "notdnd" label.
Digium phones used with or without the DPMA
Send To, Transfer To and Dial Voicemail
Digium phones, when configured, have specific "to Voicemail" functionality that appears in three places:
- on incoming calls
- in the Contacts application for call transfers to voicemail
- in the Contacts application for a direct voicemail dial
For the 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 the 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, along with the can_transfer_vm Contacts application setting. Further, the Send and Transfer capability require the use of Certified Asterisk or the 10-digiumphones branch.
On an incoming call, Digium phones present four softkeys to the user:
- Answer - which causes the phone to answer the incoming call
- Ignore - which causes the phone to send a 603 REJECT back to Asterisk
- Transfer - which allows the callee to transfer the caller to a different extension
- 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."
When transferring a call, a callee can enter the Contacts application and select a "Transfer VM" option for a contact that has been configured with the "has_voicemail=1" option. When the callee pressees Transfer VM, the phone sends a DIVERSION header to Asterisk that contains a REDIRECTING reason "send_to_vm."
Direct VM Dial
Inside of the Contacts application, for contacts configured with the "has_voicemail=1" option, a "Dial VM" softkey is available. When the "Dial VM" softkey is pressed, the phone calls Asterisk with a SIP header X-Digium-Call-Feature "feature_send_to_vm."
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.
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:
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:
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 SIP peer 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 SIP peer 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 SIP peer, 301home.
The seventh step calls the voicemail application, but only after the call has also completed the sixth step of dialing SIP peer 301home.
Intercom and Monitor
Digium phones provide Intercom and Monitor softkeys that appear inside a contact's details. The keys presence is dependent upon the can_monitor and can_intercom Contact XML parameters as well as whether or not the contact is subscribed to. If all conditions are met, then the keys will appear. When the Intercom softkey is pressed, the contact is called with the SIP header X-Digium-Call-Feature feature_intercom. When the Monitor softkey is pressed, the contact is called with the SIP header X-Digium-Call-Feature feature_monitor. These headers can be parsed in the dialplan to invoke logic to call using a special Alert-Info header or to execute the chan_spy application.
The following presents a dialplan example of using the X-Digium-Call-Feature headers to handle Intercom and Monitor functionality.
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 sip peer. Here is a basic example:
Alternate Host / Failover
Digium phones, beginning with phone firmware 1.1 and the DPMA 1.3 suppor 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 SIP (sip.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 the 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.
Digium phones, beginning with firmware 1.1.0, may be remotely notified to reconfigure by using a check-sync SIP NOTIFY Event sent from the Asterisk CLI. This feature is enabled by default and is controlled by the:
Older, as well as current, depending on the release, versions of Asterisk may not have a properly configured sip_notify.conf file to allow sending the reconfigure notices from the Asterisk CLI. To enable this functionality, add the following lines to sip_notify.conf:
Following an Asterisk reload or restart, Digium phones may then be remotely sent reconfigure notices by executing the following Asterisk CLI command:
Ringtones loaded onto Digium phones using the 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: