Sangoma Phones when used with DPMA
SIP Configuration
Configuration of a phone via the Desk 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 Sangoma phone needs a corresponding entry in Asterisk's SIP configuration. Further, use of DPMA assumes that out-of-call MESSAGE support has been enabled, and will require some specific "general" section parameters.
chan_pjsip
For chan_pjsip, a number of different types are configured, notably a transport, an aor, an auth, and an endpoint. The endpoint is the entity referenced in the DPMA for line configuration. A minimum pjsip.conf entry for a Sangoma phone then would look like:
[transport-udp] type=transport protocol=udp bind=0.0.0.0 [101] type = aor max_contacts = 1 mailboxes = 101@default [101] type = auth auth_type = userpass password = 101 username = 101 [101] type = endpoint aors=101 auth=101 callerid=Malcolm Davenport context = testing 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 Sangoma'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 direct_media = yes trust_id_inbound = yes send_pai = yes
Additionally, as Sangoma phones make use of the out-of-call messaging capabilities within Asterisk, a modification to the [general] section of Asterisk's chan_pjsip configuration file must be made as well. The modification is the definition of an endpoint, e.g. "dpma_endpoint," to bind to for the creation of outbound MESSAGE packets, as well as the configuration of chan_pjsip's "global" options to use this endpoint.
Thus, the settings are:
PJSIP General Section Requirements
[global] type = global default_outbound_endpoint = dpma_endpoint [dpma_endpoint] type=endpoint
chan_sip
For chan_sip, Asterisk provides two types of entities within SIP: peers and friends. Use of either type is permissible, when configuring a Sangoma 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 Sangoma phone then would look like:
SIP Configuration Entry Example
[mydigiumphone] 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 Sangoma'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 Sangoma phone
Additionally, as Sangoma phones make use of the out-of-call messaging capabilities within Asterisk, certain modifications to the [general] section of Asterisk's chan_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:
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=yes
callcounter may also be specified per-peer, instead of generally.
1.0.0-beta1 versions of res_digium_phone.so require that outofcall_message_context be set to phone_context. Versions after 1.0.0-beta1 default to dpma_message_context. If phone applications and provisioning are not working properly, please check the setting of outofcall_message_context.
Voicemail Configuration
All Sangoma 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 Sangoma phone is not connected to the Desk Phone module for Asterisk, the Voicemail application simply dials a SIP URI, as configured, like any other SIP phone. However, if the Sangoma phone is connected to 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 Sangoma Phone in res_digium_phone.conf, e.g.:
voicemail.conf
Voicemail Configuration Example for Voicemail Application
[fancycontext] ; The voicemail context name 100 => 12345,Bob Bobby,bobbobby@example.com ; The mailbox, its password, the person's name, and their e-mail address
res_digium_phones.conf
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 phoneoption=value phoneoption2=othervalue
Parking
When used in combination with DPMA, Sangoma 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.
res_parking.conf
Asterisk enables call parking by default with the res_parking.conf parameters:
res_parking.conf 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
res_digium_phone.conf
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 Sangoma phone.
If parking_exten is not configured for a Sangoma phone, then DPMA will not enable the one-touch parking feature of the Sangoma 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 Sangoma 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
subscribe_to="sip:701@10.24.13.224"
Handling multiple parking lots
Beginning with the 1.4 release of DPMA, Sangoma 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.
[sales-parking] type=application application=parking parkinglot=parkinglot_sales [support-parking] type=application application=parking parkinglot=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.
[phoneA] type=phone ... application=sales-parking parking_exten=800 parking_transfer_type=blind ... [phoneB] type=phone ... application=support-parking parking_exten=850 parking_transfer_type=blind ... [phoneC] type=phone ... application=support-parking application=sales-parking parking_exten=800 parking_transfer_type=blind ...
Asterisk's res_parking.conf, which controls the built-in Parking feature of Asterisk, needs definitions for the lots parkinglot_salse and parkinglot_support.
... [parkinglot_sales] parkext => 800 parkpos => 801-809 findslot => next parkingtime => 60 context => park-sales [parkinglot_support] parkext => 850 parkpos => 851-859 findslot => next parkingtime => 60 context => park-support ...
Then, in extensions.conf, defined contexts for the parking lots:
... [park-sales] exten => 800,1,Set(CHANNEL(parkinglot)=parkinglot_sales) exten => 800,n,Park() [park-support] exten => 850,1,Set(CHANNEL(parkinglot)=parkinglot_support) exten => 850,n,Park() ...
And in the extension in which the Sangoma phones exist, included those contexts:
include => park-sales include => park-support
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.
Call Recording
When used with DPMA, Sangoma 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 DPMA. Recorded calls may be listened to, moved to other folders, or forwarded to other users on the system.
Call Queues Application
Sangoma phones, when used with 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 Sangoma 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.
In order to view the on call duration for Members when using the Details-level permission, the Queue must be configured with the setinterfacevar=yes option in queues.conf.
User Presence
When used with DPMA, Sangoma 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. Sangoma Phones not connected to DPMA are capable of only Available and DND (Phone returns 486 to Asterisk) status. Sangoma Phones using 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.
A hint for extension 1111 is mapped to the PJSIP endpoint 1111 device state provider. In this example, endpoints subscribing to hint 1111 will receive a device state update anytime the device state changes for PJSIP endpoint 1111. exten => 1111,hint,PJSIP/1111 exten => 1111,1,Dial(PJSIP/1111) |
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.
A hint for extension 1111 is mapped to both the PJSIP endpoint 1111 device state provider and the CustomerPresence:1111 user presence provider. Endpoints subscribing to hint 1111 will receive both device state and user presence notifications for extension 1111. exten => 1111,hint,PJSIP/1111,CustomPresence:1111 exten => 1111,1,Dial(PJSIP/1111) |
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
PRESENCE_STATE(<presence state provider>)=value[,subtype[,message[,options]]] |
Valid State Values for Digium Phones
"available" "away" "xa" "chat" "dnd" "unavailable" |
Valid Options
e: Both subtype and message fields are base64 encoded. This is necessary for complex strings containing commas and newline characters. When this option is used, the PRESENCE_STATE function knows it must first base64 decode the subtype and message fields before setting them on the CustomPresence provider. |
Read Syntax
STATE_VALUE = ${PRESENCE_STATE(<presence state provider>,field[,options])}
|
Valid read fields arguments
value subtype message |
Valid read options
e: Base64 encode the return value when the field argument is subtype or message. |
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".
Set(PRESENCE_STATE(CustomPresence:Batman)=away,In the batcave, Making a new batch of batarangs) |
Example2: Building on example1, now set Batman's state to "Extended Away" (xa) with no subtype while maintaining the message "Making a new batch of batarangs"
Set(PRESENCE_STATE(CustomPresence:Batman)=xa,,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.
Set(PRESENCE_STATE(CustomPresence:Batman)=avaliable) |
Example4: Set complex subtype and message strings using base64 encoding.
Set(PRESENCE_STATE(CustomPresence:Blah)=away,${BASE64_ENCODE(business)},${BASE64_ENCODE(I will visiting clients in the San Diego area.\nI will be returning on Oct 11th.\nCall Josh for emergencies)})
|
PRESENCE_STATE Read Examples
SUBTYPE
${PRESENCE_STATE(<presence state provider>,subtype)}
MESSAGE
${PRESENCE_STATE(<presence state provider>,message)}
BASE64_SUBTYPE
${PRESENCE_STATE(<presence state provider>,subtype,e)}
BASE64_MESSAGE
${PRESENCE_STATE(<presence state provider>,message,e)}
AMI Examples
Example1: Setting both the user state and message using SetVar action in conjunction with PRESENCE_STATE() dialplan function.
Action: Setvar ActionID:1234 Variable: PRESENCE_STATE(CustomPresence:Batman) Value:away,In the batcave, Making a new batch of batarangs |
Example2: Setting state information that must be base64 encoded because it contains newlines and/or commas.
Action: Setvar ActionID:1234 Variable: PRESENCE_STATE(CustomPresence:Batman) Value:away,ISDW982KLJ90==,20DJKL23JK==,e |
Example3: Reading user state and message using GetVar action.
Action: Getvar ActionID:1234 Variable: PRESENCE_STATE(CustomPresence:Batman,value) Action: Getvar ActionID:1234 Variable: PRESENCE_STATE(CustomPresence:Batman,subtype) Action: Getvar ActionID:1234 Variable: PRESENCE_STATE(CustomPresence:Batman,message) |
Example4: Reading subtype and message fields as base64 values.
Action: Getvar ActionID:1234 Variable: PRESENCE_STATE(CustomPresence:Batman,subtype,e) Action: Getvar ActionID:1234 Variable: PRESENCE_STATE(CustomPresence:Batman,message,e) |
User Presence in DPMA
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. 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, 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.
exten => 100,1,NoOp()
same => n,GotoIf($["${PRESENCE_STATE(CustomPresence:100,value)}" = "dnd" | "${PRESENCE_STATE(CustomPresence:100,value}" = "xa"]?dnd:notdnd)
same => n(dnd),Playback(goodbye)
same => n,Hangup()
same => n(notdnd),Dial(PJSIP/100,20)
same => n,Hangup()