Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70

Overview

The built-in applications, and their associated hard and soft keys on the D4X, D50, D6X, & D70 can now be redirected to user defined applications as of firmware version 2_7_1.

The built-in application names below are the actual names passed into the Javascript application's digium.app.foreground event as the params.eventData.app string. The built-in applications which can be redirected are as follows...

phonemenu

Shows all phone settting screens. Mapped to the check key (dpad.select) and Menu key (fn.menu D70 only). This application is not normally redirected, but it can be in cases where minimal phone setting access is desired, or in cases where phone setting access is completely disabled, and a simple disabled screen is shown.

contacts

Shows contents of the contact file /nvdata/contact_lists/serialized_contacts.xml. Mapped to soft key 2 when conferencing or transferring a call, and the Contacts key (fn.dir D70 only).

status

Shows status screen when <appconfig id=”status”> has the <full_application/> tag, else status is simply toggled between active and DND. Mapped to soft key 3 on the account info
screen, and the status key (fn.status D70 only).

Please note that if the status app is redirected that the <auto_start/> tag should NOT be included in the <appconfig> tag for the status app, otherwise the built-in status app will
be automatically loaded and consume memory, even though it will never be executed. All that is required to ensure the redirected status app be executed (instead of the status being toggled), is: <appconfig id=”status”><full_application/></appconfig>

voicemail

Shows the voicemail application when the account's visual_voicemail=”1” element is set, else dials the number in the accounts voicemail=”” element to access voicemail. Mapped to the message key (fn.msg on all phone models).

Other applications

While forward, parking, and queues are also built-in applications, they are not hard mapped to any keys, and if they are not listed in any key maps or <appconfig> tags, they will not be listed or executed.

How to Redirect

Any single application can be redirected to a replacement app, or all of them can be redirected to a singe user application if so desired. To enable redirection a new
<appredirect> tag group has been added to the configuration.

The id=”” element in the <redirect> tag below is the application name normally executed (and the name passed into the application as the params.evenData.app string). The app=”” element is the name of the actual app executed. The actual app executed must also have a corresponding <appconfig> tag in the configuration, as it normally would, so that it gets loaded and can be executed. In the case below, the account's visual_voicemail=”1” element would also need to be set so that the voicemail app is executed, instead of a number being dialed.

<appconfig id="my_voicemail">
    <url url="http://xx.xx.xx.xx:80/my_voicemail.zip" md5="0123456789abcdef0123456789abcdef" />
    <settings app_settings_here=””... />
    <auto_start />
</appconfig>
<appredirect>
    <redirect id=”voicemail” app=”my_voicemail”/>
</appredirect>

Redirection Phone Config Example

The following configuration excerpt shows how all the internal apps can be redirected to a single user application. It also has the applications mapped to soft keys. In this case however the application's foreground function must detect which application is being executed by comparing the params.eventData.app string.

