Phones - Creating and Handling Calls

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 guide provides a basic overview for handling call events and performing various actions (e.g., hangup) on calls.

The digium.event function is key to working with calls (https://sangomakb.atlassian.net/wiki/spaces/Phones/pages/22020316 ). When you register for an event that has to do with call creation, an eventData object is passed to your handler that provides a variety of information. Most important is the callHandle. Here is an example of the eventData from an incoming call.

{
     "eventName":"digium.phone.incoming_call",
     "eventData":{
          "state":"INCOMING",
          "accountSlot":"0",
          "callHandle":"319-5",
          "remoteInfo":"\"Princess Peach\" <sip:101@10.10.8.218>",
          "remoteContact":"<sip:101@10.10.8.218>",
          "lastStatus":"0",
          "lastStatusText":"",
          "mediaStatus":"none",
          "headers":{"Via":"SIP/2.0/UDP 10.10.8.218:5060;rport=5060;received=10.10.8.218;branch=z9hG4bK1a83d2ea",
          "From":"\"Princess Peach\" <sip:101@10.10.8.218>;tag=as486547c6",
          "To":"<sip:200@10.10.6.193;ob>",
          "Contact":"<sip:101@10.10.8.218>",
          "Call-ID":"0d82476949832b7b6974c23e107cd479@10.10.8.218",
          "CSeq":"102 INVITE","User-Agent":"Asterisk PBX (digium)",
          "Max-Forwards":"70","Date":"Tue, 12 Mar 2013 05:11:58 GMT",
          "Allow":"INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, SUBSCRIBE, NOTIFY, INFO",
          "Supported":"replaces",
          "Content-Type":"application/sdp",
          "Content-Length":"288"},
     "role":"callee","local_info":"<sip:200@10.10.6.193;ob>",
     "local_contact":"\"200\" <sip:200@10.10.6.193:5060;ob>",
     "connect_duration":"0",
     "account_subslot":"0"
},"messageId":"ae277800"}

The digium.phone function provides a set of useful methods for working with calls (https://sangomakb.atlassian.net/wiki/spaces/Phones/pages/22315220 ). You can do things such as answer, hangup, and dial. Dial is used for starting a call, and the rest can be used to handle an existing call. The following example shows the process of observing a call, handling the response, and performing actions on the call itself.

//declare currentCall as a "global"
var currentCall = {};
digium.app.exitAfterBackground = false; //keep the app running in the background
  
// event listener for incoming calls
digium.event.observe({
    'eventName' : 'digium.phone.incoming_call',
    'callback'  : showCID
});
  
function showCID (evt) {
    digium.foreground(); //foreground the app when we get an incoming_call
    var callHandle = evt.eventData.callHandle; //this how the system identifies the call
    var role = evt.eventData.role; //caller or callee
  
    // parse out name from remoteInfo using a regex
    var name = (new RegExp(/^\"(.*)\"/).exec(evt.eventData.remoteInfo)) ? RegExp.$1 : "";
    // parse out number from remoteInfo using a regex
    var number = (new RegExp(/<sip:(\d+)/).exec(evt.eventData.remoteInfo)) ? RegExp.$1 : "";
  
    // this is declared outside of our function so it is "global" and accessible to other functions
    currentCall = {
        'role'          : role,
        'name'          : name,
        'number'        : number,
        'callHandle'    : callHandle
    }
  
    var cid = "Name: " + currentCall.name + " Number: " + currentCall.number;
    window.add(new Text(0, 20, window.w, Text.LINE_HEIGHT, cid));
  
    // set softkeys up
    setSoftkeys();
}
  
function setSoftkeys () {
    //softkey 1 answers
    window.setSoftkey(1, 'Answer', function () {
        digium.phone.answer({
            'callHandle'    : currentCall.callHandle,
            'handler'       : function (obj) {
                myDebug('App had a phone action (Answer)take place. State:' + obj.state);
            }
        });
    });
  
    //softkey 2 rejects
    window.setSoftkey(2, 'Reject', function () {
        digium.phone.reject({
            'callHandle'    : currentCall.callHandle,
            'handler'       : function (obj) {
                myDebug('App had a phone action (Reject)take place. State:' + obj.state);
            }
        });
    });
  
    //softkey 3 transfer
    window.setSoftkey(3, 'Transfer', function () {
        digium.phone.transfer({
            'callHandle'    : currentCall.callHandle,
            'handler'       : function (obj) {
                myDebug('App had a phone action (Transfer) take place. State:' + obj.state);
            }
        });
    });
}