Dolby Voice Remote Control API

Table of Contents

Introduction

Remote Control API is a WebSocket based interface that allows external applications to control the Dolby Voice Room/Dolby Conference Phone. These APIs are intended for A/V system integrators who need to configure, control and manage Dolby Voice devices.

The service provider apps can extend the Remote Control APIs. Refer Extending Remote Control API

Getting Started

Connecting to the API

Any WebSocket client can be used to connect to the API. Connect to Remote Control APIs using wss://<device_IP>/remoteapi address.

Hostname verification

It is only possible to connect to the server over a secure WebSocket connection (wss://). Because the server uses a hardcoded certificate in which common name may not correspond to the device hostname, users need to disable hostname verification in their WebSocket client. Please refer to your WebSocket library documentation for detail instructions.

Authentication

After connecting, the client must authorize in order to be able to send requests and receive notifications. The authorization must happen within 60 seconds of the connection. Refer login API for authorization.

Message format

The server only accepts requests in JSON format. Response messages are in JSON format as well. After authorization, any request message must always have at least these three attributes: sessionId, resource, and event. Request parameters must be attributes of parameters object.

Asynchronous model

Until the moment when the client receives a message about successful authorization, it can expect that every received message is the reply to the most recent request. After authorization, the client should not expect to receive a response immediately. Instead, it should process every message received from the server. After a request is sent, depending on whether or not it implies changes in configuration or the internal state, the client may expect to receive a respective notification.

Authentication API

These API manages authentication and session of the remote control clients. The client must login first to start the session. The session will be extended for 60 seconds after every transaction. The client may call the extended API to explicitly extend the session during idle situations.

Login

Use login API to authenticate clients within 60 seconds of opening the WebSocket connection. After successful authentication sessionId will be returned in the response that must be used in all subsequent requests. Maximum 5 clients can be connected to the server simultaneously.

Resource Event
auth login

Required parameters

Parameter Type Description
username string Login name
password string Password

Request example

{  
    "resource":"auth",
    "event":"login",
    "parameters":{  
        "username":"admin",
        "password":"1739"
    }
}

Response example

{
    "response":"ok",
    "resource":"auth",
    "event":"login",
    "id":"1369463002",
    "role":"admin"
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type
event string Event type
id string Session id that must be used in all subsequent requests
role string Role assigned to the user

Logout

Logout the user with the given sessionId.

Resource Event
auth logout

Request example

{
    "sessionId":"123456",
    "resource":"auth",
    "event":"logout"
}

Response example

{
    "response":"ok",
    "resource":"auth",
    "event":"logout",
    "id":"123456",
    "status":"expired"
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type
event string Event type
id string Session id
status string Status of this session

Get session information

Resource Event
auth info

Request example

{
    "sessionId":"123456",
    "resource":"auth",
    "event":"info"
}

Response example

{
    "response":"ok",
    "resource":"auth",
    "event":"info",
    "id":"123456",
    "username":"",
    "role":"admin",
    "source":"unknown",
    "status":"active",
    "timeout":"180",
    "remained":"169",
    "callback":"assigned"
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type
event string Event type
id string Session id
username string Username of the person who created this session
role string Role assigned to this session
source string Type of client
status string Status of this session
timeout string Number of seconds since the beginning of this session
remained string Number of seconds until this session expires
callback string True if a callback is assigned on session expiration

Extend session

Resource Event
auth extend

Request example

{
    "sessionId":"123456",
    "resource":"auth",
    "event":"extend"
}

Response example

{
    "response":"ok",
    "resource":"auth",
    "event":"info",
    "id":"1018645977",
    "username":"",
    "role":"admin",
    "source":"remote_api",
    "status":"active",
    "timeout":"180",
    "remained":"169",
    "callback":"assigned"
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type
event string Event type
id string Session id
username string Username of the person who created this session
role string Role assigned to this session
source string Type of client
status string Status of this session
timeout string Number of seconds since the beginning of this session
remained string Number of seconds until this session expires
callback string True if callback is assigned on session expiration

Configuration API

These API allows the client to read and change configurations on the device.

Refer configuration parameters for the list of the configuration parameters which can be accessed using these APIs.

Error codes

Follows the list of error codes may come in the responses to incorrect requests or in case of an error.

Code Description
4000 Invalid request format
4001 Unknown request
5000 Parameter-specific errors; check every parameter
5002 Parameter does not exist
5003 Invalid value
5013 Invalid value
5014 Invalid value
5018 Invalid value
5004 Invalid value range
5005 Invalid value type
5006 Read access denied
5007 Write access denied
5008 Invalid value length
5009 Invalid numeric value
5010 Invalid alphabet value
5011 Invalid alphanumeric value
5012 Invalid IP
5015 Invalid domain value
5016 Invalid URL value
5021 Invalid ASCII value
5023 Provisioned configuration, cannot be modified by users

Get all configuration parameters

Get all configuration parameters list and their values. This is useful for initial sync after a new connection or reconnection.

Resource Event
cfg get

Required parameters

Parameter Type Description
all string Must be empty

Request example

{
    "sessionId":"123456",
    "resource":"cfg",
    "event":"get",
    "parameters":{
        "all":""
    }
}

Response example

{  
    "response":"ok",
    "resource":"cfg",
    "event":"get",
    "parameters":[  
        {  
            "name":"Features.OperationMode",
            "value":"DUALMODE",
            "provisioned":true,
            "rebootOnChange":true
        },
        {  
            "name":"Features.RecentCallsEnabled",
            "value":true,
            "provisioned":true,
            "rebootOnChange":false
        },
        {  
            "name":"Features.UserFeedback.Enabled",
            "value":false,
            "provisioned":false,
            "rebootOnChange":false
        },
        {  
            "name":"Features.UserFeedback.Hotline",
            "value":"",
            "provisioned":false,
            "rebootOnChange":false
        },
        ...
        ...
        ...
        ...
        ...
        {  
            "name":"Network.DNS2",
            "value":"10.203.129.10",
            "provisioned":false,
            "rebootOnChange":false
        },
        {  
            "name":"Network.Ethernet.Speed",
            "value":"100",
            "provisioned":false,
            "rebootOnChange":false
        },
        {  
            "name":"Network.Ethernet.Duplex",
            "value":"half",
            "provisioned":false,
            "rebootOnChange":false
        },
        {  
            "name":"Network.Status.LinkState",
            "value":"SUCCESS_UP",
            "provisioned":false,
            "rebootOnChange":false
        },
        {  
            "name":"Network.Status.Eapol",
            "value":"NOT_APPLICABLE_UNCONFIGURED",
            "provisioned":false,
            "rebootOnChange":false
        },
        {  
            "name":"Network.Status.EapolMethod",
            "value":"UNKNOWN",
            "provisioned":false,
            "rebootOnChange":false
        },
        {  
            "name":"Network.Status.EapolPhase2Method",
            "value":"UNKNOWN",
            "provisioned":false,
            "rebootOnChange":false
        },
        {  
            "name":"Network.Status.SpeedDuplexMatch",
            "value":"NOT_APPLICABLE_LLDP_UNAVAILABLE",
            "provisioned":false,
            "rebootOnChange":false
        },
        {  
            "name":"Network.Status.LldpNeighbor",
            "value":"NOT_APPLICABLE_NO_NEIGHBOR",
            "provisioned":false,
            "rebootOnChange":false
        },
        {  
            "name":"Network.Status.VoiceVlanStatus",
            "value":"NOT_APPLICABLE_UNCONFIGURED",
            "provisioned":false,
            "rebootOnChange":false
        },
        {  
            "name":"Network.Status.Dhcp",
            "value":"SUCCESS",
            "provisioned":false,
            "rebootOnChange":false
        }

    ]
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type
event string Event type
parameters object List of parameters
name string Parameter name
value var Parameter value
provisioned boolean True if this parameter is configured through provisioning
rebootOnChanged boolean True if a reboot is required to apply this change

Get parameter value

Get the value of one or multiple parameters.

Resource Event
cfg get

Required parameters

Parameter Type Description
Parameter name string Value must be empty

Request example

{
    "sessionId":"123456",
    "resource":"cfg",
    "event":"get",
    "parameters":{
        "Features.OperationMode":""
    }
}

Response example

{
    "response":"ok",
    "resource":"cfg",
    "event":"get",
    "parameters":[
        {
            "name":"Features.OperationMode",
            "value":"DUALMODE",
            "provisioned":true,
            "rebootOnChange":true
        }
    ]
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type
event string Event type
parameters object List of parameters
name string Parameter name
value var Parameter value
provisioned boolean True if this parameter is configured through provisioning
rebootOnChanged boolean True if a reboot is required to apply this change

Error response example

{  
    "response":"failed",
    "resource":"cfg",
    "event":"get",
    "description":5000,
    "parameters":[  
        {  
            "name":"Network.IpAddres",
            "error":5002
        }
    ]
}

Error response parameters

Parameter Type Description
response string Failure or success
resource string Resource type
event string Event type
description number Response error code
parameters object List of parameters
name string Parameter name
error number Parameter-specific error code

Set parameter value

Set value of a one or multiple parameters.

Resource Event
cfg set

Required parameters

Parameter Type Description
Parameter name var

Request example

{
    "sessionId":"123456",
    "resource":"cfg",
    "event":"set",
    "parameters":{
        "Features.OperationMode":"DUALMODE"
    }
}

Response example

{
    "response":"ok",
    "resource":"cfg",
    "event":"set",
    "parameters":[
        {
            "name":"Features.OperationMode",
            "value":"DUALMODE",
            "provisioned":false,
            "rebootOnChange":true
        }
    ]
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type
event string Event type
parameters object List of parameters
name string Parameter name
value var Parameter value
provisioned boolean True if this parameter is configured through provisioning
rebootOnChanged boolean True if a reboot is required to apply this change

Error response example

{  
    "response":"failed",
    "resource":"cfg",
    "event":"get",
    "description":5000,
    "parameters":[  
        {  
            "name":"Network.IpAddres",
            "error":5002
        }
    ]
}

Error response parameters

Parameter Type Description
response string Failure or success
resource string Resource type
event string Event type
description number Response error code
parameters object List of parameters
name string Parameter name
error number Parameter-specific error code

Reset parameter value

Set configuration parameter value to default; response contains the default value.

Resource Event
cfg reset

Required parameters

Parameter Type Description
Parameter name string

Request example

{
    "sessionId":"123456",
    "resource":"cfg",
    "event":"reset",
    "parameters":{
        "Features.OperationMode":""
    }
}

Response example

{
    "response":"ok",
    "resource":"cfg",
    "event":"reset",
    "parameters":[
        {
            "name":"Features.OperationMode",
            "value":"DUALMODE",
            "provisioned":false,
            "rebootOnChange":true
        }
    ]
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type
event string Event type
parameters object List of parameters
name string Parameter name
value var Parameter value
provisioned boolean True if this parameter is configured through provisioning
rebootOnChanged boolean True if a reboot is required to apply this change

Error response example

{  
    "response":"failed",
    "resource":"cfg",
    "event":"get",
    "description":5000,
    "parameters":[  
        {  
            "name":"Network.IpAddres",
            "error":5002
        }
    ]
}

Error response parameters

Parameter Type Description
response string Failure or success
resource string Resource type
event string Event type
description number Response error code
parameters object List of parameters
name string Parameter name
error number Parameter-specific error code

Reboot device

Reboots the device.

Resource Event
cfg reboot

Request example

{
    "sessionId":"123456",
    "resource":"cfg",
    "event":"reboot"
}

Response example

{
    "response":"ok",
    "resource":"cfg",
    "parameters":[
        {
            "name":"Device.Status.Reboot",
            "value":"STARTED",
            "provisioned":false,
            "rebootOnChange":false
        }
    ]
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type
event string Event type
parameters object List of parameters
name string Parameter name
value string Parameter value, possible values: "REQUIRED", "PENDING", "PENDING_DELAYED", "CANCELLED", "STARTED", "STARTED_DELAYED"
provisioned boolean True if this parameter is configured through provisioning
rebootOnChanged boolean True if reboot is required to apply this change

Factory reset

Reset device to factory default settings.

Resource Event
cfg factoryReset

Request example

{
    "sessionId":"123456",
    "resource":"cfg",
    "event":"factoryReset"
}

Response example

{
    "response":"ok",
    "resource":"cfg",
    "factoryReset":"ok"
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type
factoryReset string Status

Provisioning API

These APIs used for provisioning activities like fetch configurations with the provisioning server, control software update process, etc.

Provision

Initiate provisioning routine which fetches configuration from the provisioning server. This might trigger software update if the new firmware is provisioned along with the configurations.

Resource Event
pvs provision

Request example

{
    "sessionId":"123456",
    "resource":"pvs",
    "event":"provision"
}

Response example

{
    "resource":"pvs",
    "response":"ok"
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type

Check for software update

Resource Event
pvs swupdate

Required parameters

Parameter Type Description
check string Must be empty

Request example

{
    "sessionId":"123456",
    "resource":"pvs",
    "event":"swupdate",
    "parameters":{
        "check":""
    }
}

Response example

{
    "resource":"pvs",
    "response":"ok",
    "swupdate":{
        "available":true,
        "version":"3.0.0.15"
    }
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type
swupdate object Software update information
available boolean True if software update is available
version string New software version

Start software update

Resource Event
pvs swupdate

Required parameters

Parameter Type Description
start string Must be empty

Request example

{
    "sessionId":"123456",
    "resource":"pvs",
    "event":"swupdate",
    "parameters":{
        "start":""
    }
}

Response example

{
    "resource":"pvs",
    "response":"ok"
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type

Get software update status

Resource Event
pvs swupdate

Required parameters

Parameter Type Description
status string Must be empty

Request example

{
    "sessionId":"123456",
    "resource":"pvs",
    "event":"swupdate",
    "parameters":{
        "status":""
    }
}

Response example

{
    "resource":"pvs",
    "response":"ok",
    "swupdate":{
        "available":true,
        "version":"3.0.0.15",
        "status":"updating",
        "error":1000,
        "progress":99
    }
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type
swupdate object Software update information
available boolean True if software update is available
version string New software version
status string Update status, possible values: "updating", "failed", "complete", "cancelled"
error number Error code, possible values: 1000, 1001, 1002
progress number Progress percentage, -1 if not applicable

Error codes

Code Description
1000 Unable to download software image file
1001 Invalid signature on software image file
1002 Invalid software image file

Cancel software update

Cancel the software update. This is useful for deferring the update process to a later time.

Resource Event
pvs swupdate

Required parameters

Parameter Type Description
cancel string Must be empty

Request example

{
    "sessionId":"123456",
    "resource":"pvs",
    "event":"swupdate",
    "parameters":{
        "cancel":""
    }
}

Response example

{
    "resource":"pvs",
    "response":"ok"
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type

Telephony API

Telephony APIs are used to request the IPPBX call related actions like making a call, answering the call, muting the call etc. These APIs also provide information about active calls. Also, refer notifications section for the call state change updates.

Make a call

Start a new IPPBX call. The dial string should be passed as number parameter. Currently, devices allow up to 2 telephony calls simultaneously.

Resource Event
call dial

Required parameters

Parameter Type Description
phone string Called party number

Request example

{
    "sessionId":"123456",
    "resource":"call",
    "event":"dial",
    "parameters":{
        "phone":"3012"
    }
}

Response example

{
    "response":"ok"
}

Response parameters

Parameter Type Description
response string Failure or success

End call

Terminate the active call by call id.

Resource Event
call end

Required parameters

Parameter Type Description
id string Call id

Request example

{
    "sessionId":"123456",
    "resource":"call",
    "event":"end",
    "parameters":{
        "id":"0"
    }
}

Response example

{
    "response":"ok"
}

Response parameters

Parameter Type Description
response string Failure or success

Get call information

Retrieve detailed information of the call specified by id parameter. Detail information of all current calls is returned if id is set to -1; useful for initial sync up with the device on the first connect or reconnect.

Resource Event
call get

Required parameters

Parameter Type Description
id string Call id or -1

Request example

{
    "sessionId":"123456",
    "resource":"call",
    "event":"get",
    "parameters":{
        "id":"0"
    }
}

Response example

{
    "call": [
        {
            "actions": "end;transfer;hold;mute;presentationMode",
            "codec": "G722",
            "dialpadEnabled": true,
            "direction": "outgoing",
            "duration": 50,
            "firstname": "UAE-Dev-DCP",
            "id": 100,
            "lastname": "",
            "localHold": false,
            "local_contact": "<sip:3005@10.112.100.103;transport=TCP>",
            "local_info": "\"DCP 3005\" <sip:3005@10.203.131.99>",
            "muted": true,
            "phone": "3006",
            "remoteHold": false,
            "remote_contact": "<sip:3006@10.203.131.99:5060;transport=tcp>",
            "remote_info": "<sip:3006@10.203.131.99:5060>",
            "server_ip": "10.203.131.99",
            "state": "Connected",
            "status": 200,
            "status_text": "OK",
            "transport": "TCP",
            "tunnel_ip": "",
            "tunnel_type": "DIRECT",
            "type": "PBX",
            "uuid": "aef43699-109d-4578-ae4c-bbfe0e7f5e90"
        }
    ],
    "event": "resource-update",
    "resource": "call"
}

Response parameters

Parameter Type Description
event string Event type
resource string Resource type
call object List of current calls (only 1 item if call id is specified)
actions string Enabled call actions
codec string Codec name
dialpadEnabled boolean Enable/Disable dialpad for DTMF
direction string Call direction (incoming or outgoing)
duration number Call duration
firstname string User first name
id number Internal call ID
lastname string User last name
localHold boolean Local hold state
local_contact string Information about local contact
local_info string Information about local account
muted boolean Mute state
phone string Account number
remoteHold boolean Remote hold state
remote_contact string Information about remote contact
remote_info string Information about the peer
server_ip string SIP server address
state string Current call state, possible values: "Calling", "Ringing", "Connected", "Failed"
status number SIP response status
status_text string Status text
transport string Current SIP transport, possible values: "TCP", "UDP", "TLS"
tunnel_ip string Conference call tunnel IP address
tunnel_type string Tunnel type, possible values: "ACME", "Dolby", "DIRECT"
type string Call type, possible values: "PBX", "CONF"
uuid string Unique call id

Answer or reject incoming call

Answer or reject the incoming call. The call is accepted if answer is set to “yes” and rejected if “no”. end is used only when another call is active and answer is “yes”. The current active call will be ended if the end parameter is set to “yes” or it will be put on hold for “no”. The device will send a preliminary response followed by call status in a notification.

Resource Event
call answer

Required parameters

Parameter Type Description
id string Call id
answer string Answer or reject call
end string End current active call or put it in on-hold state

Request example

{
    "sessionId":"123456",
    "resource":"call",
    "event":"answer",
    "parameters":{
        "id":"0",
        "answer":"yes",
        "end":"no"
    }
}

Response example

{
    "response":"ok"
}

Response parameters

Parameter Type Description
response string Failure or success

Send DTMF to peer

This API sends DTMF to the far end during the call. The key parameter indicates which key the user has pressed. It may also be used for the application to provide a sequence of DTMF for canned DTMF commands. For example, key value can be "00234" to send a sequence of DTMF digits automatically to the far end.

Resource Event
call dtmf

Required parameters

Parameter Type Description
id string Call id
key string DTMF to be sent to the peer

Request example

{
    "sessionId":"123456",
    "resource":"call",
    "event":"dtmf",
    "parameters":{
        "id":"0",
        "key":"1"
    }
}

Response example

{
    "response":"ok"
}

Response parameters

Parameter Type Description
response string Failure or success

Place call on hold

Put a call on hold or resume already held call. This API toggles the hold state of the call. The device will send a preliminary response followed by call status in a notification which contains the hold information.

Resource Event
call hold

Required parameters

Parameter Type Description
id string Call id

Request example

{
    "sessionId":"123456",
    "resource":"call",
    "event":"hold",
    "parameters":{
        "id":"0"
    }
}

Response example

{
    "response":"ok"
}

Response parameters

Parameter Type Description
response string Failure or success

Hangup all calls

Terminate all active calls.

Resource Event
call hangupall

Request example

{
    "sessionId":"123456",
    "resource":"call",
    "event":"hangupall"
}

Response example

{
    "response":"ok"
}

Response parameters

Parameter Type Description
response string Failure or success

Mute device

Mute and unmute the device during the call. This API toggles the mute state. The will send preliminary response followed by the mute status in a call notification.

Resource Event
call mute

Request example

{
    "sessionId":"123456",
    "resource":"call",
    "event":"mute"
}

Response example

{
    "response":"ok"
}

Response parameters

Parameter Type Description
response string Failure or success

Transfer call

Transfer the call with specified id to another number. The device will send a preliminary response followed by call transfer status in a notification.

Resource Event
call transfer

Required parameters

Parameter Type Description
id string Call id
phone string New destination number

Request example

{
    "sessionId":"123456",
    "resource":"call",
    "event":"transfer",
    "parameters":{
        "id":"0",
        "phone":"12345"
    }
}

Response example

{
    "response":"ok"
}

Response parameters

Parameter Type Description
response string Failure or success

Merge calls

Merge two active IPPBX calls into a three-way call. A merged call id is returned in a call notification on a successful merge.

Resource Event
call join

Required parameters

Parameter Type Description
id string First call id
second_id string Second call id

Request example

{
    "sessionId":"123456",
    "resource":"call",
    "event":"join",
    "parameters":{
        "id":"0",
        "second_id":"1"
    }
}

Response example

{
    "response":"ok"
}

Response parameters

Parameter Type Description
response string Failure or success

Split calls

Split the three-way (merged) call back to two separate IPPBX calls. After splitting, both calls are in hold state. The device will send a preliminary response followed by call split status in a call notification.

Resource Event
call split

Required parameters

Parameter Type Description
id string Call id

Request example

{
    "sessionId":"123456",
    "resource":"call",
    "event":"split",
    "parameters":{
        "id":"10000"
    }
}

Response example

{
    "response":"ok"
}

Response parameters

Parameter Type Description
response string Failure or success

Device Management API

Dolby Voice Room Device Management API

Upload logs

Upload the device's logs. The type specifies the kind of logs to upload:

  • "FULL": Upload maximum log information.
  • "EVENTS_ONLY": Only upload text log events.
  • "CALL_STATS": Upload call statistics.
Resource Event
device uploadLogs

Required parameters

Parameter Type Description
url string URL to upload the logs
logPackageType string What logs should be sent, possible values: "FULL", "EVENTS_ONLY", "CALL_STATS"

Request example

{
    "sessionId":"123456",
    "resource":"device",
    "event":"uploadLogs",
    "parameters":{
        "url":"http:/uploadhere",
        "logPackageType":"FULL"
    }
}

Response example There will be notifications sent by the device as the status changes.

{
    "resource":"device",
    "event":"logs-upload-update",
    "status": "IN_PROGRESS"
}

Response parameters

Parameter Type Description
resource string Failure or success
event string Longs upload update
status string Possible values are "IN_PROGRESS", "SUCCESS" and "FAILED"

Send logs to Dolby

Upload device logs to the Dolby diagnostic website, useful for reporting problems to Dolby. Check Device.Status.DiagnosticsUpload configuration parameter for the status of the last request.

Resource Event
device uploadDiag

Request example

{
    "sessionId":"123456",
    "resource":"device",
    "event":"uploadDiag"
}

There is no response to this request.

Dolby Conference Phone Device Management API

Device management APIs for Dolby Conference Phone.

Upload logs

Upload DCP logs to the URL specified in url. Set eventLogsOnly to true for uploading event logs only otherwise this uploads the full log package.

Resource Event
device uploadLogs

Required parameters

Parameter Type Description
url string URL to upload the logs
eventLogsOnly boolean true for uploading event logs only, false for full package

Request example

{
    "sessionId":"123456",
    "resource":"device",
    "event":"uploadLogs",
    "parameters":{
        "url":"http:/uploadhere",
        "eventLogsOnly": false
    }
}

Response example There will be notification as the status changes.

{
    "resource":"device",
    "event":"logs-upload-update",
    "status": "IN_PROGRESS"
}

Response parameters

Parameter Type Description
resource string Failure or success
event string Longs upload update
status string Possible values are "IN_PROGRESS", "SUCCESS" and "FAILED"

Send logs to Dolby

Upload device logs to the Dolby diagnostic website, useful for reporting problems to Dolby. Check Device.Status.DiagnosticsUpload configuration parameter for the status of the last request.

Resource Event
device uploadDiag

Request example

{
    "sessionId":"123456",
    "resource":"device",
    "event":"uploadDiag"
}

There is no response to this request.

LED on

Turns on the halo LED with color. You may specify an on time with blink_on and off time with blink_off to create blink patterns. Default blink_on and blink_off to 0. Both blink_on and blink_off are in milliseconds.

Resource Event
device ledOn

Required parameters

Parameter Type Description
color string Color of the LED. Possible values are "red", "green" and "blue"
blink_on number Blink on time in milliseconds
blink_off number Blink off time in milliseconds

Request example

{
    "sessionId":"123456",
    "resource":"device",
    "event":"ledOn",
    "parameters":{
        "color":"red",
        "blink_on": 0,
        "blink_off": 0
    }
}

There is no response to this request.

LED Off

Turns off the halo LED if it is on.

Resource Event
device ledOff

Request example

{
    "sessionId":"123456",
    "resource":"device",
    "event":"ledOff"
}

There is no response to this request.

Play tone

Plays tone specified by tone. Alerts can be replayed repeat times with pause of pause milliseconds. The client must wait at least 100 milliseconds between the two subsequent requests.

Resource Event
device playTone

Required parameters

Parameter Description
tone Tone to be played. Possible values: "ring", "ringback", "busy", "alert", "conf_join", "conf_leave", "keytap"
repeat Number of times tone should be played

Optional parameters

Parameter Description
pause Pause time in milliseconds before next repeat

Request example

{
    "sessionId":"123456",
    "resource":"device",
    "event":"playTone",
    "parameters":{
        "tone":"ring",
        "repeat":"2",
        "pause":"1"
    }
}

There is no response to this request.

Stop tone

Stops playing the current tone. The DCP will silently ignore this request if no tone is being played.

Resource Event
device stopTone

Request example

{
    "sessionId":"123456",
    "resource":"device",
    "event":"stopTone"
}

There is no response to this request.

Start BLE advertising

Starts BLE (Bluetooth Low Energy) advertisement on the DCP with the UUID and data provided by the request.

Resource Event
device startBleAdvertising

Required parameters

Parameter Description
uuid Application-defined unique id of BLE device (2, 4 or 16 bytes)
data Data for advertisement (array of 8 bit integers)

Optional parameters

Parameter Description
adv_interval BLE advertisement interval in milliseconds. Value must be in [100, 5000] range (step of 100 ms). Default value is 100

Request example

{
    "sessionId":"123456",
    "resource":"device",
    "event":"startBleAdvertising",
    "parameters":{
        "uuid":"1234",
        "data":"abc",
        "adv_interval":"1000"
    }
}

There is no response to this request.

Stop BLE advertising

Stops BLE (Bluetooth Low Energy) advertisement on the DCP.

Resource Event
device stopBleAdvertising

Request example

{
    "sessionId":"123456",
    "resource":"device",
    "event":"stopBleAdvertising"
}

There is no response to this request.

Call Log API

These APIs allows to access and remove recent call log entries.

Get the List of Recent Calls

Get the full list using this API. Useful for periodic sync up. The list also comes as notification when changes are made.

Resource Event
recent list_update

Request example

{
    "sessionId":"123456",
    "resource":"recent",
    "event":"list_update"
}

Response example

{
    "resource":"cl_list_update",
    "response":"ok",
    "timeFmt":"h:mm ap",
    "dateFmt":"MMMM d, yyyy",
    "total":1,
    "entries":[
        {
            "uuid":"{36db920f-5778-40ba-bf21-9365685b0489}",
            "codec_name":"G711U",
            "firstName":"",
            "lastName":"",
            "number":"3014",
            "time":"1437000467",
            "human_time":"Wed Jul 15 15:47:47 2015",
            "duration":2,
            "satmic":false,
            "type":"out",
            "origin":"dialpad",
            "transport":"TCP",
            "server_ip":"10.203.131.87",
            "tunnel_ip":"",
            "tunnel_type":"DIRECT",
            "diagnosticReports":[
                {
                    "type":"I hear echo",
                    "timestamp":16,
                    "audioLogFile":"audiolog_20150715170533.tar"
                }
            ]
        }
    ]
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type
timeFmt string Time format
dateFmt string Date format
total number Total number of recent calls
entries object List of recent calls
uuid string Unique call id
codec_name string Codec name
firstName string First name
lastName string Last name
number string Called party number
time string Call start time in seconds since epoch
human_time string Call start time in local time zone
duration number Duration of call in seconds
satmic boolean If true, satellite microphone is connected
type string Call direction, possible values: "in", "out", "missed", "missed_new", "conf"
origin string Call origin, possible values: "dial pad", "call_log", "directory", "conference", "fallback"
transport string Transport used in the call, possible values: "TCP", "UDP", "TLS"
server_ip string Call server address
tunnel_ip string Tunnel address (if applicable)
tunnel_type string Tunnel type, possible values: "DIRECT", "ACME", "DVTS"
diagnosticsReports object List of reported audio issues (only if audio logging mode is set to "diagnostics")
type string Description of reported audio problem
timestamp number Number of seconds past since problem was reported
audioLogFile string File name of the log file uploaded to the provisioning server

Delete entry

Delete an entry from the recent calls.

Resource Event
recent delete_entry

Required parameters

Parameter Type Description
uuid string Call id

Request example

{
    "sessionId":"123456",
    "resource":"recent",
    "event":"delete_entry",
    "parameters":{
        "uuid":"0"
    }
}

Response example

{
    "resource":"cl_delete",
    "response":"ok"
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type

Delete all

Delete all recent call entries.

Resource Event
recent delete_all

Request example

{
    "sessionId":"123456",
    "resource":"recent",
    "event":"delete_all"
}

Response example

{
    "resource":"cl_delete",
    "response":"ok"
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type

Reset number of missed calls

Resource Event
recent reset_num_missed

Request example

{
    "sessionId":"123456",
    "resource":"recent",
    "event":"reset_num_missed"
}

There is no response to this request.

Directory API

Interface to LDAP based directory services.

Search by name

Search the directory service for contacts with the given name.

Resource Event
ds search

Required parameters

Parameter Type Description
key string Search key (first or last name)
localOnly string Search locally only or search LDAP

Request example

{
    "sessionId":"123456",
    "resource":"ds",
    "event":"search",
    "parameters":{
        "key":"john",
        "localOnly":"0"
    }
}

Response example

{
    "resource":"ds_search",
    "response":"ok",
    "description":"203 Could not read the local directory file",
    "dserror":4,
    "total":1,
    "entries":[
        {
            "firstName":"Navneet",
            "lastName":"Bansal",
            "number":"103221",
            "uuid":"206458",
            "type":"ldap"
        }
    ]
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type
description string Response description
dserror number Error code
total number Total number of found entries
entries object List of found contacts
firstName string First name
lastName string Last name
number string Phone number
uuid string Unique user id
type string Search type

Search by number

Search the directory service for contacts with the given number.

Resource Event
ds revsearch

Required parameters

Parameter Type Description
number string Search key (phone number)

Request example

{
    "sessionId":"123456",
    "resource":"ds",
    "event":"revsearch",
    "parameters":{
        "number":"100"
    }
}

Response example

{
    "resource":"ds_revsearch",
    "response":"ok",
    "total":1,
    "entries":[
        {
            "firstName":"Smith",
            "lastName":"Lake",
            "number":"100",
            "uuid":"",
            "type":"local"
        }
    ]
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type
total number Total number of found entries
entries object List of found contacts
firstName string First name
lastName string Last name
number string Phone number
uuid string Unique user id
type string Search type

Add contact

Add a contact in the local directory.

Resource Event
ds addcontact

Required parameters

Parameter Type Description
firstName string First name
lastName string Last name
phone string Phone number

Request example

{
    "sessionId":"123456",
    "resource":"ds",
    "event":"addcontact",
    "parameters":{
        "firstName":"Smith",
        "lastName":"Don",
        "phone":"103221"
    }
}

Response example

{
    "resource":"ds_editcontacts",
    "response":"ok"
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type

Edit contact

Edit a contact in the local directory.

Resource Event
ds editcontact

Required parameters

Parameter Type Description
oldFirstName string Old first name
oldLastName string Old last name
oldPhone string Old phone number
firstName string New first name
lastName string New last name
phone string New phone number

Request example

{
    "sessionId":"123456",
    "resource":"ds",
    "event":"editcontact",
    "parameters":{
        "oldFirstName":"Smith",
        "oldLastName":"Don",
        "oldPhone":"103221",
        "firstName":"Smith",
        "lastName":"Don",
        "phone":"103222"
    }
}

Response example

{
    "resource":"ds_editcontacts",
    "response":"ok"
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type

Delete contact

Delete a contact from the local directory.

Resource Event
ds deletecontact

Required parameters

Parameter Type Description
firstName string First name
lastName string Last name
phone string Phone number

Request example

{
    "sessionId":"123456",
    "resource":"ds",
    "event":"deletecontact",
    "parameters":{
        "firstName":"Smith",
        "lastName":"Don",
        "phone":"103223"
    }
}

Response example

{
    "resource":"ds_editcontacts",
    "response":"ok"
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type

Conference Service Provider App API

Remote Control API provides a communication channel; it is Service Providers' responsibility to implement extensions in their application to support this method. The service provider app should extend the remote control APIs by following instructions in Extending Remote Control API

Send message

Send a message to the Service Provider application running on the device.

Resource Event
serviceproviderapp sendmessage

Required parameters

Parameter Type Description
message string Data in text format supported by Conference Service Provider application

Request example

{
    "resource" : "serviceproviderapp",
    "event" : "sendMessage",
    "sessionId" : "123456",
    "parameters" : {
        "message" : "{\"resource\":\"math\",\"event\":\"randomnumber\",\"parameters\":{\"min\":\"10\",\"max\":\"20\"}}"
    }
}

Response example

{
    "event": "sendMessage",
    "message": "{\"response\":\"ok\",\"resource\":\"math\",\"event\":\"randomnumber\",\"parameters\":{\"number\":\"19\"}}",
    "resource": "serviceproviderapp",
    "response": "ok",
    "sessionId": "123456"
}

Response parameters

Parameter Type Description
response string Failure or success
resource string Resource type
event string Event type
sessionId string Session id of the client this messaged is targeted to. Use "broadcast" for delivering to all connected clients
message string Data in text format defined by Conference Service Provider application

Notifications

Authentication Session Expired

Example notification

{
    "event": "notification",
    "id": "123456",
    "resource": "auth",
    "status": "expired"
}

Notification parameters

Parameter Type Description
resource string Resource type
event string Event type
id string Session id
status string Status of this session

Configuration or status update

Example notification

{
    "response":"ok",
    "resource":"cfg",
    "event":"notification",
    "parameters":[
        {
            "name":"Features.OperationMode",
            "value":"DUALMODE",
            "provisioned":false,
            "rebootOnChange":true
        }
    ]
}

Notification parameters

Parameter Type Description
response string Failure or success
resource string Resource type
event string Event type
name string Parameter or status name
value string Parameter value
provisioned boolean True if this parameter is configured through provisioning
rebootOnChange boolean True if reboot is required to apply this change

Reboot

Example notification

{
    "response":"ok",
    "resource":"cfg",
    "event":"notification",
    "parameters":[
        {
            "name":"Device.Status.Reboot",
            "value":"STARTED",
            "provisioned":false,
            "rebootOnChange":false
        }
    ]
}

Notification parameters

Parameter Type Description
response string Failure or success
resource string Resource type
event string Event type
name string Parameter name
value string Parameter value, possible values: "REQUIRED", "PENDING", "PENDING_DELAYED", "CANCELLED", "STARTED", "STARTED_DELAYED"
provisioned boolean True if this parameter is configured through provisioning
rebootOnChange boolean True if reboot is required to apply this change

Merge calls

Example notification

{
    "actions": "Hold,End,Split",
    "call": [
        {
            "actions": "end;transfer;hold;presentationMode",
            "codec": "G722",
            "dialpadEnabled": true,
            "direction": "outgoing",
            "duration": 27,
            "firstname": "DVR",
            "id": 100,
            "lastname": "",
            "localHold": true,
            "local_contact": "<sip:3006@10.112.100.111;transport=TCP>",
            "local_info": "\"Dolby Voice\" <sip:3006@10.203.131.99>",
            "muted": true,
            "phone": "3005",
            "remoteHold": false,
            "remote_contact": "<sip:3005@10.203.131.99:5060;transport=tcp>",
            "remote_info": "<sip:3005@10.203.131.99:5060>",
            "server_ip": "10.203.131.99",
            "state": "Connected",
            "status": 200,
            "status_text": "OK",
            "transport": "TCP",
            "tunnel_ip": "",
            "tunnel_type": "DIRECT",
            "type": "PBX",
            "uuid": "f1ace07d-6788-48cc-9003-2bce31826e69"
        },
        {
            "actions": "end;transfer;hold;mute;presentationMode",
            "codec": "G722",
            "dialpadEnabled": true,
            "direction": "outgoing",
            "duration": 11,
            "firstname": "1307-",
            "id": 102,
            "lastname": "3.3",
            "localHold": false,
            "local_contact": "<sip:3006@10.112.100.111;transport=TCP>",
            "local_info": "\"Dolby Voice\" <sip:3006@10.203.131.99>",
            "muted": true,
            "phone": "1307",
            "remoteHold": false,
            "remote_contact": "<sip:1307@10.203.131.99:5060;transport=tcp>",
            "remote_info": "<sip:1307@10.203.131.99:5060>",
            "server_ip": "10.203.131.99",
            "state": "Connected",
            "status": 200,
            "status_text": "OK",
            "transport": "TCP",
            "tunnel_ip": "",
            "tunnel_type": "DIRECT",
            "type": "PBX",
            "uuid": "af27f715-211f-4738-aa18-219f545b9771"
        }
    ],
    "event": "resource-update",
    "id": 1001,
    "localHold": false,
    "merged": true,
    "resource": "call"
}

Notification parameters

Parameter Type Description
event string Event type
resource string Resource type
merged boolean Merge flag
call object List of current calls (only 1 item if call id is specified)
actions string Enabled call actions
codec string Codec name
dialpadEnabled boolean Enable/Disable dialpad for DTMF
direction string Call direction (incoming or outgoing)
duration number Call duration
firstname string User first name
id number Internal call ID
lastname string User last name
localHold boolean Local hold state
local_contact string Information about local contact
local_info string Information about local account
muted boolean Mute state
phone string Account number
remoteHold boolean Remote hold state
remote_contact string Information about remote contact
remote_info string Information about the peer
server_ip string SIP server address
state string Current call state, possible values: "Calling", "Ringing", "Connected", "Failed"
status number SIP response status
status_text string Status text
transport string Current SIP transport, possible values: "TCP", "UDP", "TLS"
tunnel_ip string Conference call tunnel IP address
tunnel_type string Tunnel type, possible values: "ACME", "Dolby", "DIRECT"
type string Call type, possible values: "PBX", "CONF"
uuid string Unique call id

Split calls

Example notification

{
    "call": [
    ],
    "event": "resource-update",
    "id": 1001,
    "merged": false,
    "resource": "call"
}

Notification parameters

Parameter Type Description
resource string Resource type
event string Event type
merged boolean Merge flag
id number Merged call id
call object Empty array

Software update progress

Example notification

{
    "resource":"pvs",
    "response":"ok",
    "swupdate":{
        "available":true,
        "version":"3.0.0.15",
        "status":"updating",
        "error":1000,
        "progress":99
    }
}

Notification parameters

Parameter Type Description
response string Failure or success
resource string Resource type
swupdate object Software update information
available boolean True if the software update is available
version string New software version
status string Update status, possible values: "idle", "updating", "failed", "complete", "cancelled"
error number Error code
progress number Progress percentage, -1 if not applicable

Extending Remote Control API

Conference Service Providers can extend Remote Control API to add functions not provided by built-in resources. In order to extend Remote Control API, Service Providers need to create a WebSocket client, connect to Remote Control API WebSocket server using local address ws://127.0.0.1:10000, and make sure it was authorized. Remote Control API WebSocket server will automatically authorize any local client, but only if there is no other Service Provider application connected.

The message confirming successful authorization:

{
    "response" : "ok",
    "resource" : "auth",
    "event" : "login",
    "description" : "Authorized as Service Provider App"
}

If some other local client is already connected, you will receive an appropriate notification and connection will be closed:

{
    "response" : "failed",
    "resource" : "auth",
    "event" : "login",
    "description" : "Unable to authorize as Service Provider App"
}

There are two basic things Service Provider App should do: process incoming messages from individual Remote App clients and reply to them, and broadcast notifications.

To send a message to Service Provider application, Remote Clients should refer to sendMessage event of serviceproviderapp resource:

{
    "resource" : "serviceproviderapp",
    "event" : "sendMessage",
    "sessionId" : "1949511058",
    "parameters" : {
        "message" : "{\"resource\":\"math\",\"event\":\"randomnumber\",\"parameters\":{\"min\":\"10\",\"max\":\"20\"}}"
    }
}

Message parameter is simply a string, thus Service Providers can use any text format they want (using JSON is encouraged as all Remote App clients already support JSON). Remote Control API server will process this message and remove fields that Service Provider App does not need to know about. The request message received by Service Provider application will look as shown below:

{
    "sessionId" : "1949511058",
    "message" : "{\"resource\":\"math\",\"event\":\"randomnumber\",\"parameters\":{\"min\":\"10\",\"max\":\"20\"}}"
}

The reply message from the Service Provider app, in this case, could be something like

{
    "sessionId" : "1949511058",
    "message": "{\"response\":\"ok\",\"resource\":\"math\",\"event\":\"randomnumber\",\"parameters\":{\"number\":\"19\"}}"
}

and the message delivered to the original Remote App client will have all relevant attributes:

{
    "event": "sendMessage",
    "message": "{\"response\":\"ok\",\"resource\":\"math\",\"event\":\"randomnumber\",\"parameters\":{\"number\":\"19\"}}",
    "resource": "serviceproviderapp",
    "response": "ok",
    "sessionId": "1949511058"
}

At any time, Service Provider application can broadcast a notification that will be delivered to all connected Remote App clients. In order to do so, Service Provider App should specify keyword broadcast as sessionId of the message. It could be used, for example, to announce available resources and events after successful authorization:

{
    "sessionId" : "broadcast",
    "message":"{\"message\":\"Greetings from Remote Control API Test App!\",\"availableResources\":[{\"name\":\"fun\",\"events\":[\"randomjoke\"]},{\"name\":\"math\",\"events\":[\"randomnumber\"]}]}"
}