Phones - Smart BLF

Smart BLF encompasses the behaviors of Sangoma’s Rapid Dial keys that are available beginning with the 1.4 phone firmware.  Compared to the previous behavior of the Rapid Dial keys, Smart BLF provides an entirely new world of configuration possibilities.  This page contains both a complete description of the BLF Items capabilities as well as practical examples of Smart BLF usage with Sangoma phones.

BLF Items

BLF Items defines the absolute key location of contacts, including assignment to a fixed page or the assignment of blank keys, as well as the behavior of the key, specifically the actions taken by the phone when the key is pressed, optionally depending on the press duration as well as the state of the phone and the status of a target phone.  Further, BLF Items allows control over the LED indicators and local-ringtone playback.

BLF Items is contained in a separate XML sheet that is retrieved by the Sangoma phone by URL.  

For DPMA users, it is defined using the blf_items phone option, e.g.:

Where the XML sheet, myblfitems.xml is retrieved from the file_url_prefix according to the phone's current network.

For XML configurations, it is configured using the <smart_blf> node, e.g.:

BLF Items in XML Provisioning Example

If a Smart BLF sheet is loaded onto a phone, then each contact to be mapped to a Rapid Dial key must be explicitly defined in that sheet. If a contact is not explicitly mapped to a key, it will not show up on a key. This behavior differs from the older, pre 1.4.0 firmware behavior of automatically attaching, in order, listed contacts to Rapid Dial keys.

BLF Items XML skeleton

Because Contacts, BLF Items and Display Rules are constructed in XML, and because Sangoma 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 BLF Items XML structure is defined here:

BLF Items Structure example

And, a more complete example looks like:

BLF Item Example

BLF Item Element

Behaviors: Child element of <blf_item>

Behavior: Child element of <behaviors>

A behavior exists to define the operation of the phone when a particular Rapid Dial Key is pressed.  More than one behavior may be defined for a particular BLF Item.  Behaviors are processed top-down; so, less-specific behaviors should precede more-specific behaviors.

Phone States

There are a number of valid Phone States as used by BLF Items Behaviors.  Valid states and descriptions are listed in the following table:

Indicators: Child element of <blf_item>

Indicator: Child element of <indicators>

Behavior Considerations

When creating behaviors, the following points should be taken into consideration.

Top Down Processing

Behaviors are processed top-down.  Where one has the following:

Top-Down Example Collapse source

and where two behaviors, both for the same phone_state are defined, only the first behavior will operate when the state is true.  The second behavior, because it was not loaded first, will be discarded.

But if I have two behaviors. one of which is more specific than the first, such as:

Top-Down, Add Specificity Example Collapse source

then, where the phone is in a state other than dial, the press_action will be callb.  When the phone is in the dial state only, the press_action will be callc.

Default Behaviors

Default behaviors are driven by default actions.  If there are no behaviors defined, e.g.:

No Defined Behavior Example Collapse source

or if there are only behaviors defined for states in which the phone does not currently find itself, e.g. where a phone is actually in the idle state not the dial state:

Not Current State Default Behavior Example Collapse source

and where only a single action is configured for the contact 101 like:

Only One Action Example Collapse source

then, when pressed, the Rapid Dial key will perform the only listed action, 101 as that action will be treated as the default action, since no other actions exist.

Selective Behavior Enabling

If you want to default no behavior for an item, and only explicitly define limited behavior, it is best to first define none functions for all states, such as:

Selective Behavior Enabling Example Collapse source

Thus, the only state in which any action will be possible is the dial state.

Long-Press Function Default

The default behavior for long_press_action is info, so the information about a contact will always be loaded when a key is long_pressed unless the long_press_function is otherwise defined.

Use Cases

Call Pickup

Traditionally, Call Pickup within Asterisk is generally performed using a separate extension handler that, rather than dialing the target phone directly using the Dial() application, instead uses the Pickup() or PickupChan() application with an extension prefix.  And, Call Pickup is only performed when the target phone is ringing.  Otherwise, the target phone is dialed normally.  Assuming 3-digit extensions, dialplan for this might look like:

Pickup Dialplan Example Collapse source

First, we've defined a normal pattern match 1XX - one, followed by two digits 0-9.  If matched, Asterisk performs a dial to that SIP device.

Next, we've defined an extern pattern match on **1XX - all dialed patterns beginning with two * characters, followed by 1, then two more digits 0-9.  In the case that it's matched, Asterisk will perform a pickup against the ringing extension, stripping off the first two ** characters.

