Set control settings

📘
Only HDL310 and HDL410 devices support this command

Allows clients to set device control settings, including the speaker treble level, the speaker bass level, and whether or not the microphone is muted.

A request body must be included with the control settings and values. If the request was successful, the request, requestId and clientId will be echoed back as a response.

If there is no request body, incorrect control settings, or an error has occurred, then the WebSocket will respond with an appropriate status code and message.

Control setting	Description
microphoneMute	When this property is true, the microphone is muted. When this property is false, the microphone is not muted.
speakerTrebleLevel	This is the speaker treble level. This is measured in whole numbers from 0 to 100.
speakerBassLevel	This is the speaker bass level. This is measured in whole numbers from 0 to 100.

Request

{
  "request": "v1/devices/commands/setControlSettings",
  "requestId": string,
  "clientId": string,
  "body": {
    "microphoneMute": boolean,
    "speakerTrebleLevel": number,
    "speakerBassLevel": number
  }
}

Response

{
  "request": "v1/devices/commands/setControlSettings",
  "requestId": string,
  "clientId": string
}

Errors

Status code	Description
10000 – Bad request	Request does not conform to the specification. The message field will include detailed information about which part of the request is incorrect.
12001 – Unsupported attributes	Request body does not conform to the specification. The message field will include detailed information about which part of the request body is incorrect.

Sample requests

1. Valid request/response with one setting in body.

Sets the microphone to unmuted. The response indicates that the change was successfully applied.

Request

{
  "request": "v1/devices/commands/setControlSettings",
  "requestId": "3abe203s-42b7-4b0b-9awaf-5c381793a192",
  "clientId": "test",
  "body": {
    "microphoneMute": false
  }
}

Response

{
  "request": "v1/devices/commands/setControlSettings",
  "requestId": "3abe203s-42b7-4b0b-9awaf-5c381793a192",
  "clientId": "test"
}

2. Valid request/response with all settings in body

Sets the microphone to unmuted, the treble level to 80, and the bass level to 30. The response indicates that the change was successfully applied.

Request

{
  "request": "v1/devices/commands/setControlSettings",
  "requestId": "3abe203s-42b7-4b0b-9awaf-5c381793a192",
  "clientId": "test",
  "body": {
    "microphoneMute": false,
    "speakerTrebleLevel": 80,
    "speakerBassLevel": 30
  }
}

Response

{
  "request": "v1/devices/commands/setControlSettings",
  "requestId": "3abe203s-42b7-4b0b-9awaf-5c381793a192",
  "clientId": "test"
}

3. Invalid request - no requestId or clientId

Request

{
  "request": "v1/devices/commands/setControlSettings",
  "requestId": "",
  "clientId": ""
}

Response

{
  "request": "v1/devices/commands/setControlSettings",
  "requestId": "",
  "clientId": "",
  "errors": [
    {
      "statusCode": 10000,
      "message": "clientId: String can't be empty or whitespace"
    },
    {
      "statusCode": 10000,
      "message": "requestId: String can't be empty or whitespace"
    }
  ]
}

4. Invalid request - bad body

This is an invalid request, since the control settings expect specific value types and ranges.

Request

{
  "request": "v1/devices/commands/setControlSettings",
  "requestId": "3abe203s-42b7-4b0b-9awaf-5c381793a192",
  "clientId": "test",
  "body": {
    "microphoneMute": "a",
    "speakerTrebleLevel": -1.2,
    "speakerBassLevel": 101
  }
}

Response

{
  "request": "v1/devices/commands/setControlSettings",
  "requestId": "3abe203s-42b7-4b0b-9awaf-5c381793a192",
  "clientId": "test",
  "errors": [
    {
      "statusCode": 12001,
      "message": "Unsupported Attributes: microphoneMute. Expected boolean, received string"
    },
    {
      "statusCode": 12001,
      "message": "Unsupported Attributes: speakerTrebleLevel. Error, speakerTrebleLevel must be a whole number"
    },
    {
      "statusCode": 12001,
      "message": "Unsupported Attributes: speakerTrebleLevel. Error, speakerTrebleLevel cannot be less than 0"
    },
    {
      "statusCode": 12001,
      "message": "Unsupported Attributes: speakerBassLevel. Error, speakerBassLevel cannot be greater than 100"
    }
  ]
}