Device operations (device)

Overview

Manages registered SIP devices by sending corresponding SIP requests.

Requests

HTTP verb Endpoint Description

POST

/rest/v1/uc/sipusers/<id>/device

Sending a command to devices


Sending a command to devices

Performed by the domain administrator.

Initiates sending a command to devices registered under the account.

A SIP request is sent to each registered device: for info and message - SIP INFO and SIP MESSAGE, otherwise SIP NOTIFY, whose Event header value is determined by the operation field or set directly by the event field.

Supported operations (operation):

  • sync - forced synchronization of autoprovision settings (Event: check-sync; reboot=false).

  • restart - device reboot (Event: check-sync; reboot=true).

  • resync - repeated synchronization (Event: resync).

  • info - send SIP INFO with the content body.

  • message - send SIP MESSAGE with the content body.

For sync and restart the Broadworks extension is used. Some device types do not support synchronization without reboot, so these commands are indistinguishable.

Table 1. Request fields
Field Type Description

operation

str

sync, restart, resync, info, or message. Required unless event is set.

event

str

Arbitrary Event header value of SIP NOTIFY. Used instead of operation.

headers

str, [str]

Additional SIP headers as Name: value. The list is joined line by line.

content

str

Request body. Passed only together with contentType.

contentType

str

Content-Type header value of the body. Passed only together with content.

Waiting for device responses is up to 10 seconds.

Request

Example request
POST /rest/v1/uc/sipusers/abcdabcd-abcd-abcd-abcd-abcdabcdabcd/device HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "operation": "sync"
}

Response

Example successful response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result": "true"
}

The result field: "true" - a response was received from at least one device; "false" - there are no registered devices or none responded; "error" - execution error, described in the errormsg field.

Example request with an arbitrary event
POST /rest/v1/uc/sipusers/abcdabcd-abcd-abcd-abcd-abcdabcdabcd/device HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "event": "check-sync",
  "headers": ["X-Custom: 1"],
  "content": "hello",
  "contentType": "text/plain"
}
Examples of failed responses
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error_code": 1506,
  "error_message": "Access denied. Only administrator is allowed to perform request.",
  "error_details": {
     "msg_code":"10038"
  }
}
{
  "error_code":1413,
  "error_message":"Invalid params. Sipuser not found: 'abcdabcd-abcd-abcd-abcd-abcdabcdabcd'"
}