To affect this, our Sangoma phone needs a contact that is configured with two actions: one, called 103 to dial the contact normally, and another called pickup that dials using a prefix.  The contact configuration thus looks like:

Pickup Contacts Example Collapse source

Here, note that we've created the actions 103 and pickupcall.  For 103, only 103 is dialed.  For pickupcall, phone will dial the ** prefix first, and then 103.

Next, we need to configure the behavior of a Rapid Dial key to affect the actions.  Configuration for this resembles:

Pickup BLF Items Example Collapse source

Here, notice that we have defined two behaviors.  Because behaviors are processed top-down, we first define a behavior with press_action of 103 and press_function of dial.  This will cause the phone for all phone_states and all target_states (the implied behavior when not explicitly defining them) to call the 103 action.  

Next, we define a behavior where the target_status is ringing, we've set the press_action to pickupcall (which is the identifier of the pickup action that we created for the Contact), and the press_function is set to dial.  Because we defined a pickup_action within the contact itself, and because we have a ringing target_status behavior, this will cause the D80 model phone to display a pickup activity card in its activity stream, beginning with firmware 1.8.0.

Thus, when Mark Spencer's phone is ringing, based on a subscription NOTIFY from Asterisk, and someone presses this Rapid Dial key, the phone will dial **103 into Asterisk, which will in turn call the Pickup() application.  And, when Mark Spencer's phone isn't ringing, and someone presses this Rapid Dial key, the phone will dial 103 into Asterisk, which will call the Dial() application and ring the phone normally.

Intercom

In the following example, we assume that users want to call another party as the standard action of pressing a Rapid Dial key, but that when a Rapid Dial key is long-pressed (held down for 3 seconds or more) and the target is idle, that the user wants to Intercom the target.  

Assuming 3-digit extensions, dialplan for this might look like:

Intercom Dialplan Example Collapse source

Here, we've defined an extern pattern match on 1XX - all 3-digit dialed patterns beginning with 1 followed by two more digits 0-9.  In the case that it's matched, Asterisk will first perform a GotoIf() depending on the presence of an X-Digium-Call-Feature matching feature_intercom.  Where feature_intercom is matched, the dialplan jumps to the intercomcall label where a Dial is performed using a pre-dial handler to utilize the PJSIP_HEADER dislplan function that will add an Alert-Info header to the outgoing SIP INVITE before performing the Dial.  Otherwise, when feature_intercom is not matched, the dialplan jumps to the notintercomcall label and performs a regular Dial() without adding any special headers.

To affect this, our Sangoma phone needs a contact that is configured with two actions: one, called 103 to dial the contact normally, and another called intercom that dials with a special header.  The contact configuration thus looks like:

Intercom Contacts Example Collapse source

Here, note that we've created the actions 103 and myintercom.  For 103, only 103 is dialed.  For myintercom, phone will also dial 103, but a header will be appended to the outgoing INVITE from the phone to Asterisk

Next, we need to configure the behavior of a Rapid Dial key to affect the actions.  Configuration for this resembles:

Intercom BLF Items Example Collapse source

Here, notice that we have defined two behaviors.  Because behaviors are processed top-down, we first define a behavior with press_action of 103 and press_function of dial.  This will cause the phone for all phone_states and all target_states (the implied behavior when not explicitly defining them) to call the 103 action.  

Next, we define a behavior where the target_status is idle, we've set the long_press_action to myintercom (which is the identifier of the pickup action that we created for the Contact), and the long_press_function is set to dial.  

Thus, when Mark Spencer's phone is idle, based on a subscription NOTIFY from Asterisk, and someone performs a long press on this Rapid Dial key, the phone will dial 103 with a special X-Digium-Call-Feature header of feature_intercom into Asterisk, which will get handled by the dialplan to prepend an Alert-Info to the outgoing INVITE to Mark's phone.  And, when Mark Spencer's phone isn't idle, and someone presses this Rapid Dial key, the phone will dial 103 into Asterisk, which will call the Dial() application and ring the phone normally.

Call Monitor

Much like Call Pickup and Intercom, both within Asterisk are generally performed using a separate extension handler that rather than calling a direct Dial() to the phone, unless you've followed the above example and been more creative using X-headers.  As before, this example for Call Monitor will make use of an arbitrary SIP header that we'll configure the Sangoma phone to attach.  In this example, we assume that users want to call another party as the standard action of pressing a Rapid Dial key, that when the Rapid Dial key is long-pressed and the target is idle, that the user wants to Intercom the target, and that if the Rapid Dial key is long-pressed and the target is on the phone, that the user wants to Monitor the target.

