Phone API

This API allow you to remotely control a device once a user associated to the device through a line is authenticated.

A sample of implementation is available in app/assets/javascripts/pages/sample.js and app/views/sample/sample.scala.html

Phone Methods

Cti.setData(variables)

Attach data to the device current calls. When there is a call connected to a device, Data can be attached by passing key values as a json object Cti.setData(“{‘var1’:’val1’,’USR_var2’:’val2’}”);

The folowing json message is then sent to the server :

{"claz":"web","command":"setData","variables":{"var1":"val1","USR_var2":"val2"}}

When the call is transfered i.e. (Cti.directTransfer(destination)), data is sent in the event ringing see Phone Events, and in subsequent events. Data is not propagated in the reporting database.

{"eventType":"EventRinging","DN":"1000","otherDN":"0427466347","linkedId":"1469709757.74","uniqueId":"1469709960.78","queueName":"bluesky",
   "userData":{    "XIVO_CONTEXT":"from-extern",
                   "XIVO_USERID":"1",
                   "USR_var1":"val1",
                   "USR_var2":"val2",
                   "XIVO_EXTENPATTERN":"_012305XXXX",
                   "XIVO_SRCNUM":"0427466347",
                   "XIVO_DST_FIRSTNAME":"Brucé",
                   "XIVO_DSTNUM":"0123053012","XIVO_DST_LASTNAME":"Wail"}}

Note that USR_ prefix is added to the key, if the key does not start with it. Only attached data beginning with USR_ are sent back to the client API.

Warning

When transfering a call, these variables are attached to the new channel however to prevent propagation on all trunk channels, your trunk name must contain ‘trunk’ so they can be distinguished from sip devices.

Cti.dial(destination, variables)

Place a call to destination with the provided variables. Variables must take the following form:

{
    var1: "value 1",
    var2: "value 2"
}

USR_var1 and USR_var2 will be attached to the call and propagated to Phone Events

Cti.dialFromMobile(destination, variables)

Place a call from logged user’s mobile number to destination with the provided variables. Variables must take the following form:

{
    var1: "value 1",
    var2: "value 2"
}

USR_var1 and USR_var2 will be attached to the call and propagated to Phone Events

When placing a call using this api, Phone Events will be sent through the websocket when calls state change. If a call is made to a conference room hosted on the XiVO, Conference Events will be sent also.

Warning

When entering a conference room using this API, if the conference room is configured with an administrator PIN, the user will enter directly the conference room as an administrator without having to enter a PIN code. If the conference room has only a user PIN, the user will also enter directly without having to enter a PIN code.

Cti.dialByUsername(username, variables)

Place a call to destination, defined by username, with the provided variables. Variables must take the following form:

{
    var1: "value 1",
    var2: "value 2"
}

USR_var1 and USR_var2 will be attached to the call and propagated to Phone Events

Cti.originate(destination)

Originate a call

Cti.hangup(uniqueId)

Hangup established call. uniqueId is optional, but if you set it, you can explicitly hangup a call.

Cti.answer()

Answer a call

Cti.hold()

Put current call on hold

Cti.directTransfer(destination)

Tranfert to destination

Cti.attendedTransfer(destination)

Start a transfer to a destination

Cti.completeTransfer()

Complete previously started transfer

Cti.cancelTransfer()

Cancel a transfer

Cti.getCurrentCallsPhoneEvents()

Request PhoneEvents for current device calls. See Phone Events for answer description.

Cti.naFwd(destination,state)

Forward on non answer

Cti.uncFwd(destination,state)

Unconditionnal forward

Cti.busyFwd(destination,state)

Forward on busy

Cti.dnd(state)

Set or unset do not disturb, state true or false

Phone Events

  • Cti.MessageType.PHONEEVENT
  • Cti.MessageType.CURRENTCALLSPHONEEVENTS

Phone events are automatically sent when application is connected.

Format

{
    "msgType":"PhoneEvent",
    "ctiMessage":{
        "eventType":"EventRinging",
        "DN":"1118",
        "otherDN":"1058",
        "otherDName":"Jane Black",
        "linkedId":"1447670380.34",
        "uniqueId":"1447670382.37",
        "queueName":"blue",
        "callDirection": "Incoming",
        "userData":{
            "XIVO_CONTEXT":"default","XIVO_USERID":"9","XIVO_SRCNUM":"1058","XIVO_DSTNUM":"3000"
        },
        username: "jblack"
    }
}
fields Description
Event types
  • EventReleased
  • EventDialing
  • EventRinging
  • EventEstablished
  • EventOnHold
