Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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.

...

Code Block
xml
xml
borderStylesolid
titleXML Contact Example
<phonebooks>
    <contacts group_name="PBX Directory" id="0">
        <contact
            server_uuid="abcdefg123"
            id="104"
            prefix="Mr"
            first_name="Robert"
            second_name="Davis"
            last_name="Jones"
            suffix="III"
            contact_type="sip"
            organization="Digium"
            job_title="Direction Manager"
            location="East Texas"
            notes="A rapscallion"
            account_id="104"
            subscribe_to="sip:104@1.2.3.4"
            picture="https://server.example.com/photos/myphoto.png"
            pickup_action="my_pickup_action"
        >
            <emails>
                <email address="rdj@mycompany.com" label="Work" primary="1" />
            </emails>
            <actions>
                <action id="primary" dial="104" dial_prefix="800555" label="Extension" name="Office" />
                <action id="send_to_vm" dial="104" dial_prefix="" label="Voicemail" name="Dial Voicemail">
                    <headers>
                        <header key="X-Digium-Call-Feature" value="feature_send_to_vm" />
                        <header key="Diversion" value="&lt;sip:%_ACCOUNT_USERNAME_%@%_ACCOUNT_SERVER_%:%_ACCOUNT_PORT_%&gt;;reason=&quot;send_to_vm&quot;" />
                    </headers>
                </action>
                <action id="my_pickup_action" dial="104" dial_prefix="**" label="Pickup" name="Pickup" />
             </actions>
        </contact>
     </contacts>
    <contacts group_name="Default" id="Default">
    ....
    </contacts>
    <contacts group_name="Family Members" id="anythingyouwant">
    ....
    </contacts>
</phonebooks>

...

Option

Values

Description

server_uuidstringOptional. 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, zap, virtual and many more

Specifies the type of contact. SIP contacts are subscribed to for device and user presence, so this type should be used for DPMA-configured contacts. Special contacts are subscribed to for device presence only, so this type should be used for all other contacts that require any state awareness. Zap contacts are Switchvox-configured DAHDI-based contacts. Virtual contacts correspond to Switchvox virtual extensions. A full listing of contact_types may be found here - http://developers.digium.com/switchvox/wiki/index.php/Extension_Types

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. The SUBSCRIBE will only be made, even if this parameter is populated, if the group_name of this contact's group matches the blf_contact_group phone setting - as defined in res_digium_phone.conf or in the phone's XML config.

pictureURLSpecifies the location of the picture for the contact
pickup_actionstringSpecifies the action to be called for call pickup activity cards on the D80.
Warning

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.

Info
titleSubscription URI

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

Code Block
xml
xml
subscribe_to="auto_hint_1234"

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

Code Block
xml
xml
subscribe_to="sip:500@my.pbx.com"
Tip

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

Code Block
subscribe_to="sip:500@my.pbx.com:5060;transport=tcp

or

Code Block
subscribe_to="sip:500@my.pbx.com:5061;transport=tls

 

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

Code Block
xml
xml
subscribe_to="500"

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

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

...

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.

Magic action ids "intercom," "monitor," "sendtovm" and "dial_vm" will result in special icons displayed for the action.

dial

string

optional, number, e.g. 1234, or URI like sip:host or sip:user@host, 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

...

  • %_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.

...

Digium 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, and 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

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