Assuming 3-digit extensions, dialplan for this might look like:

Call Monitor Dialplan Example Collapse source

Here, we've defined an extern pattern match on 1XX - all 3-digit dialed patterns beginning with 1 followed by two more digits 0-9.  In the case that it's matched, Asterisk will first perform a GotoIf() depending on the presence of an X-Digium-Call-Feature matching feature_intercom.  Where feature_intercom is matched, the dialplan jumps to the intercomcall label where a pre-dial handler calls the PJSIP_HEADER dial plan function to add an Alert-Info header to the outgoing SIP INVITE before performing the Dial.  Otherwise, when feature_intercom is not matched, the dialplan jumps to the notintercomcall label.  The notintercomcall label performs another GotoIf check.  If the feature_monitor header is present, then the dialplan jumps to monitorcall to a ChanSpy() application to monitor the call.  If the feature_monitor header is not present, the dialplan jumps to donotmonitorcall to a normal Dial().

To affect this, our Sangoma phone needs a contact that is configured with three actions: one, called 103 to dial the contact normally, another called myintercom that dials with a special header, and a third called mymonitor also with a special header.  The contact configuration thus looks like:

Call Monitor Contacts Example Collapse source

Here, note that we've created the actions 103 and myintercom and mymonitor.  For 103, only 103 is dialed.  For myintercom, phone will also dial 103, but a header will be appended to the outgoing INVITE from the phone to Asterisk.  An,d for mymonitor, the phone will also dial 103, but a different header will be appended to the outgoing INVITE.

Next, we need to configure the behavior of a Rapid Dial key to affect the actions.  Configuration for this resembles:

Call Monitor BLF Items Example Collapse source

Here, notice that we have defined three behaviors.  Because behaviors are processed top-down, we first define a behavior with press_action of 103 and press_function of dial.  This will cause the phone for all phone_states and all target_states (the implied behavior when not explicitly defining them) to call the 103 action.  

Next, we define a behavior where the target_status is idle, we've set the long_press_action to myintercom (which is the identifier of the pickup action that we created for the Contact), and the long_press_function is set to dial.  

Finally, we define a behavior when the target_status is on_the_phone, where we've set the long_press_action to mymonitor.

Thus, when Mark Spencer's phone is idle, based on a subscription NOTIFY from Asterisk, and someone performs a long press on this Rapid Dial key, the phone will dial 103 with a special X-Digium-Call-Feature header of feature_intercom into Asterisk, which will get handled by the dialplan to prepend an Alert-Info to the outgoing INVITE to Mark's phone.  When Mark's on the phone, the header of feature_monitor will be sent, and ChanSpy will be called to listen to Mark's conversation.  Otherwise, when someone presses this Rapid Dial key, the phone will dial 103 into Asterisk, which will call the Dial() application and ring the phone normally.

Call Parking

Sangoma phones include a built-in Parking application, visible in the Applications menu, and have a dedicated Park soft-key, visible on the main screen while a call is in-progress, that can be exposed when the phones are configured using DPMA.  In addition to these features, it is also possible to configure a Rapid Dial key to serve both functions.  For our example, pressing a rapid dial key while a call is connected will automatically transfer the caller to the parking lot.  And, pressing the same rapid dial key while the phone is idle will load the parking application into the foreground, from which callers can be picked.  To do this, we will take advantage of Asterisk's built-in res_parking.conf-based call parking along with its built in feature-code mapping in features.conf.  First, call parking must be enabled in res_parking.conf, which looks like:

Call Parking res_parking.conf Example Collapse source

and then to handle in-call DTMF for parking, then in features.conf like:

Call Parking featues.conf Example Collapse source

Here, we've setup the main parking extension as 700, we've setup 20 lots, numbered 701-720, and we've set the in-call feature sequence that parks calls as #72.

Wondering why you can't re-park a previously parked call? Or, wondering why you can't do DTMF-based transfers of previously parked calls? Take a look at the parkedcalltransfers and parkedcallreparking (and other) options in features.conf. They're disabled by default, so, to enable that capability, they'll need to be enabled.

Next, we need to make sure our Dialplan is constructed to include the parkedcalls context like so:

Call Parking Dialplan Example Collapse source

Here, our sample context testing includes the necessary components, automatically generated by features.conf.  And, our Dial() application includes the k and K flags, which lets the called and calling parties park the other caller by dialing the proper DTMF sequence.

