Skip to end of metadata
Go to start of metadata

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

Loading a Contact List

Contacts files that the phone should load are defined in the phone's configuration XMl file and are served up by the DPMA. Contact file 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.

Rapid Dial Keys

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

  • blf_contact_group

The order of the contacts in this group is important. Those contacts fill in the BLF-keys in the same order as given in the xml, and those contacts are subscribed to, in order, up to a maximum of 40.

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

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

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

Specifies that the contact is a SIP contact

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 SIP peer name for a contact

subscribe_to

SIP URI

If the contact is to have a SIP subscription associated with it, the SIP URI

has_voicemail

boolean

Specifies whether or not a contact has a voicemail account associated with it. If so, then a context sensitive "to vm" softkey will be displayed for the contact.

can_monitor

boolean

Specifies whether or not a contact can be monitored (can have their calls listened to). If so, then a context sensitive "Monitor softkey will be displayed for the contact if the contact is subscribed to and the contact is on a call (IN USE)

can_intercom

boolean

Specifies whether or not a contact can be intercom'd. If so, then a context sensitive "Intercom" softkey will be displayed for the contact if the contact is subscribed to anad the contact is not on a call (IDLE)

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

When using the DPMA, the subscribe_to parameter should point to a special hint automatically created by the 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 the DPMA

When not using the DPMA, the subscribe_to parameter should instead point to a regular SIP URI, e.g.:

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

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

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

In both cases, use of the DPMA or not, the callcounter sip.conf parameter is still necessary.

Numbers

Number: Child Element of <numbers>

Option

Values

Description

dial

string

The number to dial

dial_prefix

string

A prefix to be added to a number before dialing. Currently not operable

label

string

A description of the number, e.g. "Extension" or "Mobile"

primary

boolean

Sets a number as the primary number for a contact. Only one primary number per contact is permissible.

Numbers

Icon

Definition of a primary number for a contact, e.g.:

is mandatory if that contact is attached to a Rapid Dial key. This number is the dialed number when the Rapid Dial key is pressed.

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.

  • No labels