<config>
    <accounts>
    <!-- voicemail hard key is remapped to user app here using visual_voicemail="1", along with the appredirect tag below -->
        <account index="0" status="1" register="1" account_id="105" username="105" authname="105" password="1234567890" passcode="1234567890" line_label="105" caller_id="105" dial_plan="[0-8]xxxxx|911|9411|9611|9011xxx.T3|91xxxxxxxxxx|9[2-9]xxxxxx|*xx.T3|[0-8]xx.T3" visual_voicemail="1" voicemail="" outbound_proxy="" outbound_port="" conflict="replace">
            <host_primary server="xx.xx.xx.xx" port="5060" transport="udp" reregister="300" retry="25" num_retries="5" />
        </account>
    </accounts>
    <keymap>
    <!-- idle softkeys allow multiple apps to be replaced by one user app using the appredirect tag below. If the label1= string has an underscore as the first char, the phone will attempt to use the string as an internal token for international translations, else it will use the string as is on the soft key. The <arg> tag is the desired application, when redirected, will be passed to params.eventDate.app -->
        <state id="idle" conflict="replace">
            <softkeys>
                <key id="0" action="missed_or_call_log" />
                <key id="1" action="show_application" label1="_CONTACTS">
                    <arg>my_contacts</arg>
                </key>
                <key id="2" action="show_application" label1="_STATUS">
                    <arg>my_status</arg>
                </key>
                <key id="3" action="info" />
                <key id="4" action="show_application" label1="_PARKED_CALLS">
                    <arg>my_parking</arg>
                </key>
                <key id="5" action="show_application" label1="_QUEUES">
                    <arg>my_queues</arg>
                </key>
                <key id="6" action="show_application" label1="_FORWARD">
                    <arg>my_forward</arg>
                </key>
                <key id="7" action="menu" />
            </softkeys>
        </state>
        <state id="hold" conflict="replace">
            <softkeys>
                <key id="0" action="resume" />
                <key id="1" action="none" />
                <key id="2" action="end_call" />
            </softkeys>
        </state>
        <state id="incoming" conflict="replace">
            <softkeys>
                <key id="0" action="accept_call" />
                <key id="1" action="reject_call" />
                <key id="2" action="transfer_call" />
            </softkeys>
        </state>
        <state id="connected" conflict="replace">
            <softkeys>
                <key id="0" action="conference" />
                <key id="1" action="none" />
                <key id="2" action="end_call" />
            </softkeys>
        </state>
        <state id="dial" conflict="replace">
            <softkeys>
                <key id="0" action="toggle_url_number" />
                <key id="1" action="none" />
                <key id="2" action="cancel_call" />
            </softkeys>
        </state>
        <state id="calling" conflict="replace">
            <softkeys>
                <key id="0" action="none" />
                <key id="1" action="none" />
                <key id="2" action="end_call" />
                </softkeys>
        </state>
    </keymap>
    <!-- status app needs full_application for the status hardkey redirect to be sent to an app, but do NOT auto_start, as the actual app will be the one auto_started -->
    <appconfig id="status">
        <full_application />
    </appconfig>
    <appconfig id="my_apps">
        <url url="http://xx.xx.xx.xx:80/my_apps.zip" md5="0123456789abcdef0123456789abcdef" />
        <settings my_app_settings_here="stuff" user="105" pass="1234567890" />
        <auto_start />
    </appconfig>
    <!-- an inconvenience - if one user app runs multiple apps only the one actual app can be listed on the appscreen. Since the my_apps is loaded from the config, appscreen will automatically show it on the screen -->
    <appconfig id="appscreen">
        <application id="call_log" />
        <auto_start/>
    </appconfig>
    <!-- apps that get redirected, id = desired app name, app = actual app executed internal hard key app names = contacts, status, voicemail, and phonemenu. Note, bootconfig and appscreen are not allowed to be redirected. -->
    <appredirect>
        <!-- redirected hard key apps -->
        <redirect id="contacts" app="my_apps" />
        <redirect id="status" app="my_apps" />
        <redirect id="voicemail" app="my_apps" />
        <!-- redirected soft key apps -->
        <redirect id="my_contacts" app="my_apps" />
        <redirect id="my_status" app="my_apps" />
        <redirect id="my_forward" app="my_apps" />
        <redirect id="my_parking" app="my_apps" />
        <redirect id="my_queues" app="my_apps" />
    </appredirect>
</config>

Redirection App Config Example

The following is an example of a my_apps.js Javascript app, and how to handle the app name passed in from the app redirect.

var app = require('app');
app.init();
  
var screen = require('screen');
var util = require('util');
var genericConfirm = require('genericConfirm');
var genericForm = require('genericForm');
var genericMenu = require('genericMenu');
  
var my_apps = {};
  
// supporting code here....
  
// desired app is now passed to digium.app.foreground event
// as params.evenData.app, switch on the string to decide
// which app to atually show. Digium phone hard key apps =
// contacts, status, voicemail, and phonemenu.
  
mmy_apps.show = function(params) {
    var eventData = params.eventData;
  
    switch(eventData.app) {
    case "contacts":
    case "my_contacts":
        this.current_screen="contact_screen";
        break;
    case "status":
    case "my_status":
        this.current_screen="status_screen";
        break;
    case "voicemail":
        this.current_screen="voicemail_screen";
        break;
    case "my_forward":
        this.current_screen="forward_screen";
        break;
    case "my_parking":
        this.current_screen="parking_screen";
        break;
    case "my_queues":
        this.current_screen="queues_screen";
        break;
    default:
        this.current_screen="menu_screen";
        break;
    }
  
    // display the selected app screen
    this.show_screen();
};
  
my_apps.hide = function() {
// clean up any variables for backgrounding here...
};
  
my_apps.init = function() {
    var config = app.getConfig().settings;
    this.config = config;
    this.current_screen = "menu_screen";
  
    digium.app.exitAfterBackground = false;
  
    // params.evenData.app now has the desired app to show
    digium.event.observe({
        'eventName' : 'digium.app.foreground',
        'callback' : this.show.bind(this)
    });
  
    digium.event.observe({
        'eventName' : 'digium.app.background',
        'callback' : this.hide.bind(this)
    });
};
  
my_apps.init();

Phones

D-Phone Javascript Application Redirection