DN The directory number of the event
otherDN Can be calling number of called number
otherDName Can be name of caller of called number
queueName Optional, the queue name for inbound acd calls
callDirection Can be Incoming or Outgoing
UserData Contains a list of attached data, system data XIVO_ or data attached to the call key beginning by USR_
username Can be the username cti of called number, it’s only defined when the called user is an internal user

If you use the following preprocess subroutine

[user_data_test]
exten = s,1,Log(DEBUG,**** set user data ****)
same  =       n,SET(USR_DATA1=hello)
same  =       n,SET(USR_DATA2=24)
same  =       n,SET(USR_DATA3=with space)
same  =       n,Return()

you will get these data in the events. Data can also be attached using the Cti.dial command.

You can also request a message with a concatenation of PhoneEvents for current calls by Cti.getCurrentCallsPhoneEvents command. The response to this command is formatted as follows:

{
    "msgType":"CurrentCallsPhoneEvents",
    "ctiMessage":{
        "events": [
        {
          "eventType":"EventRinging",
          "DN":"1118",
          "otherDN":"1058",
          "otherDName":"Jane Black",
          "linkedId":"1447670380.34",
          "uniqueId":"1447670382.37",
          "queueName":"blue",
          "callDirection": "Incoming",
          "userData":{
              "XIVO_CONTEXT":"default","XIVO_USERID":"9","XIVO_SRCNUM":"1058","XIVO_DSTNUM":"3000"
          }
        },
        {
          "eventType":"EventEstablished",
          ...
        },
        ...
    }
}

Phone Status Update

When opening the websocket, the following message will be received automatically. It will indicate the current phone status (or the webrtc status) of the user and indicate if the user is ready to receive calls. A new event will be received if, for any reason, the phone (or the webrtc line) becomes unavailable.

Cti Message Type
Cti.MessageType.PHONESTATUSUPDATE
Example
{
    "msgType":"PhoneStatusUpdate",
    "ctiMessage":{
        status: "AVAILABLE"
    }
}

Possible status values are:

ONHOLD
The phone has at least one held call
RINGING
The phone is ringing
INDISPONIBLE
The phone is unavailable and is not able to receive calls
BUSY_AND_RINGING
The phone is busy and ringing
AVAILABLE
The phone is available and ready to receive calls
CALLING
The phone is on call
BUSY
The phone is busy
DEACTIVATED
The phone is deactivated and is not able to receive calls
UNEXISTING
The phone does not exist
ERROR
An error occured while monitoring the phone. The phone may not be able to receive calls

Phone Hint Status Methods

Cti.subscribeToPhoneHints(phoneNumbers)

  • phoneNumbers (Array of string): list of phone numbers to subscribe

Subscribe to PhoneHintStatusEvents for a list of phone numbers. You will get an initial event with the current Phone Hint Status (see Phone Hint Status Events for details) for every subscribed phone number and then a new Phone Hint Status Events for every change to the phone number state. After the Xuc server restart it may happen that the current phone state is unknown, in which case you will not get the initial event, only the first event update. You can repeat the command to subscribe to more numbers. The subscription is valid for the current websocket and can be cancelled either by closing the websocket, or by the Cti.unsubscribeFromAllPhoneHints() command.

Cti.unsubscribeFromAllPhoneHints()

This command allows you to cancel all previous subscription to phone hints.

Phone Hint Status Events

You can subscribe to PhoneHintStatusEvents using Cti.subscribeToPhoneHints, allowing you to monitor state of the phone line with a given number. PhoneHintStatusEvents has the following format:

{
    "msgType":"PhoneHintStatusEvent",
    "ctiMessage":{
        "number":"1005","status":0
    }
}

The phone hint status code can be resolved to a name using the Cti.PhoneStatus object in the cti.js. E.g., the status 0 from the example above stands for “AVAILABLE”.

Voice Mail Status Events

  • VOICEMAILSTATUSUPDATE : “VoiceMailStatusUpdate”,
{"msgType":"VoiceMailStatusUpdate","ctiMessage":{"voiceMailId":58,"newMessages":2,"waitingMessages":1,"oldMessages":1}}