To affect this, our Sangoma phone needs a contact that is configured with two actions: one, called parkme to perform the actual parking of the caller, and another called showparking that loads the parking application into the foreground.  The contact configuration thus looks like:

Call Parking Contacts Example Collapse source

Here, note that we've created the actions parkme and showparking.  For parkme, #72 is dialed.  For showparking, the phone will load the parking built-in phone application.

Next, we need to configure the behavior of a Rapid Dial key to affect the actions.  Configuration for this resembles:

Call Parking BLF Items Example Collapse source

Here, notice that we have defined two behaviors.  First, we define a behavior that acts when our phone is in the connected state.  In that state, when the rapid dial key is pressed, the parkme action is called with the press_function of send_dtmf, which sends in-call DTMF back to Asterisk.

Next, we define a behavior that acts when our phone is in the idle state.  In this state, when the rapid dial key is pressed, the showparking action is called, with the press_function show_app, which loads an application into the foreground.

Thus, when we're on call, we can press the rapid dial key to send DTMF to Asterisk that sends the caller to the parking lot.  And, when we're idle, we can press the same rapid dial key to load the parking application into the foreground, so we can see who's parked.

Blind Transfer

Prior to the 1.4 phone firmware, blind transfers on Sangoma phones could only be affected on unanswered calls by pressing the Transfer hard key, followed by a Rapid Dial key for a contact, or during an in-progress call by pressing the Transfer hard key, followed by dialing the contact and pressing the Transfer soft key or by selecting the contact and pressing the Transfer soft key.  In either case, performing a blind transfer prior to the 1.4 firmware requires use of the Transfer hard key to put the phone in a transfer-capable state.

With the capabilities of Smart BLF, it is possible to perform a blind transfer with the press of a single Rapid Dial key, and it can be done one of two ways.  The first way performs a regular SIP transfer.  In this scenario, let's assume that when our phone is idle, and we press the rapid dial key for a contact, that we call that contact.  And, when our phone is receiving a call, or when our phone is on a call, or when our phone is actually in the transfer state (because someone has pressed the hard transfer key), that pressing that contact's rapid dial key will blind transfer the call that's active/highlighted in the call field to the target.

To begin, let's assume 3-digit extensions.  Diaplan for this might look like:

Blind Transfer Dialplan Example Collapse source

Here, we've defined an extern pattern match on 1XX - all 3-digit dialed patterns beginning with 1 followed by two more digits 0-9.  In the case that it's matched, Asterisk will dial the SIP extension.

To affect this, our Sangoma phone needs a contact that is configured with two actions: one, called 103 to dial the contact normally, and another called blindxfer that performs a transfer function.  The contact configuration thus looks like:

Bind Transfer Contacts Example Collapse source

Here, note that we've created the actions 103 and blindxfer.  For each, only 103 is dialed. 

Next, we need to configure the behavior of a Rapid Dial key to affect the actions.  Configuration for this resembles:

Blind Transfer BLF Items Example Collapse source

Here, notice that we have defined five behaviors.  Because behaviors are processed top-down, we first define a behavior with press_action of 103 and press_function of dial.  This will cause the phone for all phone_states and all target_states (the implied behavior when not explicitly defining them) to call the 103 action.  

Next, we define behaviors for the phone states where we want the blindxfer action to be called.  The states we've chosen are incoming (for when a call rings us), connected (for when we're on a call and not doing anything else), incoming/transfer (for when a call is ringing us and we've pressed the Transfer hard key), and hold/transfer (for when we're on a call and we've pressed the Transfer hard key, which puts the caller on hold).

Thus, when we're idle, and we press the rapid dial key, the phone will dial 103.  And, in four phone states that we've defined, the phone will instead perform a blind transfer of any call that might be ringing or already connected to the phone.

The second method of performing a blind transfer using a single key press involves use of Asterisk's built-in DTMF-based transfer.  To do this, we need to first make sure that features.conf is configured correctly.  It should look something like:

Blind Transfer featues.conf Example Collapse source

Here, we've setup DTMF sequence to invoke blind transfer as #1.

Next, we need to make sure our Dialplan is constructed to include the feature map context like so:

Blind Transfer using features.conf Dialplan Example Collapse source

Here, our sample context testing includes the necessary components, automatically generated by features.conf.  And, our Dial() application includes the t and T flags, which lets the called and calling parties transfer the other caller by dialing the proper DTMF sequence.