Contacts

Contacts

Sangoma Phones provide a Contacts application that integrates speed-dial, device busy-lamp field and user presence. The Contacts application is related to the Status application in that both are concerned with presence. The Status application is concerned only with setting the local user's presence. The Contacts application is concerned with the presence status of other users - those to which it's been programmed to subscribe.

Contacts without presence subscriptions may be loaded locally onto the phone by the phone's user; however, this is not recommended. Most deployments of Sangoma phones will see the administrator specifying XML lists of contacts to load onto phones. Here, we will discuss the methods to direct the phone to load contacts as well as the contents of the contacts XML files.

Loading a Contact List

Contacts files that the phone should load are separate files, defined by DPMA or configured in the phone's main configuration XML file. For DPMA, Contacts files are specified for a phone configuration using the phone configuration parameter:

• contact

as noted above. Multiple "contact" lines may be used for each phone configuration.  For XML configuration, Contacts files are specified using the <contacts> element.

Rapid Dial Keys

Rapid Dial, or BLF, key subscriptions are set using the phone configuration parameter:

• blf_contact_group

This parameter, whether configured in res_digium_phone.conf for DPMA or in the blf_contact_group setting in XML, must be set to the group_name of the contacts group for which you wish subscriptions to be made.  Subscriptions cannot be made to more than one group_name.  Subscriptions will not be made if the blf_contact_group parameter is undefined. If you have skipped this step, you will not have blinking lights.  The use of Smart BLF capabilities is not independent of this setting; this setting must still be used for deployments using Smart BLF BLF Items lists.

If the Smart BLF capabilities of the phone are being used, whereby a BLF Items sheet is being loaded onto the phone, then each and every contact to be placed on a Rapid Dial key must be explicitly defined.  If no BLF Items sheet is loaded onto a phone, as-is the case with phones using firmware prior to 1.4.0, then the order of the contacts in this group is important. In that case, the named contacts here fill in the BLF-keys in the same order as given in the xml, and those contacts are subscribed to, in order.

Contacts XML skeleton

A basic Contacts XML structure is defined here:

Contactx XML Structure example

And, a more fleshed-out example looks like:

XML Contact Example

Contacts Element

Contact: Child Element of <contacts>

Make sure to include definitions for both first_name and last_name in your contacts XML file, even if one of them is to be blank. Failure to do so will lead to irregular sorting inside the phone's Contacts application.

Subscription URI

For SIP endpoints that are attached to a DPMA-configured Sangoma phone, the subscribe_to parameter should point to a special hint automatically created by DPMA. This hint is in the format "auto_hint_<peer>," e.g.:

In this case, it is not necessary to create a dialplan hint, as it is automatically created by DPMA.

For non-DPMA-configured endpoints, no "auto_hint" is created, and subscriptions should be a normal SIP URI that is provided by the target system, e.g..:

If your phone is registered using a transport other than the default, UDP, then the subscribe_to URI should look like:

or

or, simply to an extension, where the phone will automatically subscribe to the registered server, e.g.:

Also, when DPMA is not used, it is necessary to create a dialplan hint, e.g.:

Users of DPMA with older versions of Asterisk, or chan_sip instead of chan_pjsip, should note that the callcounter sip.conf parameter is necessary.

Emails

Email: Child Element of <email>

Actions

Action: Child Element of <actions>

Headers: Child Element of <actions>

Header: Child Element of <headers>

Wildcard Variables

Wildcard Variables can be used in Action Headers as part of the "substitute_value" of a Header. The following variables are allowed:

• %_ACCOUNT_USERNAME_% - The username of the account that is performing the action.

• %_ACCOUNT_SERVER_% - The server host of the account that is performing the action.

• %_ACCOUNT_PORT_% - The server port of the account that is performing the action.

• %_ACCOUNT_TRANSPORT_% - The transport used for SIP traffic on the account performing the action.

• %_ACCOUNT_ID_% - The unique account ID.

• %_ACCOUNT_AUTHNAME_% - The authentication string for the account.

• %_ACCOUNT_LINE_LABEL_% - The line label for the account.

• %_ACCOUNT_CALLER_ID_% - The caller ID string for the account.

• %_ACCOUNT_OUTBOUND_PROXY_% - The outbound proxy for the account.

• %_ACCOUNT_OUTBOUND_PORT_% - The outbound port for the account.

• %_ACCOUNT_ALT_SERVER_% - The alternate server for the account.

• %_ACCOUNT_ALT_PORT_% - The alternate port for the account.

• %_ACCOUNT_ALT_TRANSPORT_% - The alternate transport for the account.

Display Rules

Beginning with phone firmware 1.4, the Contacts application works in concert with the Smart BLF functionality provided by the rapid dial keys.  As actions are assigned to a contact, those actions are, by default, displayed when viewing the contact's information.

Whereas actions are tied to BLF keys using the Smart BLF capabilities, allowing differing functions depending on the state of the phone and/or of the target phone, Display Rules allow selective display of actions within the Contacts application also depending on the state of the phone and/or of the target phone.  A common scenario for this is the display of Intercom or Monitor actions.  When a contact is idle, it is reasonable that a user's phone might have an action to Intercom that contact, but might not have an action to Monitor that contact - if the contact isn't on a call, there's no reason to try to barge into a non-existent call.  And, while that same contact is on the phone, it is reasonable that a user's phone might have an action to Monitor that contact - if the contact is already on a call, it's not necessarily  a good idea to Intercom their phone.

Display Rules are configured using an XML fragment.  For DPMA users, the fragment is loaded from the file_directory as specified by the contacts_display_rules phone option.  XML configuration users may simply append the display_rules child node to the "contacts" appconfig.

Display Rules XML Example

Display Rules XML Example Expand source

Display Rules are parsed top down. and act as a black list.  Unless an action_id is present here, it will displayed at all times.  A way to show an action in only one state is to set it's show=0 then take that same action and show=1 in a specific state.

Display Rules Configuration

Voicemail Forwarding

Sangoma phones have a Voicemail application that allows the forwarding of voicemails to a Contact.  When a user engages the forward function from within the Voicemail application, the user is then presented with a filtered list of contacts to whom forwarding is possible.  The filtered list of contacts is defined by the set of contacts that are contained on a server with the same server_uuid as the current phone, that are of the type 'sip', 'zap', or 'virtual,' and that have an account_id that matches the target voicemail box.  Further, the receiving contact must also have a phone and line entry in res_digium_phone.conf.

Contact Pictures

Sangoma's D80 telephone can display pictures for contacts within its Rapid Dial application and Drawer as well as the picture for the phone's local user within the Navigation drawer.  Pictures should be in PNG format, 150 pixels wide, and 200 pixels high.  To find the local match the D80 will compare its own account_id from its account configuration to the account_ids of its loaded contacts for a match, and display the appropriate picture.  The D80 will download and cache contact pictures and will only perform a new download if the URL of the picture changes.

For Contact pictures, the D80 telephone can connect to regular HTTP urls as well as TLSv1.0 encrypted HTTPs URLs. For Contact pictures, the D80 does not support TLSv1.1 or TLSv1.2 HTTPs connections.