Custom Phone Applications with Asterisk

Sangoma D-Series phones support loading and running user-created custom JavaScript applications. Fore more information about creating these applications, and the endless possibilities therein, please see the Getting Started page on our Digium Phone API Center website.

Custom applications may only be loaded onto phones running firmware version 1.3+. Phone firmware 1.3 is now generally available, For information about setting up your phone for application development, see the Getting Started page.

Custom Applications and DPMA

Custom applications are always defined with an application type of "custom" and are loaded onto phones using the phone type option application, just as a queue or status application would be loaded onto a phone. This application type is supported by DPMA, beginning with DPMA version 1.3.0.

Example

In this example:

• An application named Jason-Fancy-App is declared, it's of the Custom application type

• The internal name of the application is jasonapp

• The filename of the application, as retrieved from the file_url_prefix is jasonsillyapp.zip

• The application will start when the phone boots

• Custom keypairs for 'user=1234', 'permission=lots', 'string=hello world' are passed in

Example of custom application configuration

[Jason-Fancy-App]
type=application
application=custom
name=jasonapp
filename=jasonsillyapp.zip
autostart=yes
user=1234
permission=lots
string=hello world

Accessing custom key value pairs using a custom application

A custom application can access the custom key value pairs using app.getConfig().

When using the example configuration above, here is an example of accessing the custom key value pairs with a custom application:

Example of custom application accessing custom key value pairs

// Get all settings
var app_config = app.getConfig();
 
// Assign values of the custom keys to variables
var myuser = app_config['settings']['user'];
var mypermission = app_config['settings']['permission'];
var mystring = app_config['settings']['string'];

Interacting with Asterisk

In order to register methods with Asterisk, the DPMA provides an Action DPMAMessageRegister 
It's registered via Manager like:

Action: DPMAMessageRegister
Method: digium.qwelltest.okay

When a method has been registered, phone applications can use the pbx.request function to call that method and pass parameters into Asterisk. Here's an example:

pbx.request({
        'method' : 'digium.qwelltest.okay',
        'parameters' : {
            'account_id' : app.getAccountId()
        },
        'onSuccess' : function (p) {
            util.debug(JSON.stringify(p));
            win[0][1].label = p.result.foo.bar;
 
            var now = new Date();
 
            setTimeout(function() {request(win, visiblePredicate);}, 5001 - now.getMilliseconds());
        }.bind(this)
    });

In this example, we pass the method digium.qwelltest.okay with the parameter account_id and a fictitious value derived from app.getAccountID()

Asterisk will then receive the method from the pbx.request function and issue an Event like:

Event: DPMAMessage
RequestID: aeprox1636617668
Method: digium.qwelltest.okay
Format: JSON
Parameters: {"account_id":"abcdefg"}

To respond to this event, Message Responses can be sent back using the DPMAMessageResponse AMI Action like:

Action: DPMAMessageResponse
Response: {"foo":{"bar":"baz"}}
Format: JSON
RequestID: aeprox1636617668

Push Messages, which don't initiate as a response to an Event received from the phone application, can be sent into the phone using the DPMAMessageSend AMI Action like:

Action: DPMAMessageSend
Method: digium.qwelltest.bacon
Message: {"type" : "Hi there!" }
PhoneName: 6239

where PhoneName represents the phone context from res_digium_phone.conf.

When a notification is pushed from Asterisk into the phone, the notification can be read from the phone's application by using the digium.event.observe handler, such as:

digium.event.observe({
    'eventName' : 'digium.qwelltest.bacon',
    'callback' : function (params) {
        util.debug(JSON.stringify(params));
    }
});

Custom Applications and XML Provisioning

Custom applications are defined in the XML structure in an appconfig element. The phone will retrieve the application as directed by the element and load the settings as directed by the element.

Appconfig Element

 Appconfig Element Example

url: Child Element of <appconfig>

settings: Child Element of <appconfig>

auto_start: Child Element of <appconfig>

If the auto_start element is present, the application will load when the phone is booted. If the element is not present, the application will only load when the user manually starts the application through the applications menu.

Custom Applications and FreePBX

Custom applications can be loaded onto Sangoma phones within FreePBX using the "Custom" applications sub-tab of the "Applications" tab of the Sangoma phones FreePBX configuration utility.  For details on this, please see this wiki page.

Frequently Asked Questions (FAQ)

Q: Is there a developer walkthrough video for the Phone API?

A: Yes.  Please see - http://www.youtube.com/watch?v=41OCM3zwoiM

Q: Is there a place where I can list my app or search for others' apps?

A: Yes.  Apps can be listed on the Asterisk Exchange at http://www.asteriskexchange.com/listings/category/82

Q: Are any tools or examples available on Github?

A: Yes.  Tools and example may be found on Git hub at https://github.com/digium/digium-phone-apps