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


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 :


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.

   "userData":{    "XIVO_CONTEXT":"from-extern",

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.


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 If dial fails, a failure Phone Events will be sent back to application.

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.


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


Originate a call


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


Answers a call. uniqueId is optional, but if you set it, you can explicitly answer a call among other ringing calls. (however, this parameter is for WebRTC only)


Put current call on hold. uniqueId is optional. If uniqueId is set it you can explicitly hold/unhold a call among other calls. (however, this parameter is for WebRTC only)

Note that you can’t have two established. If you have one establish call and on call on hold, if you unhold this last call, the established will go automatically on hold.


Tranfert to destination


Start a transfer to a destination


Complete previously started transfer


Cancel a transfer


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


Forward on non answer


Unconditionnal forward


Forward on busy


Set or unset do not disturb, state true or false

Phone Events

  • Cti.MessageType.PHONEEVENT


Phone events are automatically sent when application is connected.


        "otherDName":"Jane Black",
        "callDirection": "Incoming",
        username: "jblack"



Event types

  • EventReleased

  • EventDialing

  • EventRinging

  • EventEstablished

  • EventOnHold

  • EventFailure


The directory number of the event


Can be calling number of called number


Can be name of caller of called number


Optional, the queue name for inbound acd calls


Can be Incoming or Outgoing


Contains a list of attached data, system data XIVO_ or data attached to the call key beginning by USR_


Can be the username cti of called number, it’s only defined when the called user is an internal user

An event Failure can be sent when Cti.dial cannot be completed. Currently it is very specific and is triggered only in case of Originate (webrtc) and peer initiator of the call is not registered

If you use the following preprocess subroutine

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:

        "events": [
          "otherDName":"Jane Black",
          "callDirection": "Incoming",

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


        status: "AVAILABLE"

Possible status values are:


The phone has at least one held call


The phone is ringing


The phone is unavailable and is not able to receive calls


The phone is busy and ringing


The phone is available and ready to receive calls


The phone is on call


The phone is busy


The phone is deactivated and is not able to receive calls


The phone does not exist


An error occured while monitoring the phone. The phone may not be able to receive calls

Phone Hint Status Methods


  • 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.


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:


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”,