Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
This file describes the application and provides specific settings used by the app engine. Every application must include an app.json file in its directory. The app.json file is a single file written in JSON notation. You must use double quotes to identify object keys and values in your app.json file.
Required: The app.json file must contain the following information:
name
The name of the app. This is how the app engine refers to the app. name must be
64 chars or less, and the first character must be a letter or a digit. The rest
can be letters, digits, underscore, period, comma. We recommend all lowercase,
but that's not required.
jsFiles
The JavaScript file to load when the app starts. You may include multiple
files, they are loaded and run in left-to-right order. It is not necessary to
list language files here.
type
The type of app, which is always foreground.
Also, this information can be included as appropriate:
displayName
This is how the app name is displayed in various places (e.g., the Applications
screen). If this is not included, name is used.
iconFile
Default icon file basename. The phone looks for D70.hello_world_icon.png first,
on a D70, and likewise for other models. The icon can be dynamically set by the
app instead (or in addition), but this file will be used when the app is not
running.
hasIdle
Indicate true if the app supports an idle screen
display mode. If you don't include this, or you indicate false,
the app cannot use the idle screen. The digium.app.idleWindow object is created
based on this.
hidden
Indicate true if the app should not appear in the
Applications screen. If you don't include this, or you indicate false,
the app does appear in the Applications Screen.
{"name": "helloworld", "jsFiles": ["file1.js"], "type": "foreground", "displayName": "Hello, world!", "iconFile" : "hello_world_icon.png", "hidden" : false, "hasIdle": true } |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
The Sangoma Phone API lets you build custom apps for your phones using the popular programming language JavaScript. And the Sangoma Phone App Engine interprets and executes this JavaScript code.
Control the Display on the Phone
The user interface and interaction tools let you control the display on the phone and collect data from the user with menus and forms.
Integrate with Internet Services
You can build AJAX functionality into custom apps to allow your phones to retrieve data from or submit data to the internet (just like programming for a website).
Integrate with Your Business Applications
You can build custom apps that interact with your business applications to improve customer service and productivity.
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
The D-Series Phone API is a JavaScript toolset used to build custom apps.
At its most basic, a custom app is a zip file that contains an app.json file and a JavaScript file.
An app is packaged into a zip file. The zip contains the app.json file, JavaScript file, and additional data (icons, language files, etc.).
A Sangoma Phone uses the zip file to install the app.
Each app requires a JSON file named app.json. The JSON file describes to the Sangoma Phone App Engine what the app is and what its settings are. See the article app.json for details.
The following are the principal phone API modules comprising the toolset:
· Core - Basic building blocks of any Sangoma Phone app. Used for functional programming.
· Classes - Core classes available to every app. Used for functional programming.
· Extended - Libraries to add additional functional methods to a Sangoma Phone app.
· Extended Classes - Additional libraries to add more functional class constructors.
· UI Core (window) - Automatically defined object that enables app display for every app at runtime.
· UI Classes (Widgets) - Basic graphical building blocks (class constructors).
· UI Extended - Additional tools for building user interaction into your app.
· UI Extended Classes - Additional UI class constructors for creating more than basic UI elements.
Links to these modules and their libraries are in the sidebar. See the Getting Started page and the other Guides for general instructions, and the Phone API Demos for annotated sample programs to give you custom app examples.
The phone app programming model is single-threaded, event-driven. Avoid long-running processing loops because they limit the responsiveness of apps, and after a few seconds, they will cause your app to be killed.
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
These core object constructors are available to all apps without requiring any libraries. Objects relating to UI elements are documented in UI Classes (Widgets).
|
Name |
Description |
|
Makes HTTP and similar requests from JavaScript. This object is similar to the standard browser XMLHttpRequest object. |
|
|
Similar to the standard DOMParser. Used to parse an XML string into a DOM document that can be traversed and manipulated in the usual ways (getElementById(), appendChild(), etc). |
|
|
Similar to standard XMLSerializer. Used to convert a DOM document into a valid XML string. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Similar to the standard DOMParser. Used to parse an XML string into a DOM document that can be traversed and manipulated in the usual ways (getElementById(), appendChild(), etc).
Create a new DOMParser object.
var parser = new DOMParser(); |
|
None |
|
Name |
Description |
|
Parse a string into a standard DOM Document. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Parse a string into a standard DOM Document.
Basic Example:
var parser = new DOMParser(); var document = parser.parseFromString('<config><test attr="value" /></config>'); |
Parameters
|
Name |
Required |
Type |
Default |
Description |
|
xml |
Yes |
string |
String containing valid XML. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Makes HTTP and similar requests from JavaScript. This object is similar to the standard browser XMLHttpRequest object.
new NetRequest()
Constructs a new NetRequest Object.
var request = new NetRequest(); |
|
None |
|
Name |
Description |
|
Returns the header field value from the response of which the field name matches header, unless the field name is Set-Cookie or Set-Cookie2. Returns null if either the response has not yet been received or the header doesn't exist in the response. |
|
|
Sets the request method and request URL. This method differs from the standard XMLHttpRequest's open() method by only accepting two parameters (all requests are asynchronous, and the user/password are entered in the request object's user and password properties.) |
|
|
Initiates the request. The optional argument provides the request entity body. The argument is ignored if request method is GET or HEAD. |
|
|
Appends a header to the list of author request headers, or if header is already in the list of author request headers, combines its value with value. |
|
|
Sets a timeout, after which the request will be aborted with a 500 status. |
|
Name |
Description |
|
oncomplete |
Called at the end of the response. This is redundant to onreadystatechange with readyState=4. Basic Example: request.oncomplete = function() { util.debug('request is done'); } |
|
onreadystatechange |
Event handler for readyState. Basic Example: request.onreadystatechange = function () {util.debug(request.readyState); util.debug(request.status); } |
|
password |
Password used in the request, or null if there is no password. Basic Example: request.password = 'secret'; |
|
readyState |
Returns the current state. Basic Example: var currentState = request.readyState; // returns integer such as 200 |
|
responseFile |
If present, along with responseLoc, the response body is placed in the file rather than in responseText. Basic Example: request.responseFile = "text.txt"; |
|
responseLoc |
If present, along with responseFile, the response body is placed in the file rather than in responseText. Basic Example: request.responseLoc = "tmp"; |
|
responseText |
Returns the text response entity body. Basic Example: var response = request.responseText; |
|
status |
Returns the HTTP status code; such as 200 (success), 500 (internal server error), 404 (file not found), etc.. Basic Example: var statusCode = request.status; |
|
user |
Returns the name of the user in the request, or null if there is no username. Sets the user for the request. Basic Example: request.user = "username"; //set username for request request.user; //"username" |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Returns the header field value from the response of which the field name matches header, unless the field name is Set-Cookie or Set-Cookie2. Returns null if either the response has not yet been received or the header doesn't exist in the response.
Basic Example:
var headerValue = request.getResponseHeader(header); |
|
Name |
Required |
Type |
Default |
Description |
|
header |
Yes |
string |
Name of the header as expected from the response. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Sets the request method and request URL. This method differs from the standard XMLHttpRequest's open() method by only accepting two parameters (all requests are asynchronous, and the user/password are entered in the request object's user and password properties.)
Basic Example:
request.open(method, url); |
|
Name |
Required |
Type |
Default |
Description |
|
url |
Yes |
string |
URL to send the request to. |
|
|
method |
Yes |
string |
HTTP method to use; such as GET or POST. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Initiates the request. The optional argument provides the request entity body. The argument is ignored if request method is GET or HEAD.
Basic Example:
request.send(); |
|
None |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Appends a header to the list of author request headers, or if header is already in the list of author request headers, combines its value with value.
Basic Example:
request.setRequestHeader(header, value); |
|
Name |
Required |
Type |
Default |
Description |
|
header |
Yes |
string |
Name of the header to set. |
|
|
value |
Yes |
string |
The value to set for the header |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Sets a timeout, after which the request will be aborted with a 500 status.
Basic Example:
request.setTimeout(milliseconds). |
|
Name |
Required |
Type |
Default |
Description |
|
milliseconds |
Yes |
integer |
Integer representing time greater than zero in milliseconds. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Similar to standard XMLSerializer. Used to convert a DOM document into a valid XML string.
Creates a new XMLSerializer object
var serializer = new XMLSerializer(); |
|
None |
|
Name |
Description |
|
serializeToString |
Serialize a DOM document object to an XML string. Basic Example: var serializer = new XMLSerializer(); var xml = serializer.serializeToString(document); Name Required Type Default Description document Yes DOM document object. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
These core functions are available to all apps without requiring any libraries. They provide functionality to interact with the application environment, invoke phone functions, etc.
|
Name |
Description |
|
Used to include and evaluate other scripts. Anything exported by a required script is then made available using require. |
|
|
Object used to provide functions, variables, and properties for use by another script. Use require in another script to obtain the exports in the current script. Exports will not work if you set exports = to an object (e.g., {"key" : "value" }). You must set properties of the exports object as can be seen in the example. |
|
|
Handles application launching/hiding, system event listeners, phone functions, and file I/O. |
|
|
Contains methods and properties about the phone's applications. |
|
|
Used to create applications that register event listeners by calling digium.event.observe() and specifying one of the event names as the eventName parameter. Also used to trigger an event with digium.event.fire() and to remove callbacks for an event with digium.event.stopObserving(). |
|
|
Call handling. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Contains methods and properties about the phone's applications.
|
Name |
Description |
|
Returns the current Image object for the specified app. |
|
|
Returns an object with information about the specified app, as defined in its app.json file. |
|
|
Returns an array containing the names of apps that the system knows about. The names are defined in app.json. |
|
Name |
Description |
|
digium.app.config.xml |
A string containing the XML representing the app's configuration (appconfig) settings from the phone's master configuration xml. These are limited to app-specific settings distributed from the phone's configuration server. Basic Example: digium.app.config.xml; //returns '<appconfig id="test.my_app"><settings /></appconfig>' |
|
digium.app.exitAfterBackground |
An app will start up each time it is placed in the foreground and shut down each time it is placed in the background. This Boolean property sets whether or not the app shuts down (exits) when it goes into the background. The default setting is true; i.e., the app shuts down when it goes into the background. Change the setting to false to make your app run persistently. Basic Example: digium.app.exitAfterBackground = false; //now it won't shut down when backgrounded |
|
digium.app.iconFile |
Get or set the filename of the icon image used for this application. The icon is used in other apps such as the app manager screen and is contained in the app's directory. Basic Example: // Let's assume your app.json file inits your app with the iconFile "myapp_no_msgs.png"; var currentIcon = digium.app.iconFile; // returns "my_app_no_msgs.png"; // Your app then may be running in the background and when it gets a message you want to // update the iconFile to provide an indicator to the Apps screen. // this could be set in some sort of call back function digium.app.iconFile = "my_app_msgs_waiting.png"; // now if you go to the Apps screen (press the Apps button on the D70) you will see the icon has changed. currentIcon = digium.app.iconFile; // returns "my_app_msgs_waiting.png"; If your app is initialized for the first time, digium.app.iconFile is set to the iconFile from the app.json file. If setting the iconFile, the {MODEL}.iconFile naming convention should be used for whichever iconFile you are setting. |
|
digium.app.idleWindowShown |
Boolean flag reflecting whether the the app's idle screen window is currently displayed. |
|
digium.app.inForeground |
Boolean value indicating whether this app is in the foreground. |
|
Get the name of the app as specified in the app's app.json file. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Returns the current Image object for the specified app.
|
Name |
Required |
Type |
Default |
Description |
|
app_name |
Yes |
string |
Name of the app to act on as defined in its app.json file. |
digium.app.getIcon
digium.app.getIcon('contacts'); |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Returns an object with information about the specified app, as defined in its app.json file.
Basic Example:
var appInfo = digium.app.getInfo(app_name); |
|
Name |
Required |
Type |
Default |
Description |
|
app_name |
Yes |
string |
Name of the app to act on as defined in its app.json file. |
digium.app.getInfo with the return object
digium.app.getInfo('contacts');/* returns: { 'name' : 'contacts', 'displayName' : 'Contacts', 'iconFile' : 'app_contacts.png', 'running' : true 'hidden' : true } */ |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Puts the app in the background, returning the screen to its regular state
(e.g., idle).
Basic Example:
digium.background(); |
When an app is put in the background, unless the digium.app.exitAfterBackground property is set to false, the app will shutdown.
|
None |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Handles application launching/hiding, system event listeners, phone functions, and file I/O.
|
Name |
Description |
|
Puts the app in the background, returning the screen to its regular state (e.g., idle). |
|
|
Brings an app into the foreground. If this is called without any arguments, it brings the current app to the foreground. |
|
|
Reads the contents of a file as utf-8 and returns the contents as a string. The filename is relative to the location that is specified (this is a flat directory). |
|
|
Resets the timeout that causes the phone to hide apps when there's no keyboard input for a while. This keeps the app alive and should be called periodicallly to prevent the app from being timed out. |
|
|
Indicates to the app to reboot itself. |
|
|
This function can be used to change the state of one of the phone's LED lights. |
|
|
Writes the string into a file. The filename is relative to the location that is specified (this is a flat directory). |
|
Name |
Description |
|
digium.phoneModel |
This property is set to a string that represents the model of the phone (D40, D45, D50, D60, D62, D65, D70). |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Used to create applications that register event listeners by calling digium.event.observe() and specifying one of the event names as the eventName parameter. Also used to trigger an event with digium.event.fire() and to remove callbacks for an event with digium.event.stopObserving().
|
Name |
Description |
|
Fire an event of the given eventName and pass your eventData onto any callback that may be observing the event. Note: the list of Digium eventNames cannot be fired except by the system. |
|
|
Set a callback function to be fired when the request eventName fires. |
|
|
Used to remove callbacks for an event. If callback is not passed in (which is a reference to the original observed callback), then all observed events are removed for the specified eventName. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Fire an event of the given eventName and pass your eventData onto any callback that may be observing the event. Note: the list of Digium eventNames cannot be fired except by the system.
Basic Example:
digium.event.fire(parameters); |
|
Name |
Required |
Type |
Default |
Description |
|
eventName |
Yes |
string |
String that identifies the event type. Event type can either be from this list if you are using digium.event.observe, or from your own list if you're using digium.event.fire to fire your own event. |
|
|
eventData |
Yes |
object |
Object passed to any callbacks listening for this event. eventData can contain a 'callback' property that will be executed when an event named eventName.response (for example, contacts.forwardVM.response) is sent with the same messageId. |
|
|
messageId |
No |
object |
Unique ID for the message. If messageId is not specified one will be generated automatically. |
A full list of system eventNames can be found here
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Set a callback function to be fired when the request eventName fires.
Basic Example:
digium.event.observe(parameters); |
|
Name |
Required |
Type |
Default |
Description |
|
eventName |
Yes |
string |
String that identifies the event type. Event type can either be from this list if you are using digium.event.observe, or from your own list if you're using digium.event.fire to fire your own event. |
|
|
callback |
No |
object |
Called when an event arrives and contains an Object with the following: · callHandle - the string identifying the call. This is only present when the notification is attached to an incoming call. · method - the SIP method type used to deliver the message. INFO, INVITE, or MESSAGE. · eventName - the string identifying the pushed event type · eventData - data associated with the message (from the x-event-data header or the body of an INFO or MESSAGE). If data can be parsed as JSON, the parsed object is used; otherwise, this field contains a string. · messageId - ID string for the event. |
A full list of system eventNames can be found here.
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Used to remove callbacks for an event. If callback is not passed in (which is a reference to the original observed callback), then all observed events are removed for the specified eventName.
Basic Example:
digium.event.stopObserving(parameters); |
|
Name |
Required |
Type |
Default |
Description |
|
eventName |
Yes |
string |
String that identifies the event type. Event type can either be from this list if you are using digium.event.observe, or from your own list if you're using digium.event.fire to fire your own event. |
|
|
callback |
No |
object |
Callback (OPTIONAL) to remove from the event listener. If this parameter is undefined, all callbacks registered to eventNamewill be removed. |
A full list of system eventNames can be found here.
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
App Events
|
digium.app.background |
Called when an application is about to be put in the background. |
|
digium.app.exit |
Called when an application is about to shut down. |
|
digium.app.foreground |
Called when the application is put into the foreground. The application name and any arguments from appconfig will be passed as arguments to the callback. |
|
digium.app.idle_screen_hide |
Called with no arguments when the app idlescreen window is hidden in the GUI. |
|
digium.app.idle_screen_show |
Called with no arguments when the app idlescreen window is displayed by the phone GUI. |
|
digium.app.start |
Called when the app first starts up. |
Phone Events
|
digium.phone.contact_presence |
Called whenever a subscribed user updates his/her presence information. |
|
digium.phone.contact_update |
Called when new contact information is received from the server. The app then rebuilds any data structures based on the result of digium.contacts.getList(). |
|
digium.phone.icon_change |
Called whenever an application changes its icon. Callback will be passed the name of the application in the eventData parameter. |
|
digium.phone.app_install |
Called when an application is installed or reinstalled. Callback will be passed the name of the application in the eventData parameter. |
|
digium.phone.incoming_call |
Called to notify of an incoming phone call. The eventData properties are the same as those given to a handler in the digium.phone api. |
|
digium.phone.mwi |
Called when a Message Waiting Indicator arrives. For example, a voicemail notification. |
|
digium.phone.new_config |
Called when the phone's configuration file has changed. |
|
digium.phone.outgoing_call |
Called to notify of an outgoing phone call. The eventData properties are the same as those given to a handler in the digium.phone api. |
|
digium.phone.play_status |
Called about every second while an audio file is playing, to give status. Also called when playback stops. |
|
digium.phone.server_change |
Called to provide failover status for accounts. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Brings an app into the foreground. If this is called without any arguments, it brings the current app to the foreground.
Basic Example:
|
|
Note: The app needs to be running for this to do anything.
|
app_name |
No |
string |
|
Name of the app to act on as defined in its app.json file. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Answers an incoming call.
Basic Example:
digium.phone.answer(parameters); |
If a function is passed in the handler parameter, that function is called with a call status object to notify of state changes to the phone call.
|
Name |
Required |
Type |
Default |
Description |
|
callHandle |
Yes |
string |
Identifier of the call to act on. A call handle can be obtained by observing call events. Information such as this will be passed into the event object. |
|
|
handler |
No |
function |
Handler to register for the call. Executed whenever the call changes state. |
digium.phone.answer with util.debug to print call state
digium.phone.answer({ 'callHandle' : callHandleVar, 'handler' : function (obj) { util.debug(obj.state); //prints the state of the call } }); |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Initiates a call. This function returns a call handle, which is a string identifying the call. It can be used in various other methods such as digium.phone.hangup.
Basic Example:
digium.phone.dial(parameters); |
If a function is passed in the handler parameter, that function is called with a call status object to notify of state changes to the phone call.
|
Name |
Required |
Type |
Default |
Description |
|
number |
Yes |
string |
Number to dial. |
|
|
url |
No |
string |
SIP URL to call (e.g., [email protected]). This can be used instead of a number. Only one of the two are required. |
|
|
headers |
No |
object |
Object with header values to set in the call's INVITE. |
|
|
accountSlot |
No |
integer |
ID for the account. |
|
|
handler |
No |
function |
Handler to register for the call. Executed whenever the call changes state. |
digium.phone.dial with util.debug for state of the call
digium.phone.dial({'number' : 100, 'handler' : function (obj) {util.debug(obj.state); //prints the 'state' of the call } }); |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Call handling.
|
Name |
Description |
|
Answers an incoming call. |
|
|
Initiates a call. This function returns a call handle, which is a string identifying the call. It can be used in various other methods such as digium.phone.hangup(). |
|
|
Hangs up on an ongoing call. |
|
|
Attaches handlers to ongoing-call status changes. Useful if you were unable to attach a handler when the call was created. |
|
|
Ignores (rejects) an incoming call before it is answered. |
|
|
Sends DTMF tones in an ongoing call. |
|
|
Transfers an active call to another extension. This is a blind transfer, meaning the transferor does not talk to the transferee. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Hangs up on an ongoing call.
Basic Example:
digium.phone.hangup(parameters); |
If a function is passed in the handler parameter, that function is called with a call status object to notify of state changes to the phone call.
|
Name |
Required |
Type |
Default |
Description |
|
callHandle |
Yes |
string |
Identifier of the call to act on. A call handle can be obtained by observing call events. Information such as this will be passed into the event object. |
|
|
handler |
No |
function |
Handler to register for the call. Executed whenever the call changes state. |
digium.phone.hangup with until.debug to print call state
digium.phone.hangup({'callHandle' : callHandleVar, 'handler' : function (obj) {util.debug(obj.callHandle); } }); |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Attaches handlers to ongoing-call status changes. Useful if you were unable to attach a handler when the call was created.
The function passed in the handler parameter is called with a call status object to notify of state changes to the phone call.
|
Name |
Required |
Type |
Default |
Description |
|
handler |
Yes |
function |
Handler to register for the call. Executed whenever the call changes state. |
|
|
callHandle |
Yes |
string |
Identifier of the call to act on. A call handle can be obtained by observing call events. Information such as this will be passed into the event object. |
digium.phone.observeCallEvents with util.debug to print call state
digium.phone.observeCallEvents({'callHandle' : callHandleVar, 'handler' : function (obj) {util.debug(obj.state); } }); |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Ignores (rejects) an incoming call before it is answered.
Basic Example:
digium.ohone.reject(parameters); |
If a function is passed in the handler parameter, that function is called with a call status object to notify of state changes to the phone call.
|
Name |
Required |
Type |
Default |
Description |
|
callHandle |
Yes |
string |
Identifier of the call to act on. A call handle can be obtained by observing call events. Information such as this will be passed into the event object. |
|
|
handler |
No |
function |
Handler to register for the call. Executed whenever the call changes state. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Sends DTMF tones in an ongoing call.
Basic Example:
digium.phone.sendDTMF(parameters); |
Parameters
|
Name |
Required |
Type |
Default |
Description |
|
digit |
Yes |
string |
Digit 0-9, a letter from A-D, *, or #. |
|
|
duration |
No |
integer |
Length of time in milliseconds to play the tone. |
digium.phone.sendDTMF with a tone to play
digium.phone.sendDTMF({'duration' : 5000, 'digit' : 5 }); |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Transfers an active call to another extension. This is a blind transfer, meaning the transferor does not talk to the transferee.
Basic Example:
digium.phone.transfer(parameters); |
If a function is passed in the handler parameter, that function is called with a call status object to notify of state changes to the phone call.
|
Name |
Required |
Type |
Default |
Description |
|
callHandle |
Yes |
string |
Identifier of the call to act on. A call handle can be obtained by observing call events. Information such as this will be passed into the event object. |
|
|
number |
Yes |
string |
Number to dial. |
|
|
handler |
No |
function |
Handler to register for the call. Executed whenever the call changes state. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
If a handler is passed to call-related actions, that handler is called whenever the state of the call changes.
The handler is called with one argument, a call status object with the following fields:
·
state - SIP state of the call. One of
"CALLING", "INCOMING", "EARLY",
"CONNECTING", "CONFIRMED", "DISCONNECTING",
"DISCONNCTD".
· accountSlot - Identifier for the line the call is coming in on.
· callHandle - Identifier for the call. This will match the call handle returned by digium.phone.dial, for example.
· remoteInfo - SIP url for the remote end of the call.
· remoteContact - SIP contact header for the remote end of the call.
· lastStatus - Most recent SIP status code associated with the call, or "0".
· lastStatusText - Most recent text associated with status code.
·
mediaStatus - Describes the current audio data flow.
One of "none", "active", "local_hold",
"remote_hold", or "error".
· headers - Object mapping SIP headers to their values.
However, if there's an api-level error (e.g., the callHandle is invalid, you are trying to make a call when there's already an active call, etc.), these are available instead:
· state - Has the value "ERROR".
· callHandle - Identifier for the call.
· errorText - Human readable error message (not for display to end users).
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Reads the contents of a file as utf-8 and returns the contents as a string. The filename is relative to the location that is specified (this is a flat directory).
Basic Example:
digium.readFile(location, file); |
Parameters
|
Name |
Required |
Type |
Default |
Description |
|
location |
Yes |
string |
Read-only location parameters: app The app's own directory (so you can read files
included in the app's zip file). Read and write location parameters: nv Non-volatile storage. Data stored here
survives firmware updates. |
|
|
filename |
Yes |
string |
Name of the file to act on. |
Using digium.readFile / digium.writeFile to store settings.
/* Here are two simple functions for working with JSON / and a JavaScript object to store some settings information. We use the readFile and writeFile method to store a string and use the native JSON JavaScript object to parse and stringify it. */ //settings object passed in, let's assume it looks like {"name" : "Bob", "location" : "USA"}function saveSettings (settings) {var settingsString = JSON.stringify(settings); //write our settings in non-volatile storage so they are preserved. digium.writeFile("nv", "my_app_settings.json", settingsString);} function readSettings () { var settings = {};// we wrap loading this file in a try catch because we are not sure if it exists yet or not. // if it doesn't the app engine will throw an exception halting execution. // this is also why we initialize the settings object above. // If this errors we will return the empty object try { var settingsString = digium.readFile("nv", "my_app_settings.json");settings = JSON.parse(settingsString); } catch (error) { util.debug("my_app_settings.json file does not exist yet");} //return our settings object return settings; } |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Resets the timeout that causes the phone to hide apps when there's no keyboard input for a while. This keeps the app alive and should be called periodicallly to prevent the app from being timed out.
Basic Example:
|
|
If an app is idle for 30 seconds without this function being called, the app will go to the background and the screen will return to idle.
|
None |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Indicates to the app to reboot itself.
Basic Example:
|
|
Note: The digium.app.exit event is fired as the app is about to shutdown. If your app is state dependent, you may need to record some information.
|
None |
digium.restart example
|
|
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
This function can be used to change the state of one of the phone's LED lights.
Basic Example:
digium.setLedState(parameters); |
This function can be used to change the state of one of the phone's LED lights. An app can only control LEDs when it is in the foreground; once it goes into the background, the phone gui will return all LEDs to its default behavior. When an app sets its first LED, all other LEDs will be turned off. The app is then responsible for all LED settings until it is backgrounded. When an app returns to the foreground, it will need to set the LEDs to its desired state again (generally in its onforeground handler).
|
Name |
Required |
Type |
Default |
Description |
|
name |
Yes |
string |
The name of the LED to target. Possible values are as follows: · msg (Voicemail Indicator light) · hdst (headset), spkr (speaker), mute · line[n] (line number [1-6] with n being a number. E.G. line1) · blf[n] (blf line [1-10] with n being a number. E.G. blf1) |
|
|
color |
Yes |
string |
Which color to activate for the LED. Possible choices are green, red and amber. |
|
|
state |
Yes |
string |
Which state the LED should be set as. Possible options are: · on · off · fast (fast blink) · slow (slow blink) |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Writes the string into a file. The filename is relative to the location that is specified (this is a flat directory).
digium.writeFile(location, filename, string); |
If the file exists, it is overwritten with the string. If the file does not exist, it is created.
|
Name |
Required |
Type |
Default |
Description |
|
location |
Yes |
string |
Read-only location parameters: app The app's own directory (so you can read files
included in the app's zip file). Read and write location parameters: nv Non-volatile storage. Data stored here
survives firmware updates. |
|
|
filename |
Yes |
string |
Name of the file to act on. |
|
|
string |
Yes |
string |
String to act on. |
Using digium.readFile / digium.writeFile to store settings.
/* Here are two simple functions for working with JSON / and a JavaScript object to store some settings information. We use the readFile and writeFile method to store a string and use the native JSON JavaScript object to parse and stringify it. */ //settings object passed in, let's assume it looks like {"name" : "Bob", "location" : "USA"}function saveSettings (settings) {var settingsString = JSON.stringify(settings); //write our settings in non-volatile storage so they are preserved. digium.writeFile("nv", "my_app_settings.json", settingsString);} function readSettings () { var settings = {};// we wrap loading this file in a try catch because we are not sure if it exists yet or not. // if it doesn't the app engine will throw an exception halting execution. // this is also why we initialize the settings object above. // If this errors we will return the empty object try { var settingsString = digium.readFile("nv", "my_app_settings.json");settings = JSON.parse(settingsString); } catch (error) { util.debug("my_app_settings.json file does not exist yet");} //return our settings object return settings; } |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Object used to provide functions, variables, and properties for use by another script. Use require in another script to obtain the exports in the current script.
Exports will not work if you set exports = to an object (e.g., {"key" : "value" }). You must set properties of the exports object as can be seen in the example.
Require Extended Library:
exports.test = "test"; |
var example2 = {};example2.init = function () {this.status = 'Status set by example2.init()'; }; example2.getStatus = function () {return this.status; }; example2.setStatus = function (param) {this.status = param; }; example2.init(); exports.getStatus = example2.getStatus.bind(example2); exports.setStatus = example2.setStatus.bind(example2); |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Used to include and evaluate other scripts. Anything exported by a required script is then made available using require.
When require is called, the app engine first checks for the required script in the current directory. If a script with the specified name is not found, it will check the shared lib directory (which contains most predefined modules such as app, util, screen, etc.).
The first time a script is required in an app, it is evaluated and then the exports are returned. If that script is required somewhere else in the same app, a reference to the object created from the first require is returned rather than evaluating the script again.
The following example code includes the util javascript module, which makes all exported util methods then available, including util.isDef, util.forceArray, etc.
var app = require('util');var foo = util.isDef(bar); //foo = false exampleArray = util.forceArray('test'); //exampleArray = ['test'] |
Note: Required JavaScript files are referenced by their filename without the .js extension.
The same script can be required from multiple places in an application, and the file is evaluated the first time. For example, if your app is written in four JavaScript files, you can require a specific one of them in all of them. This allows different parts of an application to share data and methods.
As an example, see the following app, which is split into three scripts: example1.js, example2.js, and example3.js. The following is its app.json file:
{"name": "test", "jsFiles": ["example1.js"], "type": "foreground", } |
1. When the app is started, example1.js requires both example2.js and example3.js (and example3.js, in turn, also references example2.js). When example2.js is evaluated, its init() function assigns a value to the 'status' property of 'Status set by example2.init()'
2. This value is saved to the variable 'foo' in example1.js
3. example2.setStatus() is used to change the value of example2.status to 'Status reset by example1.js'
4. When the 'bar' variable is set to the result of the example3.getStatus() function, you can see that the 'example2' object referenced in both example1.js and example3.js is actually the same object.
var example2 = require('example2');var example3 = require('example3');var foo = example2.getStatus(); //foo = 'Status set by example2.init()' example2.setStatus('Status reset by example1.js');var bar = example3.getStatus(); //bar = 'Status reset by example1.js' |
var example2 = {};example2.init = function () {this.status = 'Status set by example2.init()'; }; example2.getStatus = function () {return this.status; }; example2.setStatus = function (param) {this.status = param; }; example2.init(); exports.getStatus = example2.getStatus.bind(example2); exports.setStatus = example2.setStatus.bind(example2); |
var example2 = require('example2');var example3 = {};example3.getStatus = function () {return example2.getStatus(); }; exports.getStatus = example3.getStatus.bind(example3); |
Parameters
|
Name |
Required |
Type |
Default |
Description |
|
JavaScript module |
Yes |
JavaScript module to include. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Returns an array containing the names of apps that the system knows about. The names are defined in app.json.
Basic Example:
digium.app.getList(); |
|
None |
digium.app.getList example
var appList = digium.app.getList(); // Example output util.debug(JSON.stringify(appList)); /* outputs something that looks like the following ["appscreen","bootconfig","contacts","parking","phonemenu","queues","status", "techsupport","voicemail","myname.test_app"] */ |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Apps can include these libraries to access additional functionality. Unlike the core functions, they are not available to apps without first requiring a specific library.
|
Name |
Description |
|
Loads and saves standard settings that can be later accessed and used across the application by other modules, screens, etc. Note: the app should always have its init() method called after being included. |
|
|
Contains 'helper' functions useful for development. |
|
|
Object used to send API requests to the PBX. |
|
|
Library that aids in the processing of date strings, appropriate to the cultural differences for the user of the app, for display purposes. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Takes a parameters object and a required keys array and compares the two. If any keys are missing from the array, then an error is logged and the error screen is shown (app.showErrors).
Basic Example:
var app = require('app');app.init(); app.checkRequired(parameters); |
Parameters
|
Name |
Required |
Type |
Default |
Description |
|
p |
Yes |
object |
This is an object containing key value pairs. |
|
|
required |
Yes |
array |
Array of keys that are checked against the keys of the p object. |
Error screen shown after failing checkRequired
The required parameter ['test'] was not a key in the 'p' object passed in.
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Loads and saves standard settings that can be later accessed and used across the application by other modules, screens, etc. Note: the app should always have its init() method called after being included.
Require Extended Library:
var app = require('app');app.init(); |
|
Name |
Description |
|
Takes a parameters object and a required keys array and compares the two. If any keys are missing from the array, then an error is logged and the error screen is shown (app.showErrors). |
|
|
Returns a reference to the automatically instantiated Auth object that is created when app.init is called. |
|
|
Returns an object that contains this app's various settings including id, settings, and account. These are parsed from the app's XML in the phone configuration's appconfig section. |
|
|
Initializes the app object. Important: this should be done immediately after including the app library for consistent results. |
|
|
Reloads your appconfig and makes a new Auth object. |
|
|
Clears the screen and shows an error popup on the entire screen. Takes an array of error messages so you can show multiple messages at one time. |
|
|
Returns the translated string of the specified language key. |
|
Name |
Description |
|
app.images |
Automatically instantiated Image UI objects when app is required. Basic Example: app.images.softKeys.left; // returns left arrow Image object app.images.softKeys.right; // returns left arrow Image object app.images.softKeys.up; // returns left arrow Image object app.images.softKeys.down; // returns left arrow Image object app.images.softKeys.select; // returns the check mark image app.images.softKeys.cancel; // returns left x cancel image These most likely useful for creating apps with standarized softkeys. See setSoftKeyIcon for setting softKey icons on your widgets. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Returns a reference to the automatically instantiated Auth object that is created when app.init is called.
Basic Example:
var authObj = app.getAuth(); |
Parameters
|
None |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Returns an object that contains this app's various settings including id, settings, and account. These are parsed from the app's XML in the phone configuration's appconfig section.
Basic Example:
var configData = app.getConfig(); |
|
None |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Initializes the app object. Important: this should be done immediately after including the app library for consistent results.
Basic Example:
app.init([parameters]); |
|
Name |
Required |
Type |
Default |
Description |
|
onError |
No |
function |
Overloads if your application wants to handle error specifically. |
|
|
defaultLangLocale |
No |
string |
Indicates the language file to use if the app does not have a language file for the phone's chosen language. For example, if the chosen language/locale is fr_fr, but the app does not include the file strings.fr_fr.js, then the app uses the default language file as indicated with this parameter. If no value has been defined, the phone tries to use en_us. |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Reloads your appconfig and makes a new Auth object.
Basic Example:
app.refreshConfig(); |
The app library automatically calls this on itself when the event 'digium.phone.new_config' happens. This makes sure your settings and Auth object are always up to date.
|
None |
Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70
Returns the translated string of the specified language key.
Basic Example:
var text = app.t(key[, vars, count]); |