Contacts

Contacts

Contacts

Digium 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 Digium 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.

Beginning with the DPMA 1.3, Digium phones can support storing phone-added contacts on the Asterisk server. To support server-side storage of contacts that are added, by the user, locally on the phone, the editable option for a phonebook must be set to 1 and an identifier, as set by the id option must be unique for the phonebooks loaded by that phone.

Icon

Though it is possible to add server-side contacts from the phone, those contacts are not editable from the phone, deletable from the phone, or configurable with a subscription URI. Digium thus advises that the best practice is to only edit contacts from the server side, not from the phone.

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

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

Icon

Because Contacts, BLF Items and Display Rules are constructed in XML, and because Digium phones do not point out XML errors to you, it is very important to verify the syntax of your XML before sending it to the phone. If your syntax is invalid, the XML file will fail to load, and you might wonder why your Contacts don't show up, your BLF Items don't seem to work, or your Display Rules are ignored. So, you should use an XML editor or some other tool (Chrome, xmllint, etc.) to verify your syntax before sending XML to the phone.

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

Option	Values	Description
group_name	string	Defines the name of a contacts group. This name is used in the Contacts application to organize contacts by group
editable	boolean	Sets whether or not the group can be editable from the phone. If the phone is configured for server-side contacts storage and the editable option is set for a group, a contact may be added to that group from the phone
id	string	Unique identifier for a group

Contact: Child Element of <contacts>

Option	Values	Description
server_uuid	string	Optional. Specifies the uuid of the server to which this contact is attached. If this is a contact on a DPMA-enabled server, this should be the same as the server_uuid of that server. If server_uuid is set for contacts, it must also be set in the DPMA general section. If it is only set in one location (contact or general) instead of both, forwarding of voicemails to contacts is not permitted.
id	string	Sets a unique identifier for the contact, used by blf_item definitions
prefix	string	Sets the prefix title for a contact, e.g. "Mr."
first_name	string	Specifies the first name for a contact
second_name	string	Specifies a second name for a contact
last_name	string	Specifies a final name for a contact
suffix	string	Sets a suffix for a contact, e.g. "Jr."
contact_type	sip, special	Specifies the type of contact. SIP contacts can be subscribed to for device and user presence (when DPMA is in use). Special contacts are subscribed to for device presence only.
organization	string	Sets an organization for a contact
job_title	string	Specifies a job title for a contact
location	string	Sets a location for a contact, e.g. "Las Vegas"
notes	string	Allows for provision of notes about a contact
account_id	string	If the contact is associated with a contact local to the system, the PJSIP endpoint name for a contact
subscribe_to	SIP URI	If the contact is to have a SIP subscription associated with it, the SIP URI

Icon

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

Icon

For SIP endpoints that are attached to a DPMA-configured Digium 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..:

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.:

exten => 1234,hint,PJSIP/mypeer
exten => 1234,1,NoOp()
exten => 1234,n,Dial(PJSIP/mypeer,20)

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>

Option	Values	Description
address	string	The e-mail address of the contact
label	string	A description of the e-mail address, e.g. "Work" or "Home"
primary	boolean	Sets an email as the primary e-mail for a contact. Only one primary email per contact is permissible.

Actions

Action: Child Element of <actions>

Option	Values	Description
id	string	mandatory, unique identifier for the action, used by blf_item definitions. One id with the reserved name "primary" should be used for each contact, to designate the primary action, that occurs when no other action is matched.
dial	string	optional, number to be passed to the phone application and dialed for this action
dial_prefix	string	optional, number to be prepended before dial, where be passed to the phone application and dialed for this action
app_id	string	optional, identifier for an application to which events or functions are sent. The identifier should be either one of the phone default applications (contacts, voicemail, parking, status, queues) or should be the identifier of a user-loaded custom application.
label	string	mandatory, pertinent information about the number for the Contacts application, e.g. SIP Extension, Cell; appears to the left of the number or application within the contact's information screen
name	string	mandatory, a name for this action, used as its language key within applications, e.g. custom applications; appears to the right, in square brackets, of the number or application within the contact's information screen

Headers: Child Element of <actions>

Header: Child Element of <headers>

Option	Values	Description
key	string	Key value of the header applied to the action
value	string	optional, value to be matched with the key, may incorporate wildcard values

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.

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

Option	Values	Description
id	unique id	A unique identifier for this display_rule, e.g. 0, 1, 2, etc.
action_id	A valid action as defined in the phone's Contacts file	Sets the action_id for the display rule to act upon
phone_state	idle, hold, transfer, incoming/transfer, incoming, connected, dialing, calling, failed	Defines the state of the local phone during which the rule will be acting. If not specified in a rule, all states are matched. Note that this list of states differs from the larger list of states available for BLF key action mappings.
target_status	unknown, idle, on_hold, ringing, on_the_phone	Optional. Sets the status of the subscribed to contact that must be matched for this display rule to be in effect
show	Boolean	If set to yes, shows a particular action; if set to no, hides the action. To hide an action for all states and only show it for some states, first declare the action to have a false show, then declare it to have a true show for only a particular state or states.