Dolby Voice Remote Control API

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](#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](#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.

ResourceEvent
authlogin
ParameterTypeDescription
usernamestringLogin name
passwordstringPassword
{
    "resource":"auth",
    "event":"login",
    "parameters":{
        "username":"admin",
        "password":"1739"
    }
}
{
    "response":"ok",
    "resource":"auth",
    "event":"login",
    "id":"1369463002",
    "role":"admin"
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type
eventstringEvent type
idstringSession id that must be used in all subsequent requests
rolestringRole assigned to the user

Logout

Logout the user with the given sessionId.

ResourceEvent
authlogout
{
    "sessionId":"123456",
    "resource":"auth",
    "event":"logout"
}
{
    "response":"ok",
    "resource":"auth",
    "event":"logout",
    "id":"123456",
    "status":"expired"
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type
eventstringEvent type
idstringSession id
statusstringStatus of this session

Get session information

ResourceEvent
authinfo
{
    "sessionId":"123456",
    "resource":"auth",
    "event":"info"
}
{
    "response":"ok",
    "resource":"auth",
    "event":"info",
    "id":"123456",
    "username":"",
    "role":"admin",
    "source":"unknown",
    "status":"active",
    "timeout":"180",
    "remained":"169",
    "callback":"assigned"
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type
eventstringEvent type
idstringSession id
usernamestringUsername of the person who created this session
rolestringRole assigned to this session
sourcestringType of client
statusstringStatus of this session
timeoutstringNumber of seconds since the beginning of this session
remainedstringNumber of seconds until this session expires
callbackstringTrue if a callback is assigned on session expiration

Extend session

ResourceEvent
authextend
{
    "sessionId":"123456",
    "resource":"auth",
    "event":"extend"
}
{
    "response":"ok",
    "resource":"auth",
    "event":"info",
    "id":"1018645977",
    "username":"",
    "role":"admin",
    "source":"remote_api",
    "status":"active",
    "timeout":"180",
    "remained":"169",
    "callback":"assigned"
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type
eventstringEvent type
idstringSession id
usernamestringUsername of the person who created this session
rolestringRole assigned to this session
sourcestringType of client
statusstringStatus of this session
timeoutstringNumber of seconds since the beginning of this session
remainedstringNumber of seconds until this session expires
callbackstringTrue 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](./configuration-parameters.html) 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.

CodeDescription
4000Invalid request format
4001Unknown request
5000Parameter-specific errors; check every parameter
5002Parameter does not exist
5003Invalid value
5013Invalid value
5014Invalid value
5018Invalid value
5004Invalid value range
5005Invalid value type
5006Read access denied
5007Write access denied
5008Invalid value length
5009Invalid numeric value
5010Invalid alphabet value
5011Invalid alphanumeric value
5012Invalid IP
5015Invalid domain value
5016Invalid URL value
5021Invalid ASCII value
5023Provisioned 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.

ResourceEvent
cfgget
ParameterTypeDescription
allstringMust be empty
{
    "sessionId":"123456",
    "resource":"cfg",
    "event":"get",
    "parameters":{
        "all":""
    }
}
{
    "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
        }
    ]
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type
eventstringEvent type
parametersobjectList of parameters
namestringParameter name
valuevarParameter value
provisionedbooleanTrue if this parameter is configured through provisioning
rebootOnChangedbooleanTrue if a reboot is required to apply this change

Get parameter value

Get the value of one or multiple parameters.

ResourceEvent
cfgget
ParameterTypeDescription
Parameter namestringValue must be empty
{
    "sessionId":"123456",
    "resource":"cfg",
    "event":"get",
    "parameters":{
        "Features.OperationMode":""
    }
}
{
    "response":"ok",
    "resource":"cfg",
    "event":"get",
    "parameters":[
        {
            "name":"Features.OperationMode",
            "value":"DUALMODE",
            "provisioned":true,
            "rebootOnChange":true
        }
    ]
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type
eventstringEvent type
parametersobjectList of parameters
namestringParameter name
valuevarParameter value
provisionedbooleanTrue if this parameter is configured through provisioning
rebootOnChangedbooleanTrue if a reboot is required to apply this change
{
    "response":"failed",
    "resource":"cfg",
    "event":"get",
    "description":5000,
    "parameters":[
        {
            "name":"Network.IpAddres",
            "error":5002
        }
    ]
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type
eventstringEvent type
descriptionnumberResponse error code
parametersobjectList of parameters
namestringParameter name
errornumberParameter-specific error code

Set parameter value

Set value of a one or multiple parameters.

ResourceEvent
cfgset
ParameterTypeDescription
Parameter namevar
{
    "sessionId":"123456",
    "resource":"cfg",
    "event":"set",
    "parameters":{
        "Features.OperationMode":"DUALMODE"
    }
}
{
    "response":"ok",
    "resource":"cfg",
    "event":"set",
    "parameters":[
        {
            "name":"Features.OperationMode",
            "value":"DUALMODE",
            "provisioned":false,
            "rebootOnChange":true
        }
    ]
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type
eventstringEvent type
parametersobjectList of parameters
namestringParameter name
valuevarParameter value
provisionedbooleanTrue if this parameter is configured through provisioning
rebootOnChangedbooleanTrue if a reboot is required to apply this change
{
    "response":"failed",
    "resource":"cfg",
    "event":"get",
    "description":5000,
    "parameters":[
        {
            "name":"Network.IpAddres",
            "error":5002
        }
    ]
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type
eventstringEvent type
descriptionnumberResponse error code
parametersobjectList of parameters
namestringParameter name
errornumberParameter-specific error code

Reset parameter value

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

ResourceEvent
cfgreset
ParameterTypeDescription
Parameter namestring
{
    "sessionId":"123456",
    "resource":"cfg",
    "event":"reset",
    "parameters":{
        "Features.OperationMode":""
    }
}
{
    "response":"ok",
    "resource":"cfg",
    "event":"reset",
    "parameters":[
        {
            "name":"Features.OperationMode",
            "value":"DUALMODE",
            "provisioned":false,
            "rebootOnChange":true
        }
    ]
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type
eventstringEvent type
parametersobjectList of parameters
namestringParameter name
valuevarParameter value
provisionedbooleanTrue if this parameter is configured through provisioning
rebootOnChangedbooleanTrue if a reboot is required to apply this change
{
    "response":"failed",
    "resource":"cfg",
    "event":"get",
    "description":5000,
    "parameters":[
        {
            "name":"Network.IpAddres",
            "error":5002
        }
    ]
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type
eventstringEvent type
descriptionnumberResponse error code
parametersobjectList of parameters
namestringParameter name
errornumberParameter-specific error code

Reboot device

Reboots the device.

ResourceEvent
cfgreboot
{
    "sessionId":"123456",
    "resource":"cfg",
    "event":"reboot"
}
{
    "response":"ok",
    "resource":"cfg",
    "parameters":[
        {
            "name":"Device.Status.Reboot",
            "value":"STARTED",
            "provisioned":false,
            "rebootOnChange":false
        }
    ]
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type
eventstringEvent type
parametersobjectList of parameters
namestringParameter name
valuestringParameter value, possible values: "REQUIRED", "PENDING", "PENDING_DELAYED", "CANCELLED", "STARTED", "STARTED_DELAYED"
provisionedbooleanTrue if this parameter is configured through provisioning
rebootOnChangedbooleanTrue if reboot is required to apply this change

Factory reset

Reset device to factory default settings.

ResourceEvent
cfgfactoryReset
{
    "sessionId":"123456",
    "resource":"cfg",
    "event":"factoryReset"
}
{
    "response":"ok",
    "resource":"cfg",
    "factoryReset":"ok"
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type
factoryResetstringStatus

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.

ResourceEvent
pvsprovision
{
    "sessionId":"123456",
    "resource":"pvs",
    "event":"provision"
}
{
    "resource":"pvs",
    "response":"ok"
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type

Check for software update

ResourceEvent
pvsswupdate
ParameterTypeDescription
checkstringMust be empty
{
    "sessionId":"123456",
    "resource":"pvs",
    "event":"swupdate",
    "parameters":{
        "check":""
    }
}
{
    "resource":"pvs",
    "response":"ok",
    "swupdate":{
        "available":true,
        "version":"3.0.0.15"
    }
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type
swupdateobjectSoftware update information
availablebooleanTrue if software update is available
versionstringNew software version

Start software update

ResourceEvent
pvsswupdate
ParameterTypeDescription
startstringMust be empty
{
    "sessionId":"123456",
    "resource":"pvs",
    "event":"swupdate",
    "parameters":{
        "start":""
    }
}
{
    "resource":"pvs",
    "response":"ok"
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type

Get software update status

ResourceEvent
pvsswupdate
ParameterTypeDescription
statusstringMust be empty
{
    "sessionId":"123456",
    "resource":"pvs",
    "event":"swupdate",
    "parameters":{
        "status":""
    }
}
{
    "resource":"pvs",
    "response":"ok",
    "swupdate":{
        "available":true,
        "version":"3.0.0.15",
        "status":"updating",
        "error":1000,
        "progress":99
    }
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type
swupdateobjectSoftware update information
availablebooleanTrue if software update is available
versionstringNew software version
statusstringUpdate status, possible values: "updating", "failed", "complete", "cancelled"
errornumberError code, possible values: 1000, 1001, 1002
progressnumberProgress percentage, -1 if not applicable
CodeDescription
1000Unable to download software image file
1001Invalid signature on software image file
1002Invalid software image file

Cancel software update

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

ResourceEvent
pvsswupdate
ParameterTypeDescription
cancelstringMust be empty
{
    "sessionId":"123456",
    "resource":"pvs",
    "event":"swupdate",
    "parameters":{
        "cancel":""
    }
}
{
    "resource":"pvs",
    "response":"ok"
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource 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.

ResourceEvent
calldial
ParameterTypeDescription
phonestringCalled party number
{
    "sessionId":"123456",
    "resource":"call",
    "event":"dial",
    "parameters":{
        "phone":"3012"
    }
}
{
    "response":"ok"
}
ParameterTypeDescription
responsestringFailure or success

End call

Terminate the active call by call id.

ResourceEvent
callend
ParameterTypeDescription
idstringCall id
{
    "sessionId":"123456",
    "resource":"call",
    "event":"end",
    "parameters":{
        "id":"0"
    }
}
{
    "response":"ok"
}
ParameterTypeDescription
responsestringFailure 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.

ResourceEvent
callget
ParameterTypeDescription
idstringCall id or -1
{
    "sessionId":"123456",
    "resource":"call",
    "event":"get",
    "parameters":{
        "id":"0"
    }
}
{
    "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"
}
ParameterTypeDescription
eventstringEvent type
resourcestringResource type
callobjectList of current calls (only 1 item if call id is specified)
actionsstringEnabled call actions
codecstringCodec name
dialpadEnabledbooleanEnable/Disable dialpad for DTMF
directionstringCall direction (incoming or outgoing)
durationnumberCall duration
firstnamestringUser first name
idnumberInternal call ID
lastnamestringUser last name
localHoldbooleanLocal hold state
local_contactstringInformation about local contact
local_infostringInformation about local account
mutedbooleanMute state
phonestringAccount number
remoteHoldbooleanRemote hold state
remote_contactstringInformation about remote contact
remote_infostringInformation about the peer
server_ipstringSIP server address
statestringCurrent call state, possible values: "Calling", "Ringing", "Connected", "Failed"
statusnumberSIP response status
status_textstringStatus text
transportstringCurrent SIP transport, possible values: "TCP", "UDP", "TLS"
tunnel_ipstringConference call tunnel IP address
tunnel_typestringTunnel type, possible values: "ACME", "Dolby", "DIRECT"
typestringCall type, possible values: "PBX", "CONF"
uuidstringUnique 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.

ResourceEvent
callanswer
ParameterTypeDescription
idstringCall id
answerstringAnswer or reject call
endstringEnd current active call or put it in on-hold state
{
    "sessionId":"123456",
    "resource":"call",
    "event":"answer",
    "parameters":{
        "id":"0",
        "answer":"yes",
        "end":"no"
    }
}
{
    "response":"ok"
}
ParameterTypeDescription
responsestringFailure 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.

ResourceEvent
calldtmf
ParameterTypeDescription
idstringCall id
keystringDTMF to be sent to the peer
{
    "sessionId":"123456",
    "resource":"call",
    "event":"dtmf",
    "parameters":{
        "id":"0",
        "key":"1"
    }
}
{
    "response":"ok"
}
ParameterTypeDescription
responsestringFailure 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.

ResourceEvent
callhold
ParameterTypeDescription
idstringCall id
{
    "sessionId":"123456",
    "resource":"call",
    "event":"hold",
    "parameters":{
        "id":"0"
    }
}
{
    "response":"ok"
}
ParameterTypeDescription
responsestringFailure or success

Hangup all calls

Terminate all active calls.

ResourceEvent
callhangupall
{
    "sessionId":"123456",
    "resource":"call",
    "event":"hangupall"
}
{
    "response":"ok"
}
ParameterTypeDescription
responsestringFailure 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.

ResourceEvent
callmute
{
    "sessionId":"123456",
    "resource":"call",
    "event":"mute"
}
{
    "response":"ok"
}
ParameterTypeDescription
responsestringFailure 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.

ResourceEvent
calltransfer
ParameterTypeDescription
idstringCall id
phonestringNew destination number
{
    "sessionId":"123456",
    "resource":"call",
    "event":"transfer",
    "parameters":{
        "id":"0",
        "phone":"12345"
    }
}
{
    "response":"ok"
}
ParameterTypeDescription
responsestringFailure 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.

ResourceEvent
calljoin
ParameterTypeDescription
idstringFirst call id
second_idstringSecond call id
{
    "sessionId":"123456",
    "resource":"call",
    "event":"join",
    "parameters":{
        "id":"0",
        "second_id":"1"
    }
}
{
    "response":"ok"
}
ParameterTypeDescription
responsestringFailure 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.

ResourceEvent
callsplit
ParameterTypeDescription
idstringCall id
{
    "sessionId":"123456",
    "resource":"call",
    "event":"split",
    "parameters":{
        "id":"10000"
    }
}
{
    "response":"ok"
}
ParameterTypeDescription
responsestringFailure 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:

ResourceEvent
deviceuploadLogs
ParameterTypeDescription
urlstringURL to upload the logs
logPackageTypestringWhat logs should be sent, possible values: "FULL", "EVENTS_ONLY", "CALL_STATS"
{
    "sessionId":"123456",
    "resource":"device",
    "event":"uploadLogs",
    "parameters":{
        "url":"http:/uploadhere",
        "logPackageType":"FULL"
    }
}

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

{
    "resource":"device",
    "event":"logs-upload-update",
    "status": "IN_PROGRESS"
}
ParameterTypeDescription
resourcestringFailure or success
eventstringLongs upload update
statusstringPossible 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.

ResourceEvent
deviceuploadDiag
{
    "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.

ResourceEvent
deviceuploadLogs
ParameterTypeDescription
urlstringURL to upload the logs
eventLogsOnlyboolean`true` for uploading event logs only, `false` for full package
{
    "sessionId":"123456",
    "resource":"device",
    "event":"uploadLogs",
    "parameters":{
        "url":"http:/uploadhere",
        "eventLogsOnly": false
    }
}

There will be notification as the status changes.

{
    "resource":"device",
    "event":"logs-upload-update",
    "status": "IN_PROGRESS"
}
ParameterTypeDescription
resourcestringFailure or success
eventstringLongs upload update
statusstringPossible 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.

ResourceEvent
deviceuploadDiag
{
    "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.

ResourceEvent
deviceledOn
ParameterTypeDescription
colorstringColor of the LED. Possible values are "red", "green" and "blue"
blink_onnumberBlink on time in milliseconds
blink_offnumberBlink off time in milliseconds
{
    "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.

ResourceEvent
deviceledOff
{
    "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.

ResourceEvent
deviceplayTone
ParameterDescription
toneTone to be played. Possible values: "ring", "ringback", "busy", "alert", "conf_join", "conf_leave", "keytap"
repeatNumber of times tone should be played
ParameterDescription
pausePause time in milliseconds before next repeat
{
    "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.

ResourceEvent
devicestopTone
{
    "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.

ResourceEvent
devicestartBleAdvertising
ParameterDescription
uuidApplication-defined unique id of BLE device (2, 4 or 16 bytes)
dataData for advertisement (array of 8 bit integers)
ParameterDescription
adv_intervalBLE advertisement interval in milliseconds. Value must be in [100, 5000] range (step of 100 ms). Default value is 100
{
    "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.

ResourceEvent
devicestopBleAdvertising
{
    "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.

ResourceEvent
recentlist_update
{
    "sessionId":"123456",
    "resource":"recent",
    "event":"list_update"
}
{
    "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"
                }
            ]
        }
    ]
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type
timeFmtstringTime format
dateFmtstringDate format
totalnumberTotal number of recent calls
entriesobjectList of recent calls
uuidstringUnique call id
codec_namestringCodec name
firstNamestringFirst name
lastNamestringLast name
numberstringCalled party number
timestringCall start time in seconds since epoch
human_timestringCall start time in local time zone
durationnumberDuration of call in seconds
satmicbooleanIf true, satellite microphone is connected
typestringCall direction, possible values: "in", "out", "missed", "missed_new", "conf"
originstringCall origin, possible values: "dial pad", "call_log", "directory", "conference", "fallback"
transportstringTransport used in the call, possible values: "TCP", "UDP", "TLS"
server_ipstringCall server address
tunnel_ipstringTunnel address (if applicable)
tunnel_typestringTunnel type, possible values: "DIRECT", "ACME", "DVTS"
diagnosticsReportsobjectList of reported audio issues (only if audio logging mode is set to "diagnostics")
typestringDescription of reported audio problem
timestampnumberNumber of seconds past since problem was reported
audioLogFilestringFile name of the log file uploaded to the provisioning server

Delete entry

Delete an entry from the recent calls.

ResourceEvent
recentdelete_entry
ParameterTypeDescription
uuidstringCall id
{
    "sessionId":"123456",
    "resource":"recent",
    "event":"delete_entry",
    "parameters":{
        "uuid":"0"
    }
}
{
    "resource":"cl_delete",
    "response":"ok"
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type

Delete all

Delete all recent call entries.

ResourceEvent
recentdelete_all
{
    "sessionId":"123456",
    "resource":"recent",
    "event":"delete_all"
}
{
    "resource":"cl_delete",
    "response":"ok"
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type

Reset number of missed calls

ResourceEvent
recentreset_num_missed
{
    "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.

ResourceEvent
dssearch
ParameterTypeDescription
keystringSearch key (first or last name)
localOnlystringSearch locally only or search LDAP
{
    "sessionId":"123456",
    "resource":"ds",
    "event":"search",
    "parameters":{
        "key":"john",
        "localOnly":"0"
    }
}
{
    "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"
        }
    ]
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type
descriptionstringResponse description
dserrornumberError code
totalnumberTotal number of found entries
entriesobjectList of found contacts
firstNamestringFirst name
lastNamestringLast name
numberstringPhone number
uuidstringUnique user id
typestringSearch type

Search by number

Search the directory service for contacts with the given number.

ResourceEvent
dsrevsearch
ParameterTypeDescription
numberstringSearch key (phone number)
{
    "sessionId":"123456",
    "resource":"ds",
    "event":"revsearch",
    "parameters":{
        "number":"100"
    }
}
{
    "resource":"ds_revsearch",
    "response":"ok",
    "total":1,
    "entries":[
        {
            "firstName":"Smith",
            "lastName":"Lake",
            "number":"100",
            "uuid":"",
            "type":"local"
        }
    ]
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type
totalnumberTotal number of found entries
entriesobjectList of found contacts
firstNamestringFirst name
lastNamestringLast name
numberstringPhone number
uuidstringUnique user id
typestringSearch type

Add contact

Add a contact in the local directory.

ResourceEvent
dsaddcontact
ParameterTypeDescription
firstNamestringFirst name
lastNamestringLast name
phonestringPhone number
{
    "sessionId":"123456",
    "resource":"ds",
    "event":"addcontact",
    "parameters":{
        "firstName":"Smith",
        "lastName":"Don",
        "phone":"103221"
    }
}
{
    "resource":"ds_editcontacts",
    "response":"ok"
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type

Edit contact

Edit a contact in the local directory.

ResourceEvent
dseditcontact
ParameterTypeDescription
oldFirstNamestringOld first name
oldLastNamestringOld last name
oldPhonestringOld phone number
firstNamestringNew first name
lastNamestringNew last name
phonestringNew phone number
{
    "sessionId":"123456",
    "resource":"ds",
    "event":"editcontact",
    "parameters":{
        "oldFirstName":"Smith",
        "oldLastName":"Don",
        "oldPhone":"103221",
        "firstName":"Smith",
        "lastName":"Don",
        "phone":"103222"
    }
}
{
    "resource":"ds_editcontacts",
    "response":"ok"
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type

Delete contact

Delete a contact from the local directory.

ResourceEvent
dsdeletecontact
ParameterTypeDescription
firstNamestringFirst name
lastNamestringLast name
phonestringPhone number
{
    "sessionId":"123456",
    "resource":"ds",
    "event":"deletecontact",
    "parameters":{
        "firstName":"Smith",
        "lastName":"Don",
        "phone":"103223"
    }
}
{
    "resource":"ds_editcontacts",
    "response":"ok"
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource 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](#extending-remote-control-api)

Send message

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

ResourceEvent
serviceproviderappsendmessage
ParameterTypeDescription
messagestringData in text format supported by Conference Service Provider application
{
    "resource" : "serviceproviderapp",
    "event" : "sendMessage",
    "sessionId" : "123456",
    "parameters" : {
        "message" : "{\"resource\":\"math\",\"event\":\"randomnumber\",\"parameters\":{\"min\":\"10\",\"max\":\"20\"}}"
    }
}
{
    "event": "sendMessage",
    "message": "{\"response\":\"ok\",\"resource\":\"math\",\"event\":\"randomnumber\",\"parameters\":{\"number\":\"19\"}}",
    "resource": "serviceproviderapp",
    "response": "ok",
    "sessionId": "123456"
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type
eventstringEvent type
sessionIdstringSession id of the client this messaged is targeted to. Use "broadcast" for delivering to all connected clients
messagestringData in text format defined by Conference Service Provider application

Notifications

Authentication Session Expired

{
    "event": "notification",
    "id": "123456",
    "resource": "auth",
    "status": "expired"
}
ParameterTypeDescription
resourcestringResource type
eventstringEvent type
idstringSession id
statusstringStatus of this session

Configuration or status update

{
    "response":"ok",
    "resource":"cfg",
    "event":"notification",
    "parameters":[
        {
            "name":"Features.OperationMode",
            "value":"DUALMODE",
            "provisioned":false,
            "rebootOnChange":true
        }
    ]
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type
eventstringEvent type
namestringParameter or status name
valuestringParameter value
provisionedbooleanTrue if this parameter is configured through provisioning
rebootOnChangebooleanTrue if reboot is required to apply this change

Reboot

{
    "response":"ok",
    "resource":"cfg",
    "event":"notification",
    "parameters":[
        {
            "name":"Device.Status.Reboot",
            "value":"STARTED",
            "provisioned":false,
            "rebootOnChange":false
        }
    ]
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type
eventstringEvent type
namestringParameter name
valuestringParameter value, possible values: "REQUIRED", "PENDING", "PENDING_DELAYED", "CANCELLED", "STARTED", "STARTED_DELAYED"
provisionedbooleanTrue if this parameter is configured through provisioning
rebootOnChangebooleanTrue if reboot is required to apply this change

Merge calls

{
    "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"
}
ParameterTypeDescription
eventstringEvent type
resourcestringResource type
mergedbooleanMerge flag
callobjectList of current calls (only 1 item if call id is specified)
actionsstringEnabled call actions
codecstringCodec name
dialpadEnabledbooleanEnable/Disable dialpad for DTMF
directionstringCall direction (incoming or outgoing)
durationnumberCall duration
firstnamestringUser first name
idnumberInternal call ID
lastnamestringUser last name
localHoldbooleanLocal hold state
local_contactstringInformation about local contact
local_infostringInformation about local account
mutedbooleanMute state
phonestringAccount number
remoteHoldbooleanRemote hold state
remote_contactstringInformation about remote contact
remote_infostringInformation about the peer
server_ipstringSIP server address
statestringCurrent call state, possible values: "Calling", "Ringing", "Connected", "Failed"
statusnumberSIP response status
status_textstringStatus text
transportstringCurrent SIP transport, possible values: "TCP", "UDP", "TLS"
tunnel_ipstringConference call tunnel IP address
tunnel_typestringTunnel type, possible values: "ACME", "Dolby", "DIRECT"
typestringCall type, possible values: "PBX", "CONF"
uuidstringUnique call id

Split calls

{
    "call": [
    ],
    "event": "resource-update",
    "id": 1001,
    "merged": false,
    "resource": "call"
}
ParameterTypeDescription
resourcestringResource type
eventstringEvent type
mergedbooleanMerge flag
idnumberMerged call id
callobjectEmpty array

Software update progress

{
    "resource":"pvs",
    "response":"ok",
    "swupdate":{
        "available":true,
        "version":"3.0.0.15",
        "status":"updating",
        "error":1000,
        "progress":99
    }
}
ParameterTypeDescription
responsestringFailure or success
resourcestringResource type
swupdateobjectSoftware update information
availablebooleanTrue if the software update is available
versionstringNew software version
statusstringUpdate status, possible values: "idle", "updating", "failed", "complete", "cancelled"
errornumberError code
progressnumberProgress 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\"]}]}"
}