├── .gitignore ├── .github └── workflows │ └── stale.yml └── README-v1.0.md /.gitignore: -------------------------------------------------------------------------------- 1 | 2 | *.code-workspace 3 | -------------------------------------------------------------------------------- /.github/workflows/stale.yml: -------------------------------------------------------------------------------- 1 | name: Stale 2 | 3 | on: 4 | issues: 5 | types: [reopened] 6 | schedule: 7 | - cron: '*/60 * * * *' 8 | 9 | jobs: 10 | stale: 11 | runs-on: ubuntu-latest 12 | env: 13 | ACTIONS_STEP_DEBUG: true 14 | steps: 15 | - uses: actions/stale@v3.0.14 16 | with: 17 | repo-token: ${{ secrets.GITHUB_TOKEN }} 18 | stale-issue-message: 'This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.' 19 | stale-pr-message: 'This pull request has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.' 20 | stale-issue-label: 'stale' 21 | stale-pr-label: 'stale' 22 | days-before-stale: 730 23 | days-before-close: 5 24 | exempt-issue-labels: 'pinned' 25 | exempt-pr-labels: 'awaiting-approval,work-in-progress' 26 | remove-stale-when-updated: true 27 | close-issue-message: 'This issue has been automatically closed because it has not had recent activity. Thank you for your contributions.' 28 | close-pr-message: 'This pull request has been automatically closed because it has not had recent activity. Thank you for your contributions.' 29 | -------------------------------------------------------------------------------- /README-v1.0.md: -------------------------------------------------------------------------------- 1 | # SwitchBot API v1.0 2 | 3 | - [SwitchBot API](#switchbot-api) 4 | - [Introduction](#introduction) 5 | - [Getting Started](#getting-started) 6 | - [Authentication](#authentication) 7 | - [Open Token](#open-token) 8 | - [Glossary](#glossary) 9 | - [API Usage](#api-usage) 10 | - [Host Domain](#host-domain) 11 | - [Sending a Request](#sending-a-request) 12 | - [Content-Type](#content-type) 13 | - [Request limit](#request-limit) 14 | - [Request Header](#request-header) 15 | - [Standard HTTP Error Codes](#standard-http-error-codes) 16 | - [Devices](#devices) 17 | - [Get device list](#get-device-list) 18 | - [Description](#description) 19 | - [Responses](#responses) 20 | - [Sample](#sample) 21 | - [Get all devices](#get-all-devices) 22 | - [Get device status](#get-device-status) 23 | - [Description](#description) 24 | - [Path parameters](#path-parameters) 25 | - [Responses](#responses) 26 | - [Sample](#sample) 27 | - [SwitchBot Meter example](#switchbot-meter-example) 28 | - [SwitchBot Curtain example](#switchbot-curtain-example) 29 | - [Send device control commands](#send-device-control-commands) 30 | - [Description](#description) 31 | - [Command set for physical devices](#command-set-for-physical-devices) 32 | - [Command set for virtual infrared remote devices](#command-set-for-virtual-infrared-remote-devices) 33 | - [Path parameters](#path-parameters) 34 | - [Request body parameters](#request-body-parameters) 35 | - [Response](#response) 36 | - [Errors](#errors) 37 | - [Sample](#sample) 38 | - [Bot example](#bot-example) 39 | - [Infrared remote device example](#infrared-remote-device-example) 40 | - [Scenes](#scenes) 41 | - [Get scene list](#get-scene-list) 42 | - [Description](#description) 43 | - [Response](#response) 44 | - [Errors](#errors) 45 | - [Sample](#sample) 46 | - [Get all scenes](#get-all-scenes) 47 | - [Execute manual scenes](#execute-manual-scenes) 48 | - [Description](#description) 49 | - [Path parameters](#path-parameters) 50 | - [Errors](#errors) 51 | - [Sample](#sample) 52 | - [Execute a scene](#execute-a-scene) 53 | - [Webhook](#webhook) 54 | - [Setup webhook](#setup-webhook) 55 | - [Description](#description) 56 | - [Request](#request) 57 | - [Request body parameters](#request-body-parameters) 58 | - [Response](#response) 59 | - [Query webhook](#query-webhook) 60 | - [Description](#description) 61 | - [Request](#request) 62 | - [Request body parameters](#request-body-parameters) 63 | - [queryUrl](#queryurl) 64 | - [queryDetails](#querydetails) 65 | - [Response](#response) 66 | - [queryUrl](#queryurl) 67 | - [queryDetails](#querydetails) 68 | - [Update webhook](#update-webhook) 69 | - [Description](#description) 70 | - [Request](#request) 71 | - [Request body parameters](#request-body-parameters) 72 | - [Response](#response) 73 | - [Delete webhook](#delete-webhook) 74 | - [Description](#description) 75 | - [Request](#request) 76 | - [Request body parameters](#request-body-parameters) 77 | - [Response](#response) 78 | - [Receive events from webhook](#receive-events-from-webhook) 79 | - [Motion Sensor](#motion-sensor) 80 | - [Contact Sensor](#contact-sensor) 81 | - [Meter](#meter) 82 | - [Meter Plus](#meter-plus) 83 | - [Lock](#lock) 84 | - [Indoor Cam](#indoor-cam) 85 | - [Pan/Tilt Cam](#pantilt-cam) 86 | - [Color Bulb](#color-bulb) 87 | - [LED Strip Light](#led-strip-light) 88 | - [Plug Mini (US)](#plug-mini-us) 89 | - [Plug Mini (JP)](#plug-mini-jp) 90 | 91 | ## Introduction 92 | This document describes a collection of SwitchBot API methods, examples, and best practices for, but not limited to, IoT hobbyists, developers, and gurus to make their own smart home programs or applications. 93 | 94 | ## Getting Started 95 | Please follow these steps, 96 | 1. Download the SwitchBot app on App Store or Google Play Store 97 | 2. Register a SwitchBot account and log in into your account 98 | 3. Generate an Open Token within the app 99 | a) Go to Profile > Preference 100 | b) Tap App Version 10 times. Developer Options will show up 101 | c) Tap Developer Options 102 | d) Tap Get Token 103 | 4. Roll up your sleeves and get your hands dirty with SwitchBot OpenAPI! 104 | 105 | ## Authentication 106 | ### Open Token 107 | The token returned from the SwitchBot Cloud is an encrypted open token that grants the user developer-level permissions. The user will be able to add, delete, edit, and look up his or her user data including profile data and data associated with the devices that have been added to the user's account. 108 | 109 | 110 | 111 | ## Glossary 112 | 113 | The following table provides definitions to the terms to be frequently mentioned in the subsequent sections. 114 | 115 | | Term | Description | 116 | | ------------- | ------------------------------------------------------------ | 117 | | Hub | Generally referred to these devices, SwitchBot Hub Model No. SwitchBot Hub S1/SwitchBot Hub Mini Model No. W0202200/SwitchBot Hub Plus Model No. SwitchBot Hub S1 | 118 | | Hub Mini | Short for SwitchBot Hub Mini Model No. W0202200 | 119 | | Hub Plus | Short for SwitchBot Hub Plus Model No. SwitchBot Hub S1 | 120 | | Bot | Short for SwitchBot Bot Model No. SwitchBot S1 | 121 | | Curtain | Short for SwitchBot Curtain Model No. W0701600 | 122 | | Plug | Short for SwitchBot Plug Model No. SP11 | 123 | | Meter | Short for SwitchBot Thermometer and Hygrometer Model No. SwitchBot MeterTH S1 | 124 | | Meter Plus (JP) | Short for SwitchBot Thermometer and Hygrometer Plus (JP) Model No. W2201500 | 125 | | Meter Plus (US) | Short for SwitchBot Thermometer and Hygrometer Plus (US) Model No. W2301500 | 126 | | Motion Sensor | Short for SwitchBot Motion Sensor Model No. W1101500 | 127 | | Contact Sensor | Short for SwitchBot Contact Sensor Model No. W1201500 | 128 | | Color Bulb | Short for SwitchBot Color Bulb Model No. W1401400 | 129 | | Smart Fan | Short for SwitchBot Smart Fan Model No. W0601100 | 130 | | Strip Light | Short for SwitchBot LED Strip Light Model No. W1701100 | 131 | | Plug Mini (US) | Short for SwitchBot Plug Mini (US) Model No. W1901400 | 132 | | Plug Mini (JP) | Short for SwitchBot Plug Mini (JP) Model No. W2001400 | 133 | | Lock | Short for SwitchBot Lock Model No. W1601700 | 134 | | Robot Vacuum Cleaner S1 | Short for SwitchBot Robot Vacuum Cleaner S1 Model No. W3011000; currently only available in Japan | 135 | | Robot Vacuum Cleaner S1 Plus | Short for SwitchBot Robot Vacuum Cleaner S1 Plus Model No. W3011010; currently only available in Japan | 136 | | Cloud Service | An SwitchBot app feature that 1. enables SwitchBot products to be discovered and communicated with third-party services voice control services, 2. allows users to create customized smart scenes and Android widgets. For BLE-based devices such as Bot and Curtain, you MUST first add a Hub/Hub Mini/Hub Plus and then enable Cloud Service on the Settings page in order to make use of the web API! | 137 | 138 | 139 | 140 | ## API Usage 141 | ### Host Domain 142 | ``` 143 | https://api.switch-bot.com 144 | ``` 145 | 146 | ### Sending a Request 147 | The following request types are supported, 148 | - GET 149 | - PUT 150 | - POST 151 | - DELETE 152 | 153 | #### Content-Type 154 | For `POST` requests, use `application/json; charset=utf8` as the `Content-Type` 155 | 156 | #### Request limit 157 | The amount of API calls per day is limited to **10000** times. Going over that limit will return "Unauthorized." 158 | 159 | ### Request Header 160 | 161 | The following parameters need to be included into the header, 162 | 163 | | Parameter | Type | Location | Required | Description | 164 | | ------------- | -------- | ------------ | ------------ | ------------------- | 165 | | Authorization | String | header | Yes | Open Token acquired | 166 | 167 | ### Standard HTTP Error Codes 168 | 169 | The following table lists the most common HTTP error response, 170 | 171 | | Code | Name | Description | 172 | | :--- | :--------------------- | :----------------------------------------------------------- | 173 | | 400 | Bad Request | The client has issued an invalid request. This is commonly used to specify validation errors in a request payload. | 174 | | 401 | Unauthorized | Authorization for the API is required, but the request has not been authenticated. | 175 | | 403 | Forbidden | The request has been authenticated but does not have appropriate permissions, or a requested resource is not found. | 176 | | 404 | Not Found | Specifies the requested path does not exist. | 177 | | 406 | Not Acceptable | The client has requested a MIME type via the Accept header for a value not supported by the server. | 178 | | 415 | Unsupported Media Type | The client has defined a contentType header that is not supported by the server. | 179 | | 422 | Unprocessable Entity | The client has made a valid request, but the server cannot process it. This is often used for APIs for which certain limits have been exceeded. | 180 | | 429 | Too Many Requests | The client has exceeded the number of requests allowed for a given time window. | 181 | | 500 | Internal Server Error | An unexpected error on the SmartThings servers has occurred. These errors should be rare. | 182 | 183 | 184 | 185 | 186 | 187 | 188 | 189 | 190 | 191 | ## Devices 192 | 193 | The devices API is used to access the properties and states of SwitchBot devices and to send control commands to those devices. 194 | 195 | ### Get device list 196 | ```http 197 | GET /v1.0/devices 198 | ``` 199 | 200 | #### Description 201 | Get a list of devices, which include physical devices and virtual infrared remote devices that have been added to the current user's account. 202 | 203 | Physical devices refer to the following SwitchBot products, 204 | - Hub 205 | - Hub Plus 206 | - Hub Mini 207 | - Bot (MUST enable Cloud Service first) 208 | - Curtain (MUST enable Cloud Service first) 209 | - Plug 210 | - Meter (MUST enable Cloud Service first) 211 | - Motion Sensor (MUST enable Cloud Service first) 212 | - Contact Sensor (MUST enable Cloud Service first) 213 | - Color Bulb 214 | - Humidifier 215 | - Smart Fan 216 | - Strip Light 217 | - Plug Mini (US) 218 | - Plug Mini (JP) 219 | - Lock 220 | - Meter Plus (JP) (MUST enable Cloud Service first) 221 | - Meter Plus (US) (MUST enable Cloud Service first) 222 | - `new` Robot Vacuum Cleaner S1 223 | - `new` Robot Vacuum Cleaner S1 Plus 224 | 225 | Virtual infrared remote devices refer to virtual devices that are used to simulate infrared signals of a home appliance remote control. A SwitchBot Hub Plus / Hub Mini is required in order to be able to create these virtual devices within the app. The types of appliances supported include, 226 | - Air Conditioner 227 | - TV 228 | - Light 229 | - IPTV/Streamer 230 | - Set Top Box 231 | - DVD 232 | - Fan 233 | - Projector 234 | - Camera 235 | - Air Purifier 236 | - Speaker 237 | - Water Heater 238 | - Vacuum Cleaner 239 | - Others 240 | 241 | #### Responses 242 | 243 | The response is basically a JSON object, which contains the following properties, 244 | 245 | | Key Name | Value Type | 246 | | ---------- | ------------ | 247 | | statusCode | Integer | 248 | | message | String | 249 | | body | Object | 250 | 251 | The body object contains the following properties, 252 | 253 | | Key Name | Value Type | Description | 254 | | ------------------ | --------------------- | ----------------------------------------- | 255 | | deviceList | Array | a list of physical devices | 256 | | infraredRemoteList | Array | a list of virtual infrared remote devices | 257 | 258 | The deviceList array contains a list of objects with the following key-value attributes, 259 | 260 | | Key | Value Type | Description | 261 | | ------------------ | --------------- | ------------------------------------------------------------ | 262 | | deviceId | String | device ID | 263 | | deviceName | String | device name | 264 | | deviceType | String | device type | 265 | | enableCloudService | Boolean | determines if Cloud Service is enabled or not for the current device | 266 | | hubDeviceId | String | device's parent Hub ID | 267 | | curtainDevicesIds | Array | only available for Curtain devices. a list of Curtain device IDs such that the Curtain devices are being paired or grouped | 268 | | calibrate | Boolean | only available for Curtain/Lock devices. determines if the open position and the close position of a device have been properly calibrated or not | 269 | | group | Boolean | only available for Curtain devices. determines if a Curtain is paired with or grouped with another Curtain or not | 270 | | master | Boolean | only available for Curtain devices. determines if a Curtain is the master device or not when paired with or grouped with another Curtain | 271 | | openDirection | String | only available for Curtain devices. the opening direction of a Curtain | 272 | 273 | The infraredRemoteList array contains a list of objects with the following key-value attributes, 274 | | Key | Value Type | Description | 275 | | ----------- | ---------- | ----------------------------- | 276 | | deviceId | String | device ID | 277 | | deviceName | String | device name | 278 | | remoteType | String | device type | 279 | | hubDeviceId | String | remote device's parent Hub ID | 280 | 281 | The response may contain the following codes and messages, 282 | 283 | | Status Code | Body Content | Message | Description | 284 | | ----------- | ------------ | ----------- | ----------- | 285 | | 100 | Device list object | success | Returns an object that contains two device lists | 286 | | n/a | n/a | Unauthorized | Http 401 Error. User permission is denied due to invalid token. | 287 | | 190 | n/a | System error | Device internal error due to device states not synchronized with server | 288 | 289 | #### Sample 290 | 291 | ##### Get all devices 292 | 293 | Request 294 | 295 | ```http 296 | GET https://api.switch-bot.com/v1.0/devices 297 | ``` 298 | 299 | Response 300 | 301 | ```js 302 | { 303 |     "statusCode": 100, 304 |     "body": { 305 |         "deviceList": [ 306 |             { 307 |                 "deviceId": "500291B269BE", 308 |                 "deviceName": "Living Room Humidifier", 309 |                 "deviceType": "Humidifier", 310 |                 "enableCloudService": true, 311 |                 "hubDeviceId": "000000000000" 312 |             } 313 |         ], 314 |         "infraredRemoteList": [ 315 |             { 316 |                 "deviceId": "02-202008110034-13", 317 |                 "deviceName": "Living Room TV", 318 |                 "remoteType": "TV", 319 |                 "hubDeviceId": "FA7310762361" 320 |             } 321 |         ] 322 |     }, 323 |     "message": "success" 324 | } 325 | ``` 326 | 327 | 328 | ### Get device status 329 | ```http 330 | GET /v1.0/devices/{deviceId}/status 331 | ``` 332 | 333 | #### Description 334 | Get the status of a physical device that has been added to the current user's account. 335 | 336 | Physical devices refer to the following SwitchBot products, 337 | 338 | - Bot 339 | - Plug 340 | - Curtain 341 | - Meter 342 | - Motion Sensor 343 | - Contact Sensor 344 | - Color Bulb 345 | - Humidifier 346 | - Smart Fan 347 | - Strip Light 348 | - Plug Mini (US) 349 | - Plug Mini (JP) 350 | - Lock 351 | - Meter Plus (JP) 352 | - Meter Plus (US) 353 | - `new` Robot Vacuum Cleaner S1 354 | - `new` Robot Vacuum Cleaner S1 Plus 355 | 356 | #### Path parameters 357 | 358 | | Name | Type | Required | Description | 359 | | -------- | ------ | -------- | ----------- | 360 | | deviceId | String | Yes | device ID | 361 | 362 | #### Responses 363 | The response is basically a JSON object, which contains the following properties, 364 | 365 | | Key Name | Value Type | 366 | | ---------- | ------------ | 367 | | statusCode | Integer | 368 | | message | String | 369 | | body | Object | 370 | 371 | body object contains the following properties, 372 | | Key | Value Type | Used by Products | Description | 373 | | ---------------------- | ---------- | ------------------------------------------------------------ | ------------------------------------------------------------ | 374 | | deviceId | String | All | device ID | 375 | | deviceType | String | All | device type | 376 | | hubDeviceId | String | All | device's parent Hub ID | 377 | | power | String | Bot/Plug/Humidifier/Color Bulb/Strip Light/Plug Mini | ON/OFF state | 378 | | humidity | Integer | Meter/Meter Plus/Humidifier | humidity percentage | 379 | | temperature | Float | Meter/Meter Plus/Humidifier | temperature in celsius | 380 | | nebulizationEfficiency | Integer | Humidifier | atomization efficiency % | 381 | | auto | Boolean | Humidifier | determines if a Humidifier is in Auto Mode or not | 382 | | childLock | Boolean | Humidifier | determines if a Humidifier's safety lock is on or not | 383 | | sound | Boolean | Humidifier | determines if a Humidifier is muted or not | 384 | | calibrate | Boolean | Curtain/Lock | determines if a device has been calibrated or not | 385 | | group | Boolean | Curtain | determines if a Curtain is paired with or grouped with another Curtain or not | 386 | | moving | Boolean | Curtain | determines if a Curtain is moving or not | 387 | | slidePosition | Integer | Curtain | the percentage of the distance between the calibrated open position and closed position that Curtain has traversed | 388 | | mode | Integer | Smart Fan | fan mode | 389 | | speed | Integer | Smart Fan | fan speed | 390 | | shaking | Boolean | Smart Fan | determines if the fan is swinging or not | 391 | | shakeCenter | Integer | Smart Fan | the fan's swing direciton | 392 | | shakeRange | Integer | Smart Fan | the fan's swing range, 0~120° | 393 | | moveDetected | Boolean | Motion Sensor/Contact Sensor | determines if motion is detected | 394 | | brightness | String | Motion Sensor/Contact Sensor | if the ambient environment is bright or dim | 395 | | openState | String | Contact Sensor | open/close/timeOutNotClose | 396 | | brightness | Integer | Color Bulb/Strip Light | the brightness value, range from 1 to 100 | 397 | | color | String | Color Bulb/Strip Light | the color value, RGB "255:255:255" | 398 | | colorTemperature | Integer | Color Bulb | the color temperature value, range from 2700 to 6500 | 399 | | lackWater | Boolean | Humidifier | determines if the water tank is empty or not | 400 | | voltage | Integer | Plug Mini | Current voltage of the device (Unit: V) | 401 | | weight | Integer | Plug Mini | the power consumption of the device for the day (Unit: W/min) | 402 | | electricityOfDay | Integer | Plug Mini | How long the device has been used for the day (Unit: min) | 403 | | electricCurrent | Integer | Plug Mini | current of the device (Unit: A) at the moment | 404 | | lockState | String | Lock | determines if the lock is locked or not | 405 | | doorState | String | Lock | determines if the door is closed or not | 406 | | workingStatus | String | Robot Vacuum Cleaner S1/ S1 Plus | the working status of the device, e.g. Cleaning, Paused | 407 | | onlineStatus | String | Robot Vacuum Cleaner S1/ S1 Plus | determines if the device is online or offline | 408 | | battery | Integer | Robot Vacuum Cleaner S1/ S1 Plus | the battery level | 409 | 410 | The reponses may contain the following codes and message, 411 | 412 | | Status Code | Body Content | Message | Description | 413 | | ----------- | ------------------ | ------------ | ----------- | 414 | | 100 | Device list object | success | Returns an object that contains two device lists | 415 | | n/a | n/a | Unauthorized | Http 401 Error. User permission is denied due to invalid token. | 416 | | 190 | n/a | System error | Device internal error due to device states not synchronized with server | 417 | 418 | #### Sample 419 | 420 | ##### SwitchBot Meter example 421 | 422 | Request the status of a SwitchBot Thermometer and Hygrometer 423 | 424 | Request 425 | 426 | ```http 427 | GET https://api.switch-bot.com/v1.0/devices/C271111EC0AB/status 428 | ``` 429 | 430 | Response 431 | 432 | 433 | ```js 434 | { 435 |     "statusCode": 100, 436 |     "body": { 437 |         "deviceId": "C271111EC0AB", 438 |         "deviceType": "Meter", 439 |         "hubDeviceId": "FA7310762361", 440 |         "humidity": 52, 441 |         "temperature": 26.1 442 |     }, 443 |     "message": "success" 444 | } 445 | ``` 446 | 447 | ##### SwitchBot Curtain example 448 | 449 | Request the status of a SwitchBot Curtain 450 | 451 | Request 452 | 453 | ```http 454 | GET https://api.switch-bot.com/v1.0/devices/E2F6032048AB/status 455 | ``` 456 | 457 | Response 458 | 459 | 460 | ```js 461 | { 462 | "statusCode": 100, 463 | "body": { 464 | "deviceId": "E2F6032048AB", 465 | "deviceType": "Curtain", 466 | "hubDeviceId": "FA7310762361", 467 | "calibrate": true, 468 | "group": false, 469 | "moving": false, 470 | "slidePosition": 0 471 | }, 472 | "message": "success" 473 | } 474 | ``` 475 | 476 | 477 | 478 | ### Send device control commands 479 | 480 | ```http 481 | POST /v1.0/devices/{deviceId}/commands 482 | ``` 483 | 484 | #### Description 485 | 486 | Send control commands to physical devices and virtual infrared remote devices. 487 | 488 | #### Command set for physical devices 489 | 490 | The table below describes all the available commands for physical devices, 491 | 492 | | deviceType | commandType | Command | command parameter | Description | 493 | | ---- | ---- | ---- | ---- | ---- | 494 | | Bot | command | turnOff | default | set to OFF state | 495 | | Bot | command | turnOn | default | set to ON state | 496 | | Bot | command | press | default | trigger press | 497 | | Plug | command | turnOn | default | set to ON state | 498 | | Plug | command | turnOff | default | set to OFF state | 499 | | Curtain | command | setPosition | index0,mode0,position0
e.g. `0,ff,80` | mode: 0 (Performance Mode), 1 (Silent Mode), ff (default mode)
position: 0~100 (0 means opened, 100 means closed) | 500 | | Curtain | command | turnOff | default | equivalent to set position to 100 | 501 | | Curtain | command | turnOn | default | equivalent to set position to 0 | 502 | | Humidifier | command | turnOff | default | set to OFF state | 503 | | Humidifier | command | turnOn | default | set to ON state | 504 | | Humidifier | command |setMode | `auto` or `101` or
`102` or `103` or `{0~100}` | auto, set to Auto Mode,
101, set atomization efficiency to 34%,
102, set atomization efficiency to 67%,
103, set atomization efficiency to 100% | 505 | | Smart Fan | command |turnOn | default | set to ON state | 506 | | Smart Fan | command |turnOff | default | set to OFF state | 507 | | Smart Fan | command | setAllStatus | power,fanMode,
fanSpeed,shakeRange
e.g. `on,1,1,60` | power: off/on,
fanMode: 1/2,
fanSpeed: 1/2/3/4,
shakeRange: 0~120
fanMode: 1 (Standard), 2 (Natural) | 508 | | Color Bulb | command |turnOn | default | set to ON state | 509 | | Color Bulb | command |turnOff | default | set to OFF state | 510 | | Color Bulb | command |toggle | default | toggle state | 511 | | Color Bulb | command |setBrightness | `{1-100}` | set brightness | 512 | | Color Bulb | command |setColor | `"{0-255}:{0-255}:{0-255}"` | set RGB color value | 513 | | Color Bulb | command |setColorTemperature | `{2700-6500}` | set color temperature | 514 | | Strip Light | command |turnOn | default | set to ON state | 515 | | Strip Light | command |turnOff | default | set to OFF state | 516 | | Strip Light | command |toggle | default | toggle state | 517 | | Strip Light | command |setBrightness | `{1-100}` | set brightness | 518 | | Strip Light | command |setColor | `"{0-255}:{0-255}:{0-255}"` | set RGB color value | 519 | | Plug Mini (US/JP) | command | turnOn | default | set to ON state | 520 | | Plug Mini (US/JP) | command | turnOff | default | set to OFF state | 521 | | Plug Mini (US/JP) | command | toggle | default | toggle state | 522 | | Robot Vacuum Cleaner S1 | command | start | default | start vacuuming | 523 | | Robot Vacuum Cleaner S1 | command | stop | default | stop vacuuming | 524 | | Robot Vacuum Cleaner S1 | command | dock | default | return to charging dock | 525 | | Robot Vacuum Cleaner S1 | command | PowLevel | `{0-3}` | set suction power level: 0 (Quiet), 1 (Standard), 2 (Strong), 3 (MAX) | 526 | | Robot Vacuum Cleaner S1 Plus | command | start | default | start vacuuming | 527 | | Robot Vacuum Cleaner S1 Plus | command | stop | default | stop vacuuming | 528 | | Robot Vacuum Cleaner S1 Plus | command | dock | default | return to charging dock | 529 | | Robot Vacuum Cleaner S1 Plus | command | PowLevel | `{0-3}` | set suction power level: 0 (Quiet), 1 (Standard), 2 (Strong), 3 (MAX) | 530 | 531 | #### Command set for virtual infrared remote devices 532 | 533 | The table below describes all the available commands for virtual infrared remote devices, 534 | 535 | | deviceType | commandType | Command | command parameter | Description | 536 | | -------------------------------------- | ----------- | -------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | 537 | | All home appliance types except Others | "" | turnOn | default | every home appliance can be turned on by default | 538 | | All home appliance types except Others | command | turnOff | default | every home appliance can be turned off by default | 539 | | Others | `customize` | {user-defined button name} | default | all user-defined buttons must be configured with commandType=customize | 540 | | Air Conditioner | command | setAll | {temperature},{mode},{fan speed},{power state}
e.g. `26,1,3,on` | the unit of temperature is in celsius;
modes include 1 (auto), 2 (cool), 3 (dry), 4 (fan), 5 (heat);
fan speed includes 1 (auto), 2 (low), 3 (medium), 4 (high);
power state includes on and off | 541 | | | | | | | 542 | | TV, IPTV/Streamer, Set Top Box | command | SetChannel | {channel number}, e.g. 15 | set the TV channel to switch to || | command | setMute | default | mute/unmute | 543 | | | command | volumeAdd | default | volume up | 544 | | | command | volumeSub | default | volume down | 545 | | | command | channelAdd | default | next channel | 546 | | | command | channelSub | default | previous channel | 547 | | DVD, Speaker | command | setMute | default | mute/unmute | 548 | | | command | FastForward | default | fast forward | 549 | | | command | Rewind | default | rewind | 550 | | | command | Next | default | next track | 551 | | | command | Previous | default | last track | 552 | | | command | Pause | default | pause | 553 | | | command | Play | default | play/resume | 554 | | | command | Stop | default | stop | 555 | | Speaker | command | volumeAdd | default | volume up | 556 | | | command | volumeSub | default | volume down | 557 | | Fan | command | swing | default | swing | 558 | | | command | timer | default | set timer | 559 | | | command | lowSpeed | default | set fan speed to low | 560 | | | command | middleSpeed | default | set fan speed to medium | 561 | | | command | highSpeed | default | set fan speed to high | 562 | | Light | command | brightnessUp | default | brightness up | 563 | | | command | brightnessDown | default | brightness down | 564 | 565 | > Note: Most of the devices support `turnOn` or `turnOff`, which are case-sensitive. For infrared remote devices, when you have created customized buttons, you must set `commandType` to `customize`, otherwise the command will not work. `command` needs to be set to the name of the customized button. 566 | 567 | 568 | 569 | #### Path parameters 570 | 571 | | Name | Type | Required | Description | 572 | | -------- | ------ | -------- | ----------- | 573 | | deviceId | String | Yes | device ID | 574 | 575 | #### Request body parameters 576 | 577 | | Name | Type | Required | Description | 578 | | ----------- | ------ | -------- | ----------------------------------------------------------- | 579 | | command | String | Yes | the name of the command | 580 | | parameter | String | No | some commands require parameters, such as `SetChannel` | 581 | | commandType | String | No | for customized buttons, this needs to be set to `customzie` | 582 | 583 | #### Response 584 | 585 | The response is basically a JSON object, which contains the following properties, 586 | 587 | | Key Name | Value Type | 588 | | ---------- | ------------ | 589 | | statusCode | Integer | 590 | | message | String | 591 | | body | Object | 592 | 593 | #### Errors 594 | 595 | | Error code/message | Description | 596 | | --------------------------- | ------------------------------------------------------------ | 597 | | {"message": "Unauthorized"} | Http 401 Error. User permission is denied due to invalid token. | 598 | | 151 | device type error | 599 | | 152 | device not found | 600 | | 160 | command is not supported | 601 | | 161 | device offline | 602 | | 171 | hub device is offline | 603 | | 190 | Device internal error due to device states not synchronized with server. Or command format is invalid. | 604 | 605 | #### Sample 606 | 607 | ##### Bot example 608 | 609 | Turn a Bot on 610 | 611 | Request 612 | 613 | ```http 614 | POST https://api.switch-bot.com/v1.0/devices/210/commands 615 | ``` 616 | 617 | ```js 618 | { 619 | "command": "turnOn", 620 | "parameter": "default", 621 | "commandType": "command" 622 | } 623 | ``` 624 | 625 | Response 626 | 627 | ```js 628 | { 629 | "statusCode": 100, 630 | "body": {}, 631 | "message": "success" 632 | } 633 | ``` 634 | 635 | 636 | 637 | Set the color value of a Color Bulb 638 | Request 639 | 640 | ```http 641 | POST https://api.switch-bot.com/v1.0/devices/84F70353A411/commands 642 | ``` 643 | 644 | ```js 645 | { 646 | "command": "setColor", 647 | "parameter": "122:80:20", // yellow 648 | "commandType": "command" 649 | } 650 | ``` 651 | 652 | Response 653 | 654 | ```js 655 | { 656 | "statusCode": 100, 657 | "body": {}, 658 | "message": "success" 659 | } 660 | ``` 661 | 662 | 663 | ##### Infrared remote device example 664 | 665 | Set an Air Conditioner 666 | 667 | Request 668 | 669 | ```http 670 | POST https://api.switch-bot.com/v1.0/devices/02-202007201626-70/commands 671 | ``` 672 | 673 | ```js 674 | { 675 | "command": "setAll", 676 | "parameter": "26,1,3,on", 677 | "commandType": "command" 678 | } 679 | ``` 680 | 681 | Response 682 | 683 | ```js 684 | { 685 | "statusCode": 100, 686 | "body": {}, 687 | "message": "success" 688 | } 689 | ``` 690 | 691 | 692 | 693 | Trigger a customized button 694 | 695 | Request 696 | 697 | ```http 698 | POST https://api.switch-bot.com/v1.0/devices/02-202007201626-10/commands 699 | ``` 700 | 701 | ```js 702 | { 703 | "command": "ボタン", // the name of the customized button 704 | "parameter": "default", 705 | "commandType": "customize" 706 | } 707 | ``` 708 | 709 | Response 710 | 711 | ```js 712 | { 713 | "statusCode": 100, 714 | "body": {}, 715 | "message": "success" 716 | } 717 | ``` 718 | 719 | 720 | 721 | ## Scenes 722 | 723 | The scenes API is used to access the smart scenes created by a user and to execute manual scenes. 724 | 725 | ### Get scene list 726 | 727 | ```http 728 | GET /v1.0/scenes 729 | ``` 730 | 731 | #### Description 732 | 733 | Get a list of manual scenes created by the current user. 734 | 735 | #### Response 736 | 737 | The response is basically a JSON object, which contains the following properties, 738 | 739 | | Key Name | Value Type | 740 | | ---------- | ------------ | 741 | | statusCode | Integer | 742 | | message | String | 743 | | body | Object | 744 | 745 | The body object contains a list of objects, which has the following properties, 746 | 747 | | Key | Type | Description | 748 | | --------- | ------ | -------------- | 749 | | sceneId | String | a scene's ID | 750 | | sceneName | String | a scene's name | 751 | 752 | #### Errors 753 | 754 | | Error code/message | Description | 755 | | --------------------------- | ------------------------------------------------------------ | 756 | | {"message": "Unauthorized"} | Http 401 Error. User permission is denied due to invalid token. | 757 | | 190 | Device internal error due to device states not synchronized with server | 758 | 759 | #### Sample 760 | 761 | ##### Get all scenes 762 | 763 | Request 764 | 765 | ```http 766 | GET https://api.switch-bot.com/v1.0/scenes 767 | ``` 768 | 769 | Response 770 | 771 | ```js 772 | { 773 | "statusCode": 100, 774 | "body": [ 775 | { 776 | "sceneId": "T02-20200804130110", 777 | "sceneName": "Close Office Devices" 778 | }, 779 | { 780 | "sceneId": "T02-202009221414-48924101", 781 | "sceneName": "Set Office AC to 25" 782 | }, 783 | { 784 | "sceneId": "T02-202011051830-39363561", 785 | "sceneName": "Set Bedroom to 24" 786 | }, 787 | { 788 | "sceneId": "T02-202011051831-82928991", 789 | "sceneName": "Turn off home devices" 790 | }, 791 | { 792 | "sceneId": "T02-202011062059-26364981", 793 | "sceneName": "Set Bedroom to 26 degree" 794 | } 795 | ], 796 | "message": "success" 797 | } 798 | ``` 799 | 800 | ### Execute manual scenes 801 | 802 | ```http 803 | POST /v1.0/scenes/{sceneId}/execute 804 | ``` 805 | 806 | #### Description 807 | 808 | Sends a request to execute a manual scene. 809 | 810 | #### Path parameters 811 | 812 | | Name | Type | Required | Description | 813 | | ------- | ------ | -------- | ----------- | 814 | | sceneId | String | Yes | scene ID | 815 | 816 | The response is basically a JSON object, which contains the following properties, 817 | 818 | | Key Name | Value Type | 819 | | ---------- | ------------ | 820 | | statusCode | Integer | 821 | | message | String | 822 | | body | Object | 823 | 824 | #### Errors 825 | 826 | | Error code/message | Description | 827 | | --------------------------- | ------------------------------------------------------------ | 828 | | {"message": "Unauthorized"} | Http 401 Error. User permission is denied due to invalid token. | 829 | | 190 | Device internal error due to device states not synchronized with server | 830 | 831 | #### Sample 832 | 833 | ##### Execute a scene 834 | 835 | Request 836 | 837 | ```http 838 | POST https://api.switch-bot.com/v1.0/scenes/T02-202009221414-48924101/execute 839 | ``` 840 | 841 | Response 842 | 843 | ```js 844 | { 845 |     "statusCode": 100, 846 |     "body": {}, 847 |     "message": "success" 848 | } 849 | ``` 850 | 851 | ## Webhook 852 | 853 | ### Configure webhook 854 | 855 | #### Description 856 | Configure the url that all the webhook events will be sent to 857 | 858 | #### Request 859 | ```http 860 | POST https://api.switch-bot.com/v1.0/webhook/setupWebhook 861 | ``` 862 | 863 | ##### Request body parameters 864 | | Key Name | Value Type | Description | 865 | | ---------- | ---------- | ----------------------------------------------------- | 866 | | action | String | the type of actions | 867 | | url | String | the url where all the events are sent to | 868 | | deviceList | String | the list of device ids, currently only supports "ALL" | 869 | 870 | Head 871 | 872 | ```js 873 | { 874 | "Content-type":"application/json", 875 | "Authorization":your_token // enter your API token 876 | } 877 | ``` 878 | 879 | Body 880 | 881 | ```js 882 | { 883 | "action":"setupWebhook", 884 | "url":url1, // enter your url 885 | "deviceList":"ALL" 886 | } 887 | ``` 888 | 889 | #### Response 890 | 891 | Sample 892 | 893 | ```js 894 | { 895 | "statusCode": 100, 896 | "body": {}, 897 | "message": "" 898 | } 899 | ``` 900 | 901 | ### Get webhook configuration 902 | #### Description 903 | Get the current configuration info of the webhook 904 | 905 | #### Request 906 | ```http 907 | POST https://api.switch-bot.com/v1.0/webhook/queryWebhook 908 | ``` 909 | 910 | ##### Request body parameters 911 | 912 | | Key Name | Value Type | Description | 913 | | -------- | ---------- | ------------------------------------------------------------ | 914 | | action | String | the type of actions, currently supports "queryUrl", "queryDetails" | 915 | | url | String | the url where all the events are sent to. you need to specify the url when using queryDetails | 916 | 917 | ##### queryUrl 918 | 919 | Head 920 | 921 | ```js 922 | { 923 | "Content-type":"application/json", 924 | "Authorization":your_token // enter your API token 925 | } 926 | ``` 927 | 928 | Body 929 | 930 | ```js 931 | { 932 | "action": "queryUrl" 933 | } 934 | ``` 935 | 936 | ##### queryDetails 937 | Head 938 | 939 | ```js 940 | { 941 | "Content-type":"application/json", 942 | "Authorization":your_token // enter your API token 943 | } 944 | ``` 945 | 946 | Body 947 | 948 | ```js 949 | { 950 | "action": "queryDetails", 951 | "urls":[url1] // get infos of a url 952 | } 953 | ``` 954 | 955 | 956 | #### Response 957 | 958 | ##### queryUrl 959 | 960 | ```js 961 | { 962 | "statusCode": 100, 963 | "body": { 964 | "urls": [url1] // the target url 965 | }, 966 | "message": "" 967 | } 968 | ``` 969 | 970 | ##### queryDetails 971 | ```js 972 | { 973 | "statusCode": 100, 974 | "body": [ 975 | { 976 | "url":url1, 977 | "createTime":123456, 978 | "lastUpdateTime":123456, 979 | "deviceList": "ALL", 980 | "enable":true 981 | } 982 | ], 983 | "message": "" 984 | } 985 | ``` 986 | ### Update webhook configuration 987 | #### Description 988 | Update the configuration of the webhook 989 | 990 | #### Request 991 | ```http 992 | POST https://api.switch-bot.com/v1.0/webhook/queryWebhook 993 | ``` 994 | 995 | ##### Request body parameters 996 | | Key Name | Value Type | Description | 997 | | -------- | ---------- | ------------------------------------------------------------ | 998 | | action | String | the type of actions | 999 | | config | Object | the configuration details you want to update. you can change the current url or enable/disable the webhook. refer to the example below | 1000 | 1001 | Head 1002 | 1003 | ```js 1004 | { 1005 | "Content-type":"application/json", 1006 | "Authorization":your_token // enter your API token 1007 | } 1008 | ``` 1009 | 1010 | Body 1011 | 1012 | ```js 1013 | { 1014 | "action": "updateWebhook", 1015 | "config":{ 1016 | "url":url1, 1017 | "enable":true 1018 | } 1019 | } 1020 | ``` 1021 | 1022 | #### Response 1023 | ```js 1024 | { 1025 | "statusCode": 100, 1026 | "body": {}, 1027 | "message": "" 1028 | } 1029 | ``` 1030 | 1031 | ### Delete webhook 1032 | #### Description 1033 | Delete the configuration of the webhook 1034 | 1035 | #### Request 1036 | ```http 1037 | POST https://api.switch-bot.com/v1.0/webhook/deleteWebhook 1038 | ``` 1039 | 1040 | ##### Request body parameters 1041 | | Key Name | Value Type | Description | 1042 | | -------- | ---------- | ------------------------------------------------------------ | 1043 | | action | String | the type of actions | 1044 | | url | String | the url where all the events are sent to | 1045 | 1046 | Head 1047 | 1048 | ```js 1049 | { 1050 | "Content-type":"application/json", 1051 | "Authorization":your_token // enter your API token 1052 | } 1053 | ``` 1054 | 1055 | Body 1056 | 1057 | ```js 1058 | { 1059 | "action": "deleteWebhook", 1060 | "url":url1 1061 | } 1062 | ``` 1063 | 1064 | #### Response 1065 | ```js 1066 | { 1067 | "statusCode": 100, 1068 | "body": {}, 1069 | "message": "" 1070 | } 1071 | ``` 1072 | 1073 | 1074 | 1075 | ### Receive events from webhook 1076 | 1077 | When an event gets triggered, SwitchBot server will send a `POST` request to the url you have configured. Refer to the table below for a list of products that support webhook. 1078 | 1079 | | Device Type | **Product** | 1080 | | ------------ | --------------- | 1081 | | WoPresence | Motion Sensor | 1082 | | WoContact | Contact Sensor | 1083 | | WoLock | Lock | 1084 | | WoCamera | Indoor Cam | 1085 | | WoPanTiltCam | Pan/Tilt Cam | 1086 | | WoBulb | Color Bulb | 1087 | | WoStrip | LED Strip Light | 1088 | | WoPlugUS | Plug Mini (US) | 1089 | | WoPlugJP | Plug Mini (JP) | 1090 | | WoMeter | Meter | 1091 | | WoMeterPlus | Meter Plus | 1092 | 1093 | #### Motion Sensor 1094 | 1095 | | Key Name | Value Type | Description | 1096 | | -------------- | ---------- | ------------------------------------------------------------ | 1097 | | eventType | String | the type of events | 1098 | | eventVersion | String | the current event version | 1099 | | context | Object | the detail info of the event | 1100 | | deviceType | String | the type of the device | 1101 | | deviceMac | String | the MAC address of the device | 1102 | | detectionState | String | the motion state of the device, "DETECTED" stands for motion is detected; "NOT_DETECTED" stands for motion has not been detected for some time | 1103 | | timeOfSample | Long | the time stamp when the event is sent | 1104 | 1105 | ```js 1106 | { 1107 | "eventType": "changeReport", 1108 | "eventVersion": "1", 1109 | "context": { 1110 | "deviceType": "WoPresence", 1111 | "deviceMac": DEVICE_MAC_ADDR, 1112 | "detectionState": "NOT_DETECTED", 1113 | "timeOfSample": 123456789 1114 | } 1115 | } 1116 | ``` 1117 | 1118 | #### Contact Sensor 1119 | 1120 | | Key Name | Value Type | Description | 1121 | | -------------- | ---------- | ------------------------------------------------------------ | 1122 | | eventType | String | the type of events | 1123 | | eventVersion | String | the current event version | 1124 | | context | Object | the detail info of the event | 1125 | | deviceType | String | the type of the device | 1126 | | deviceMac | String | the MAC address of the device | 1127 | | detectionState | String | the motion state of the device, "DETECTED" stands for motion is detected; "NOT_DETECTED" stands for motion has not been detected for some time | 1128 | | doorMode | String | when the enter or exit mode gets triggered, "IN_DOOR" or "OUT_DOOR" is returned | 1129 | | brightness | String | the level of brightness, can be "bright" or "dim" | 1130 | | openState | String | the state of the contact sensor, can be "open" or "close" or "timeOutNotClose" | 1131 | | timeOfSample | Long | the time stamp when the event is sent | 1132 | 1133 | ```js 1134 | { 1135 | "eventType": "changeReport", 1136 | "eventVersion": "1", 1137 | "context": { 1138 | "deviceType": "WoContact", 1139 | "deviceMac": DEVICE_MAC_ADDR, 1140 | "detectionState": "NOT_DETECTED", 1141 | "doorMode":"OUT_DOOR", 1142 | "brightness": "dim", 1143 | "openState": "open", 1144 | "timeOfSample": 123456789 1145 | } 1146 | } 1147 | ``` 1148 | 1149 | #### Meter 1150 | 1151 | | Key Name | Value Type | Description | 1152 | | ------------ | ---------- | ------------------------------------------ | 1153 | | eventType | String | the type of events | 1154 | | eventVersion | String | the current event version | 1155 | | context | Object | the detail info of the event | 1156 | | deviceType | String | the type of the device | 1157 | | deviceMac | String | the MAC address of the device | 1158 | | temperature | Float | the current temperature reading | 1159 | | scale | String | the current temperature unit being used | 1160 | | humidity | Integer | the current humidity reading in percentage | 1161 | | timeOfSample | Long | the time stamp when the event is sent | 1162 | 1163 | ```js 1164 | { 1165 | "eventType": "changeReport", 1166 | "eventVersion": "1", 1167 | "context": { 1168 | "deviceType": "WoMeter", 1169 | "deviceMac": DEVICE_MAC_ADDR, 1170 | "temperature": 22.5, 1171 | "scale": "CELSIUS", 1172 | "humidity": 31, 1173 | "timeOfSample": 123456789 1174 | } 1175 | } 1176 | ``` 1177 | 1178 | #### Meter Plus 1179 | 1180 | | Key Name | Value Type | Description | 1181 | | ------------ | ---------- | ------------------------------------------ | 1182 | | eventType | String | the type of events | 1183 | | eventVersion | String | the current event version | 1184 | | context | Object | the detail info of the event | 1185 | | deviceType | String | the type of the device | 1186 | | deviceMac | String | the MAC address of the device | 1187 | | temperature | Float | the current temperature reading | 1188 | | scale | String | the current temperature unit being used | 1189 | | humidity | Integer | the current humidity reading in percentage | 1190 | | timeOfSample | Long | the time stamp when the event is sent | 1191 | 1192 | ```js 1193 | { 1194 | "eventType": "changeReport", 1195 | "eventVersion": "1", 1196 | "context": { 1197 | "deviceType": "WoMeter", 1198 | "deviceMac": DEVICE_MAC_ADDR, 1199 | "temperature": 22.5, 1200 | "scale": "CELSIUS", 1201 | "humidity": 31, 1202 | "timeOfSample": 123456789 1203 | } 1204 | } 1205 | ``` 1206 | 1207 | #### Lock 1208 | 1209 | | Key Name | Value Type | Description | 1210 | | ------------ | ---------- | ------------------------------------------------------------ | 1211 | | eventType | String | the type of events | 1212 | | eventVersion | String | the current event version | 1213 | | context | Object | the detail info of the event | 1214 | | deviceType | String | the type of the device | 1215 | | deviceMac | String | the MAC address of the device | 1216 | | lockState | String | the state of the device, "LOCKED" stands for the motor is rotated to locking position; "UNLOCKED" stands for the motor is rotated to unlocking position; "JAMMED" stands for the motor is jammed while rotating | 1217 | | timeOfSample | Long | the time stamp when the event is sent | 1218 | 1219 | ```js 1220 | { 1221 | "eventType": "changeReport", 1222 | "eventVersion": "1", 1223 | "context": { 1224 | "deviceType": "WoLock", 1225 | "deviceMac": DEVICE_MAC_ADDR, 1226 | "lockState": "LOCKED", 1227 | "timeOfSample": 123456789 1228 | } 1229 | } 1230 | ``` 1231 | 1232 | #### Indoor Cam 1233 | 1234 | | Key Name | Value Type | Description | 1235 | | -------------- | ---------- | ------------------------------------------------------------ | 1236 | | eventType | String | the type of events | 1237 | | eventVersion | String | the current event version | 1238 | | context | Object | the detail info of the event | 1239 | | deviceType | String | the type of the device | 1240 | | deviceMac | String | the MAC address of the device | 1241 | | detectionState | String | the detection state of the device, "DETECTED" stands for motion is detected | 1242 | | timeOfSample | Long | the time stamp when the event is sent | 1243 | 1244 | ```js 1245 | { 1246 | "eventType": "changeReport", 1247 | "eventVersion": "1", 1248 | "context": { 1249 | "deviceType": "WoCamera", 1250 | "deviceMac": DEVICE_MAC_ADDR, 1251 | "detectionState": "DETECTED", 1252 | "timeOfSample": 123456789 1253 | } 1254 | } 1255 | ``` 1256 | 1257 | #### Pan/Tilt Cam 1258 | 1259 | | Key Name | Value Type | Description | 1260 | | -------------- | ---------- | ------------------------------------------------------------ | 1261 | | eventType | String | the type of events | 1262 | | eventVersion | String | the current event version | 1263 | | context | Object | the detail info of the event | 1264 | | deviceType | String | the type of the device | 1265 | | deviceMac | String | the MAC address of the device | 1266 | | detectionState | String | the detection state of the device, "DETECTED" stands for motion is detected | 1267 | | timeOfSample | Long | the time stamp when the event is sent | 1268 | 1269 | ```js 1270 | { 1271 | "eventType": "changeReport", 1272 | "eventVersion": "1", 1273 | "context": { 1274 | "deviceType": "WoPanTiltCam", 1275 | "deviceMac": DEVICE_MAC_ADDR, 1276 | "detectionState": "DETECTED", 1277 | "timeOfSample": 123456789 1278 | } 1279 | } 1280 | ``` 1281 | 1282 | #### Color Bulb 1283 | 1284 | | Key Name | Value Type | Description | 1285 | | ---------------- | ---------- | ---------------------------------------------------------- | 1286 | | eventType | String | the type of events | 1287 | | eventVersion | String | the current event version | 1288 | | context | Object | the detail info of the event | 1289 | | deviceType | String | the type of the device | 1290 | | deviceMac | String | the MAC address of the device | 1291 | | powerState | String | the current power state of the device, "ON" or "OFF" | 1292 | | brightness | Integer | the brightness value, range from 1 to 100 | 1293 | | color | String | the color value, in the format of RGB value, "255:255:255" | 1294 | | colorTemperature | Integer | the color temperature value, range from 2700 to 6500 | 1295 | | timeOfSample | Long | the time stamp when the event is sent | 1296 | 1297 | ```js 1298 | { 1299 | "eventType": "changeReport", 1300 | "eventVersion": "1", 1301 | "context": { 1302 | "deviceType": "WoBulb", 1303 | "deviceMac": DEVICE_MAC_ADDR, 1304 | "powerState": "ON", 1305 | "brightness": 10, 1306 | "color":"255:245:235", 1307 | "colorTemperature":3500, 1308 | "timeOfSample": 123456789 1309 | } 1310 | } 1311 | ``` 1312 | 1313 | #### LED Strip Light 1314 | 1315 | | Key Name | Value Type | Description | 1316 | | ------------ | ---------- | ---------------------------------------------------------- | 1317 | | eventType | String | the type of events | 1318 | | eventVersion | String | the current event version | 1319 | | context | Object | the detail info of the event | 1320 | | deviceType | String | the type of the device | 1321 | | deviceMac | String | the MAC address of the device | 1322 | | powerState | String | the current power state of the device, "ON" or "OFF" | 1323 | | brightness | Integer | the brightness value, range from 1 to 100 | 1324 | | color | String | the color value, in the format of RGB value, "255:255:255" | 1325 | | timeOfSample | Long | the time stamp when the event is sent | 1326 | 1327 | ```js 1328 | { 1329 | "eventType": "changeReport", 1330 | "eventVersion": "1", 1331 | "context": { 1332 | "deviceType": "WoStrip", 1333 | "deviceMac": DEVICE_MAC_ADDR, 1334 | "powerState": "ON", 1335 | "brightness": 10, 1336 | "color": "255:245:235", 1337 | "timeOfSample": 123456789 1338 | } 1339 | } 1340 | ``` 1341 | 1342 | #### Plug Mini (US) 1343 | 1344 | | Key Name | Value Type | Description | 1345 | | ------------ | ---------- | ---------------------------------------------------- | 1346 | | eventType | String | the type of events | 1347 | | eventVersion | String | the current event version | 1348 | | context | Object | the detail info of the event | 1349 | | deviceType | String | the type of the device | 1350 | | deviceMac | String | the MAC address of the device | 1351 | | powerState | String | the current power state of the device, "ON" or "OFF" | 1352 | | timeOfSample | Long | the time stamp when the event is sent | 1353 | 1354 | ```js 1355 | { 1356 | "eventType": "changeReport", 1357 | "eventVersion": "1", 1358 | "context": { 1359 | "deviceType": "WoPlugUS", 1360 | "deviceMac": DEVICE_MAC_ADDR, 1361 | "powerState": "ON", 1362 | "timeOfSample": 123456789 1363 | } 1364 | } 1365 | ``` 1366 | 1367 | #### Plug Mini (JP) 1368 | 1369 | | Key Name | Value Type | Description | 1370 | | ------------ | ---------- | ---------------------------------------------------- | 1371 | | eventType | String | the type of events | 1372 | | eventVersion | String | the current event version | 1373 | | context | Object | the detail info of the event | 1374 | | deviceType | String | the type of the device | 1375 | | deviceMac | String | the MAC address of the device | 1376 | | powerState | String | the current power state of the device, "ON" or "OFF" | 1377 | | timeOfSample | Long | the time stamp when the event is sent | 1378 | 1379 | ```js 1380 | { 1381 | "eventType": "changeReport", 1382 | "eventVersion": "1", 1383 | "context": { 1384 | "deviceType": "WoPlugJP", 1385 | "deviceMac": DEVICE_MAC_ADDR, 1386 | "powerState": "ON", 1387 | "timeOfSample": 123456789 1388 | } 1389 | } 1390 | ``` 1391 | 1392 | 1393 | 1394 | ---- 1395 | 1396 | * [SwitchBot (Official website)](https://www.switch-bot.com/) 1397 | * [Facebook @SwitchBotRobot](https://www.facebook.com/SwitchBotRobot/) 1398 | * [Twitter @SwitchBot](https://twitter.com/switchbot) 1399 | --------------------------------------------------------------------------------