Skip to content

lie/SwitchBotAPI

BranchesTags
 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

53 Commits

.github/workflows

.github/workflows

 
 

.gitignore

.gitignore

 
 

README-v1.0.md

README-v1.0.md

 
 

README.md

README.md

 
 

Repository files navigation

SwitchBot API v1.1

Introduction

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.

About the New Version

We will stop adding support for new products on v1.0 as we release v1.1.

Hence, we strongly recommend all SwitchBot users to migrate to the new API version because we have improved the authentication method. This will make the communication between your server and the SwitchBot server more secure.

Getting Started

Please follow these steps,

  1. Download the SwitchBot app on App Store or Google Play Store
  2. Register a SwitchBot account and log in into your account
  3. Generate an Open Token within the app a) Go to Profile > Preference b) Tap App Version 10 times. Developer Options will show up c) Tap Developer Options d) Tap Get Token
  4. Roll up your sleeves and get your hands dirty with SwitchBot OpenAPI!

Authentication

Open Token and Secret Key

Note: You must update the app to the latest version, V6.14 or later, in order to get the secret key.

In SwitchBot API v1.1, the authentication method has been improved. In order to gain access to private data through the API, you must generate a unique signature using a token and a secret key. When you make a request, the Authorization token and signature will be validated simultaneously.

You as a developer will then be able to add, delete, edit, and look up your data including profile data and data associated with the devices that have been added to your SwitchBot account.

To continue to use SwitchBot API v1.0, refer to the legacy document.

How to Sign?

We have attached a python script for you to quickly generate a sign. If you prefer to write your own script or routine, here is the procedure.

  1. Print the 13 digit timestamp and concatenate it with your token
  2. Create a signature using your secret and the string produced in the previous step
  3. Convert the signature to upper case

For instance,

# secret key
secret = "" # copy and paste from the SwitchBot app V6.14 or later
# open token
token = "" # copy and paste from the SwitchBot app V6.14 or later
t = 1661927531000
sign = HMAC-SHA256(token + t, secret).toUpperCase()

Python 2 example code

import time
import hashlib
import hmac
import base64

# open token
token = '' # copy and paste from the SwitchBot app V6.14 or later
# secret key
secret = '' # copy and paste from the SwitchBot app V6.14 or later
nonce = ''
t = int(round(time.time() * 1000))
string_to_sign = '{}{}{}'.format(token, t, nonce)

sign = base64.b64encode(hmac.new(secret, msg=string_to_sign, digestmod=hashlib.sha256).digest())
print ('Authorization: {}'.format(token))
print ('t: {}'.format(t))
print ('sign: {}'.format(sign))
print ('nonce: {}'.format(nonce))

Python 3 example code

import json
import time
import hashlib
import hmac
import base64
import uuid

# Declare empty header dictionary
apiHeader = {}
# open token
token = '' # copy and paste from the SwitchBot app V6.14 or later
# secret key
secret = '' # copy and paste from the SwitchBot app V6.14 or later
nonce = uuid.uuid4()
t = int(round(time.time() * 1000))
string_to_sign = '{}{}{}'.format(token, t, nonce)

string_to_sign = bytes(string_to_sign, 'utf-8')
secret = bytes(secret, 'utf-8')

sign = base64.b64encode(hmac.new(secret, msg=string_to_sign, digestmod=hashlib.sha256).digest())
print ('Authorization: {}'.format(token))
print ('t: {}'.format(t))
print ('sign: {}'.format(str(sign, 'utf-8')))
print ('nonce: {}'.format(nonce))

#Build api header JSON
apiHeader['Authorization']=token
apiHeader['Content-Type']='application/json'
apiHeader['charset']='utf8'
apiHeader['t']=str(t)
apiHeader['sign']=str(sign, 'utf-8')
apiHeader['nonce']=str(nonce)

JavaScript example code

const token = "yourToken";
const secret = "yourSecret";
const t = Date.now();
const nonce = "requestID";
const data = token + t + nonce;
const signTerm = crypto.createHmac('sha256', secret)
    .update(Buffer.from(data, 'utf-8'))
    .digest();
const sign = signTerm.toString("base64");
console.log(sign);

const body = JSON.stringify({
    "command": "turnOn",
    "parameter": "default",
    "commandType": "command"
});
const deviceId = "MAC";
const options = {
    hostname: 'api.switch-bot.com',
    port: 443,
    path: `/v1.1/devices/${deviceId}/commands`,
    method: 'POST',
    headers: {
        "Authorization": token,
        "sign": sign,
        "nonce": nonce,
        "t": t,
        'Content-Type': 'application/json',
        'Content-Length': body.length,
    },
};

const req = https.request(options, res => {
    console.log(`statusCode: ${res.statusCode}`);
    res.on('data', d => {
        process.stdout.write(d);
    });
});

req.on('error', error => {
    console.error(error);
});

req.write(body);
req.end();

C# example code

using System;
using System.Diagnostics;
using System.Text;
using System.Security.Cryptography;
using System.Net.Http;

string token = "My Token";
string secret = "My Secret Key";
DateTime dt1970 = new DateTime(1970, 1, 1);
DateTime current = DateTime.Now;
TimeSpan span = current - dt1970;
long time = Convert.ToInt64(span.TotalMilliseconds);
string nonce = Guid.NewGuid().ToString();
string data = token + time.ToString() + nonce;
Encoding utf8 = Encoding.UTF8;
HMACSHA256 hmac = new HMACSHA256(utf8.GetBytes(secret));
string signature = Convert.ToBase64String(hmac.ComputeHash(utf8.GetBytes(data)));

//Create http client
HttpClient client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, @"https://api.switch-bot.com/v1.1/devices");
request.Headers.TryAddWithoutValidation(@"Authorization", token);
request.Headers.TryAddWithoutValidation(@"sign", signature);
request.Headers.TryAddWithoutValidation(@"nonce", nonce);
request.Headers.TryAddWithoutValidation(@"t", time.ToString());

var response = await client.SendAsync(request);

Console.WriteLine(await response.Content.ReadAsStringAsync());

Java 11+ example code

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.time.Instant;
import java.util.Base64;
import java.util.UUID;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class Main {
    public static void main(String[] args) throws Exception {
    	
      String token = args[0];
      String secret = args[1];
      String nonce = UUID.randomUUID().toString();
      String time= "" + Instant.now().toEpochMilli();
      String data = token + time + nonce;
      
      SecretKeySpec secretKeySpec = new SecretKeySpec(secret.getBytes("UTF-8"), "HmacSHA256");
      Mac mac = Mac.getInstance("HmacSHA256");
      mac.init(secretKeySpec);
      String signature = new String(Base64.getEncoder().encode(mac.doFinal(data.getBytes("UTF-8"))));      
      
      HttpRequest getDevices = HttpRequest.newBuilder()
      .uri(new URI("https://api.switch-bot.com/v1.1/devices"))
      .header("Authorization", token)
      .header("sign", signature)
      .header("nonce", nonce)
      .header("t", time)
      .GET()
      .build();
      
      HttpResponse<String> response = HttpClient.newBuilder().build().send(getDevices, BodyHandlers.ofString());
      
      System.out.println(response.body());
    	
    	
    }
    
}

PHP example code

<?php
$token = 'XXXXXXXXXXXXXXXXXXX';
$secret = 'YYYYYYYYYYY';
$nonce = guidv4();
$t = time() * 1000;
$data = utf8_encode($token . $t . $nonce);
$sign = hash_hmac('sha256', $data, $secret,true);
$sign = strtoupper(base64_encode($sign));

$url = "https://api.switch-bot.com/v1.1/devices";

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

$headers = array(
    "Content-Type:application/json",
    "Authorization:" . $token,
    "sign:" . $sign,
    "nonce:" . $nonce,
    "t:" . $t
);

curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
curl_close($curl);

function guidv4($data = null) {
    // Generate 16 bytes (128 bits) of random data or use the data passed into the function.
    $data = $data ?? random_bytes(16);
    assert(strlen($data) == 16);
    $data[6] = chr(ord($data[6]) & 0x0f | 0x40);
    $data[8] = chr(ord($data[8]) & 0x3f | 0x80);

    // Output the 36 character UUID.
    return vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($data), 4));
}

Glossary

The following table provides definitions to the terms to be frequently mentioned in the subsequent sections.

Term Description
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
Hub Mini Short for SwitchBot Hub Mini Model No. W0202200
Hub Plus Short for SwitchBot Hub Plus Model No. SwitchBot Hub S1
Hub 2 Short for SwitchBot Hub 2 Model No. W3202100
Bot Short for SwitchBot Bot Model No. SwitchBot S1
Curtain Short for SwitchBot Curtain Model No. W0701600
Plug Short for SwitchBot Plug Model No. SP11. Currently only available in Japan
Meter Short for SwitchBot Thermometer and Hygrometer Model No. SwitchBot MeterTH S1
Meter Plus (JP) Short for SwitchBot Thermometer and Hygrometer Plus (JP) Model No. W2201500
Meter Plus (US) Short for SwitchBot Thermometer and Hygrometer Plus (US) Model No. W2301500
Outdoor Meter Short for Indoor/Outdoor Thermo-Hygrometer Model No. W3400010
Motion Sensor Short for SwitchBot Motion Sensor Model No. W1101500
Contact Sensor Short for SwitchBot Contact Sensor Model No. W1201500
Color Bulb Short for SwitchBot Color Bulb Model No. W1401400
Strip Light Short for SwitchBot LED Strip Light Model No. W1701100
Plug Mini (US) Short for SwitchBot Plug Mini (US) Model No. W1901400 and W1901401
Plug Mini (JP) Short for SwitchBot Plug Mini (JP) Model No. W2001400 and W2001401
Lock Short for SwitchBot Lock Model No. W1601700
Keypad Short for SwitchBot Lock Model No. W2500010
Keypad Touch Short for SwitchBot Lock Model No. W2500020
Robot Vacuum Cleaner S1 Short for SwitchBot Robot Vacuum Cleaner S1 Model No. W3011000. Currently only available in Japan.
Robot Vacuum Cleaner S1 Plus Short for SwitchBot Robot Vacuum Cleaner S1 Plus Model No. W3011010. Currently only available in Japan.
Ceiling Light Short for SwitchBot Ceiling Light Model No. W2612230 and W2612240. Currently only available in Japan.
Ceiling Light Pro Short for SwitchBot Ceiling Light Pro Model No. W2612210 and W2612220. Currently only available in Japan.
Indoor Cam Short for SwitchBot Indoor Cam Model No. W1301200
Pan/Tilt Cam Short for SwitchBot Pan/Tilt Cam Model No. W1801200
Pan/Tilt Cam 2K Short for SwitchBot Pan/Tilt Cam 2K Model No. W3101100
Blind Tilt Short for SwitchBot Blind Tilt Model No. W2701600
Cloud Services A SwitchBot app feature that 1. enables SwitchBot products to be discovered and communicated with third-party services such as Alexa, Google Home, IFTTT, and so forth 2. allows users to create customized smart scenes and widgets. For BLE-based devices such as Bot and Curtain, you MUST first add a Hub/Hub Mini/Hub Plus and then enable Cloud Services on the Settings page in order to make use of the web API!

API Usage

Host Domain

https://api.switch-bot.com

Sending a Request

The following request types are supported,

  • GET
  • PUT
  • POST
  • DELETE

Content-Type

For POST requests, use application/json; charset=utf8 as the Content-Type

Request limit

The amount of API calls per day is limited to 10000 times. Going over that limit will return "Unauthorized."

Request Header

The following parameters need to be included into the header,

Parameter Type Location Required Description
Authorization String header Yes Open Token acquired
sign String header Yes A signature generated from the token and secret key using a specific algorithm.
t Long header Yes A 13 digit timestamp (standard time).
nonce Long header Yes A random UUID generated by developers themselves to blend into the string to sign.

Standard HTTP Error Codes

The following table lists the most common HTTP error response,

Code Name Description
400 Bad Request The client has issued an invalid request. This is commonly used to specify validation errors in a request payload.
401 Unauthorized Authorization for the API is required, but the request has not been authenticated.
403 Forbidden The request has been authenticated but does not have appropriate permissions, or a requested resource is not found.
404 Not Found Specifies the requested path does not exist.
406 Not Acceptable The client has requested a MIME type via the Accept header for a value not supported by the server.
415 Unsupported Media Type The client has defined a contentType header that is not supported by the server.
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.
429 Too Many Requests The client has exceeded the number of requests allowed for a given time window.
500 Internal Server Error An unexpected error on the SmartThings servers has occurred. These errors should be rare.

Devices

The devices API is used to access the properties and states of SwitchBot devices and to send control commands to those devices.

Get device list

GET /v1.1/devices

Description

Get a list of devices, which include physical devices and virtual infrared remote devices that have been added to the current user's account.

Physical devices refer to the following SwitchBot products,

  • Hub
  • Hub Plus
  • Hub Mini
  • Bot (MUST enable Cloud Services on SwitchBot app first)
  • Curtain (MUST enable Cloud Services on SwitchBot app first)
  • Plug
  • Meter (MUST enable Cloud Services on SwitchBot app first)
  • Motion Sensor (MUST enable Cloud Services on SwitchBot app first)
  • Contact Sensor (MUST enable Cloud Services on SwitchBot app first)
  • Color Bulb
  • Humidifier
  • Smart Fan
  • Strip Light
  • Plug Mini (US)
  • Plug Mini (JP)
  • Lock
  • Meter Plus (JP) (MUST enable Cloud Services on SwitchBot app first)
  • Meter Plus (US) (MUST enable Cloud Services on SwitchBot app first)
  • Robot Vacuum Cleaner S1
  • Robot Vacuum Cleaner S1 Plus
  • Keypad (MUST enable Cloud Services on SwitchBot app first)
  • Keypad Touch (MUST enable Cloud Services on SwitchBot app first)
  • Ceiling Light
  • Ceiling Light Pro
  • Blind Tilt (MUST enable Cloud Services on SwitchBot app first)
  • new Hub 2
  • new Outdoor Meter

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, Hub 2, or Ceiling Light is required in order to be able to create these virtual devices within the app. The types of appliances supported include,

  • Air Conditioner
  • TV
  • Light
  • Streamer
  • Set Top Box
  • DVD Player
  • Fan
  • Projector
  • Camera
  • Air Purifier
  • Speaker
  • Water Heater
  • Robot Vacuum Cleaner
  • Others

Responses

The response is basically a JSON object, which contains the following properties,

Key Name Value Type
statusCode Integer
message String
body Object

The body object contains the following properties,

Key Name Value Type Description
deviceList Array a list of physical devices
infraredRemoteList Array a list of virtual infrared remote devices

The response may contain the following codes and messages,

Status Code Body Content Message Description
100 Device list object success Returns an object that contains two device lists
n/a n/a Unauthorized Http 401 Error. User permission is denied due to invalid token.
190 n/a System error Device internal error due to device states not synchronized with server

The deviceList array contains a list of objects with the following key-value attributes,

Bot
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Bot
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID
Curtain
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Curtain
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID
curtainDevicesIds Array a list of Curtain device IDs such that the Curtain devices are being paired or grouped
calibrate Boolean determines if the open position and the close position of a device have been properly calibrated or not
group Boolean determines if a Curtain is paired with or grouped with another Curtain or not
master Boolean determines if a Curtain is the master device or not when paired with or grouped with another Curtain
openDirection String the opening direction of a Curtain
Hub/Hub Plus/Hub Mini/Hub 2
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Hub, Hub Plus, Hub Mini, or Hub 2.
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
Meter
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Meter
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID
Meter Plus
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. MeterPlus
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID
Outdoor Meter
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. WoIOSensor
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID
Lock
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Smart Lock
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID
group Boolean determines if a Lock is grouped with another Lock or not
master Boolean determines if a Lock is the master device or not when grouped with another Lock in Dual Lock mode
groupName String the name of the Lock group
lockDevicesIds Array a list of Lock device IDs such that the Lock devices are being grouped in Dual Lock mode
Keypad
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Keypad
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID
lockDeviceId String MAC address of the Lock that the current device is paired with
keyList Object a list of passcodes

keyList maintains a list of passcodes,

Key Value Type Description
id Integer passcode ID
name String name of the passcode
type String type of the passcode. permanent, a permanent passcode. timeLimit, a temporary passcode. disposable, a one-time passcode. urgent, an emergency passcode.
password String the passcode string encrypted with the developer secret key using the aes-128-cbc algorithm
iv String an arbitrary number used for the encryption
status String validity of the passcode. normal, the passcode is valid. expired, the passcode is invalid.
createTime Long the time when the passcode is generated
Keypad Touch
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Keypad Touch
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID
lockDeviceId String MAC address of the Lock that the current device is paired with
keyList Object a list of passcodes

keyList maintains a list of passcodes,

Key Value Type Description
id Integer passcode ID
name String name of the passcode
type String type of the passcode. permanent, a permanent passcode. timeLimit, a temporary passcode. disposable, a one-time passcode. urgent, an emergency passcode.
password String the passcode string encrypted with the developer secret key using the aes-128-cbc algorithm
iv String an arbitrary number used for the encryption
status String validity of the passcode. normal, the passcode is valid. expired, the passcode is invalid.
createTime Long the time when the passcode is generated
Remote
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Remote
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID
Motion Sensor
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Motion Sensor
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID
Contact Sensor
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Contact Sensor
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID
Ceiling Light
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Ceiling Light
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
Ceiling Light Pro
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Ceiling Light Pro
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
Plug Mini (US)
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Plug Mini (US)
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
Plug Mini (JP)
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Plug Mini (JP)
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
Plug
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Plug
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
Strip Light
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Strip Light
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
Color Bulb
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Color Bulb
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
Robot Vacuum Cleaner S1
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Robot Vacuum Cleaner S1
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
Robot Vacuum Cleaner S1 Plus
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Robot Vacuum Cleaner S1 Plus
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
Humidifier
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Humidifier
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
Indoor Cam
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Indoor Cam
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
Pan/Tilt Cam
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Pan/Tilt Cam
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
Pan/Tilt Cam 2K
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Pan/Tilt Cam
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
Blind Tilt
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Blind Tilt
version Integer the version of the device
enableCloudService Boolean determines if Cloud Service is enabled or not for the current device
hubDeviceId String device's parent Hub ID
blindTiltDevicesIds Array a list of Blind Tilt device IDs such that the Blind Tilt devices are being paired or grouped
calibrate Boolean determines if the open and the closed positions have been properly calibrated or not
group Boolean determines if a Blind Tilt device is paired with or grouped with one or more devices of the same type or not
master Boolean determines if a Blind Tilt device is the master device or not when paired with or grouped with one or more devices of the same type
direction String the opening direction of a Blind Tilt device
slidePosition Integer the current position, 0-100
Virtual infrared remote devices

The infraredRemoteList array contains a list of objects with the following key-value attributes,

Key Value Type Description
deviceId String device ID
deviceName String device name
remoteType String device type
hubDeviceId String remote device's parent Hub ID

Sample

Get all devices

Request

GET https://api.switch-bot.com/v1.1/devices

Response

{
    "statusCode": 100,
    "body": {
        "deviceList": [
            {
                "deviceId": "500291B269BE",
                "deviceName": "Living Room Humidifier",
                "deviceType": "Humidifier",
                "enableCloudService": true,
                "hubDeviceId": "000000000000"
            }
        ],
        "infraredRemoteList": [
            {
                "deviceId": "02-202008110034-13",
                "deviceName": "Living Room TV",
                "remoteType": "TV",
                "hubDeviceId": "FA7310762361"
            }
        ]
    },
    "message": "success"
}

Get device status

GET /v1.1/devices/{deviceId}/status

Description

Get the status of a physical device that has been added to the current user's account.

Physical devices refer to the following SwitchBot products,

  • Bot
  • Plug
  • Curtain
  • Meter
  • Motion Sensor
  • Contact Sensor
  • Color Bulb
  • Humidifier
  • Smart Fan
  • Strip Light
  • Plug Mini (US)
  • Plug Mini (JP)
  • Lock
  • Meter Plus (JP)
  • Meter Plus (US)
  • Robot Vacuum Cleaner S1
  • Robot Vacuum Cleaner S1 Plus
  • Keypad (MUST enable Cloud Service first)
  • Keypad Touch (MUST enable Cloud Service first)
  • Ceiling Light
  • Ceiling Light Pro
  • new Hub 2
  • new Outdoor Meter

Path parameters

Name Type Required Description
deviceId String Yes device ID

Responses

The response is basically a JSON object, which contains the following properties,

Key Name Value Type
statusCode Integer
message String
body Object

The reponses may contain the following codes and message,

Status Code Body Content Message Description
100 Device list object success Returns an object that contains two device lists
n/a n/a Unauthorized Http 401 Error. User permission is denied due to invalid token.
190 n/a System error Device internal error due to device states not synchronized with server

The body object contains the following properties,

Bot
Key Value Type Description
deviceId String device ID
deviceType String device type. Bot
power String ON/OFF state
battery Integer the current battery level, 0-100
version String the current firmware version, e.g. V6.3
deviceMode String pressMode, switchMode, or customizeMode
hubDeviceId String device's parent Hub ID
Curtain
Key Value Type Description
deviceId String device ID
deviceType String device type. Curtain
hubDeviceId String device's parent Hub ID
calibrate Boolean determines if the open position and the close position of a device have been properly calibrated or not
group Boolean determines if a Curtain is paired with or grouped with another Curtain or not
moving Boolean determines if a Curtain is moving or not
battery Integer the current battery level, 0-100
version String the current firmware version, e.g. V4.2
slidePosition String the percentage of the distance between the calibrated open position and closed position that Curtain has traversed
Meter
Key Value Type Description
deviceId String device ID
deviceType String device type. Meter
hubDeviceId String device's parent Hub ID
temperature Float temperature in celsius
version String the current firmware version, e.g. V4.2
battery Integer the current battery level, 0-100
humidity Integer humidity percentage
Meter Plus
Key Value Type Description
deviceId String device ID
deviceType String device type. MeterPlus
hubDeviceId String device's parent Hub ID
battery Integer the current battery level, 0-100
version String the current firmware version, e.g. V4.2
temperature Float temperature in celsius
humidity Integer humidity percentage
Outdoor Meter
Key Value Type Description
deviceId String device ID
deviceType String device type. WoIOSensor
hubDeviceId String device's parent Hub ID
battery Integer the current battery level, 0-100
version String the current firmware version, e.g. V4.2
temperature Float temperature in celsius
humidity Integer humidity percentage
Lock
Key Value Type Description
deviceId String device ID
deviceType String device type. Smart Lock
hubDeviceId String device's parent Hub ID
battery Integer the current battery level, 0-100
version String the current firmware version, e.g. V4.2
lockState String determines if locked or not
doorState String determines if the door is closed or not
calibrate Boolean determines if Lock has been calibrated or not
Keypad
Key Value Type Description
deviceId String device ID
deviceType String device type. Keypad
hubDeviceId String device's parent Hub ID
Keypad Touch
Key Value Type Description
deviceId String device ID
deviceType String device type. Keypad Touch
hubDeviceId String device's parent Hub ID
Motion Sensor
Key Value Type Description
deviceId String device ID
deviceType String device type. Motion Sensor
hubDeviceId String device's parent Hub ID
battery Integer the current battery level, 0-100
version String the current firmware version, e.g. V4.2
moveDetected Boolean determines if motion is detected
brightness String the ambient brightness picked up by the sensor. bright or dim
Contact Sensor
Key Value Type Description
deviceId String device ID
deviceType String device type. Contact Sensor
hubDeviceId String device's parent Hub ID
battery Integer the current battery level, 0-100
version String the current firmware version, e.g. V4.2
moveDetected Boolean determines if motion is detected
openState String the open state of the sensor. open, close, or timeOutNotClose
brightness String the ambient brightness picked up by the sensor. bright or dim
Ceiling Light
Key Value Type Description
deviceId String device ID
deviceType String device type. Ceiling Light
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
power String ON/OFF state
version String the current BLE and Wi-Fi firmware version, e.g. V3.1-6.3
brightness Integer the brightness value, range from 1 to 100
colorTemperature Integer the color temperature value, range from 2700 to 6500
Ceiling Light Pro
Key Value Type Description
deviceId String device ID
deviceType String device type. Ceiling Light Pro
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
version String the current BLE and Wi-Fi firmware version, e.g. V3.1-6.3
power String ON/OFF state
brightness Integer the brightness value, range from 1 to 100
colorTemperature Integer the color temperature value, range from 2700 to 6500
Plug Mini (US)
Key Value Type Description
deviceId String device ID
deviceType String device type. Plug Mini (US)
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
voltage Float the voltage of the device, measured in Volt
version String the current BLE and Wi-Fi firmware version, e.g. V3.1-6.3
weight Float the power consumed in a day, measured in Watts
electricityOfDay Integer the duration that the device has been used during a day, measured in minutes
electricCurrent Float the current of the device at the moment, measured in Amp
Plug Mini (JP)
Key Value Type Description
deviceId String device ID
deviceType String device type. Plug Mini (JP)
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
voltage Float the voltage of the device, measured in Volt
version String the current BLE and Wi-Fi firmware version, e.g. V3.1-6.3
weight Float the power consumed in a day, measured in Watts
electricityOfDay Integer the duration that the device has been used during a day, measured in minutes
electricCurrent Float the current of the device at the moment, measured in Amp
Plug
Key Value Type Description
deviceId String device ID
deviceType String device type. Plug
power String ON/OFF state
version String the current Wi-Fi firmware version, e.g. V4.2
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
Strip Light
Key Value Type Description
deviceId String device ID
deviceType String device type. Strip Light
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
power String ON/OFF state
version String the current BLE and Wi-Fi firmware version, e.g. V3.1-6.3
brightness Integer the brightness value, range from 1 to 100
color String the color value, RGB "255:255:255"
Color Bulb
Key Value Type Description
deviceId String device ID
deviceType String device type. Color Bulb
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
power String ON/OFF state
brightness Integer the brightness value, range from 1 to 100
version String the current BLE and Wi-Fi firmware version, e.g. V3.1-6.3
color String the color value, RGB "255:255:255"
colorTemperature Integer the color temperature value, range from 2700 to 6500
Robot Vacuum Cleaner S1
Key Value Type Description
deviceId String device ID
deviceType String device type. Robot Vacuum Cleaner S1
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
workingStatus String the working status of the device. StandBy, Clearing, Paused, GotoChargeBase, Charging, ChargeDone, Dormant, InTrouble, InRemoteControl, or InDustCollecting
onlineStatus String the connection status of the device. online or offline
battery Integer the current battery level
Robot Vacuum Cleaner S1 Plus
Key Value Type Description
deviceId String device ID
deviceName String device name
deviceType String device type. Robot Vacuum Cleaner S1 Plus
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
workingStatus String the working status of the device. StandBy, Clearing, Paused, GotoChargeBase, Charging, ChargeDone, Dormant, InTrouble, InRemoteControl, or InDustCollecting
onlineStatus String the connection status of the device. online or offline
battery Integer the current battery level
Humidifier
Key Value Type Description
deviceId String device ID
deviceType String device type. Humidifier
hubDeviceId String device's parent Hub ID. 000000000000 when the device itself is a Hub or it is connected through Wi-Fi.
power String ON/OFF state
humidity Integer humidity percentage
temperature Float temperature in celsius
nebulizationEfficiency Integer atomization efficiency percentage
auto Boolean determines if a Humidifier is in Auto Mode or not
childLock Boolean determines if a Humidifier's safety lock is on or not
sound Boolean determines if a Humidifier is muted or not
lackWater Boolean determines if the water tank is empty or not
Blind Tilt
Key Value Type Description
deviceId String device ID
deviceType String device type. Blind Tilt
hubDeviceId String device's parent Hub ID
version Integer the firmware version of the device
calibrate Boolean determines if the open and the closed positions have been properly calibrated or not
group Boolean determines if a Blind Tilt device is paired with or grouped with one or more devices of the same type or not
moving Boolean determines if the device is moving or not
direction String the opening direction of a Blind Tilt device
slidePosition Integer the current position, 0-100
Hub 2
Key Value Type Description
deviceId String device ID
deviceType String device type. Hub 2
hubDeviceId String Hub ID, equivalent to device ID
temperature Float temperature in celsius
lightLevel Integer the level of illuminance of the ambience light, 1~20
version String the current firmware version, e.g. V4.2
humidity Integer humidity percentage

Sample

SwitchBot Meter example

Request the status of a SwitchBot Thermometer and Hygrometer

Request

GET https://api.switch-bot.com/v1.1/devices/C271111EC0AB/status

Response

{
    "statusCode": 100,
    "body": {
        "deviceId": "C271111EC0AB",
        "deviceType": "Meter",
        "hubDeviceId": "FA7310762361",
        "humidity": 52,
        "temperature": 26.1
    },
    "message": "success"
}
SwitchBot Curtain example

Request the status of a SwitchBot Curtain

Request

GET https://api.switch-bot.com/v1.1/devices/E2F6032048AB/status

Response

{
    "statusCode": 100,
    "body": {
        "deviceId": "E2F6032048AB",
        "deviceType": "Curtain",
        "hubDeviceId": "FA7310762361",
        "calibrate": true,
        "group": false,
        "moving": false,
        "slidePosition": 0
    },
    "message": "success"
}

Send device control commands

POST /v1.1/devices/{deviceId}/commands

Description

Send control commands to physical devices and virtual infrared remote devices.

Command set for physical devices

Bot
deviceType commandType Command command parameter Description
Bot command turnOff default set to OFF state
Bot command turnOn default set to ON state
Bot command press default trigger press
Curtain
deviceType commandType Command command parameter Description
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 open, 100 means closed)
Curtain command turnOff default equivalent to set position to 100
Curtain command turnOn default equivalent to set position to 0
Lock
deviceType commandType Command command parameter Description
Lock command lock default rotate to locked position
Lock command unlock default rotate to unlocked position
Humidifier
deviceType commandType Command command parameter Description
Humidifier command turnOff default set to OFF state
Humidifier command turnOn default set to ON state
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%
Plug
deviceType commandType Command command parameter Description
Plug command turnOn default set to ON state
Plug command turnOff default set to OFF state
Plug Mini (US)
deviceType commandType Command command parameter Description
Plug Mini (US) command turnOn default set to ON state
Plug Mini (US) command turnOff default set to OFF state
Plug Mini (US) command toggle default toggle state
Plug Mini (JP)
deviceType commandType Command command parameter Description
Plug Mini (JP) command turnOn default set to ON state
Plug Mini (JP) command turnOff default set to OFF state
Plug Mini (JP) command toggle default toggle state
Color Bulb
deviceType commandType Command command parameter Description
Color Bulb command turnOn default set to ON state
Color Bulb command turnOff default set to OFF state
Color Bulb command toggle default toggle state
Color Bulb command setBrightness {1-100} set brightness
Color Bulb command setColor "{0-255}:{0-255}:{0-255}" set RGB color value
Color Bulb command setColorTemperature {2700-6500} set color temperature
Strip Light
deviceType commandType Command command parameter Description
Strip Light command turnOn default set to ON state
Strip Light command turnOff default set to OFF state
Strip Light command toggle default toggle state
Strip Light command setBrightness {1-100} set brightness
Strip Light command setColor "{0-255}:{0-255}:{0-255}" set RGB color value
Robot Vacuum Cleaner S1
deviceType commandType Command command parameter Description
Robot Vacuum Cleaner S1 command start default start vacuuming
Robot Vacuum Cleaner S1 command stop default stop vacuuming
Robot Vacuum Cleaner S1 command dock default return to charging dock
Robot Vacuum Cleaner S1 command PowLevel {0-3} set suction power level: 0 (Quiet), 1 (Standard), 2 (Strong), 3 (MAX)
Robot Vacuum Cleaner S1 Plus
deviceType commandType Command command parameter Description
Robot Vacuum Cleaner S1 Plus command start default start vacuuming
Robot Vacuum Cleaner S1 Plus command stop default stop vacuuming
Robot Vacuum Cleaner S1 Plus command dock default return to charging dock
Robot Vacuum Cleaner S1 Plus command PowLevel {0-3} set suction power level: 0 (Quiet), 1 (Standard), 2 (Strong), 3 (MAX)
Ceiling Light
deviceType commandType Command command parameter Description
Ceiling Light command turnOn default set to ON state
Ceiling Light command turnOff default set to OFF state
Ceiling Light command toggle default toggle state
Ceiling Light command setBrightness {1-100} set brightness
Ceiling Light command setColorTemperature {2700-6500} set the color temperature
Ceiling Light Pro
deviceType commandType Command command parameter Description
Ceiling Light Pro command turnOn default set to ON state
Ceiling Light Pro command turnOff default set to OFF state
Ceiling Light Pro command toggle default toggle state
Ceiling Light Pro command setBrightness {1-100} set brightness
Ceiling Light Pro command setColorTemperature {2700-6500} set the color temperature
Keypad

The control commands for this product work differently than the other products. Due to security concerns, the passcodes are stored locally. This mechanism dramatically prolongs the time needed to successfully create a passcode and get the correct result through the Web API. Hence, the actual results of the following commands are returned from the SwitchBot server asynchronously and are delivered through a webhook.

You need to configure a webhook to receive the correct result. Refer to this product's webhook definition.

deviceType commandType Command command parameter Description
Keypad command createKey { "name": passcode _name_str, "type": passcode_type_str, "password": passcode_str, "startTime": valid_from_long, "endTime": valid_to_long } create a new passcode
Keypad command deleteKey { "id": passcode_id_int } delete an existing passcode

The following table describes the parameter object for createKey,

Key Name Value Type Description
name String a unique name for the passcode. duplicates under the same device are not allowed.
type String type of the passcode. permanent, a permanent passcode. timeLimit, a temporary passcode. disposable, a one-time passcode. urgent, an emergency passcode.
password String a 6 to 12-digit passcode in plain text
startTime Long set the time the passcode becomes valid from, mandatory for one-time passcode and temporary passcode. a 10-digit timestamp.
endTime Long set the time the passcode becomes expired, mandatory for one-time passcode and temporary passcode. a 10-digit timestamp.

The following table describes the parameter object for deleteKey,

Key Name Value Type Description
id String the id of the passcode
Keypad Touch

The control commands for this product work differently than the other products. Due to security concerns, the passcodes are stored locally. This mechanism dramatically prolongs the time needed to successfully create a passcode and get the correct result through the Web API. Hence, the actual results of the following commands are returned from the SwitchBot server asynchronously and are delivered through a webhook.

You need to configure a webhook to receive the correct result. Refer to this product's webhook definition.

deviceType commandType Command command parameter Description
Keypad Touch command createKey { "name": passcode _name_str, "type": passcode_type_str, "password": passcode_str, "startTime": valid_from_long, "endTime": valid_to_long } create a new passcode
Keypad Touch command deleteKey { "id": passcode_id_int } delete an existing passcode

The following table describes the parameter object for createKey,

Key Name Value Type Description
name String a unique name for the passcode. duplicates under the same device are not allowed.
type String type of the passcode. permanent, a permanent passcode. timeLimit, a temporary passcode. disposable, a one-time passcode. urgent, an emergency passcode.
password String a 6 to 12-digit passcode in plain text
startTime Long set the time the passcode becomes valid from, mandatory for one-time passcode and temporary passcode. a 10-digit timestamp.
endTime Long set the time the passcode becomes expired, mandatory for one-time passcode and temporary passcode. a 10-digit timestamp.

The following table describes the parameter object for deleteKey,

Key Name Value Type Description
id String the id of the passcode
Blind Tilt
deviceType commandType Command command parameter Description
Blind Tilt command setPosition direction;position
e.g. up;60		 direction: up/down
position: 0~100 (0 means closed, 100 means open, it MUST be set to a multiple of 2. e.g. up;48 or up; 36)
Blind Tilt command fullyOpen default Set the position of Blind Tilt to open, equivalent to setting the position to up;100 or down;100
Blind Tilt command closeUp default Set the position of Blind Tilt to closed up, equivalent to setting the position to up;0
Blind Tilt command closeDown default Set the position of Blind Tilt to closed down, equivalent to setting the position to down;0

Command set for virtual infrared remote devices

The table below describes all the available commands for virtual infrared remote devices,

deviceType commandType Command command parameter Description
All home appliance types except Others command turnOn default every home appliance can be turned on by default
All home appliance types except Others command turnOff default every home appliance can be turned off by default
Others customize {user-defined button name} default all user-defined buttons must be configured with commandType=customize
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
TV, IPTV/Streamer, Set Top Box command SetChannel {channel number}, e.g. 15 set the TV channel to switch to
command volumeAdd default volume up
command volumeSub default volume down
command channelAdd default next channel
command channelSub default previous channel
DVD, Speaker command setMute default mute/unmute
command FastForward default fast forward
command Rewind default rewind
command Next default next track
command Previous default last track
command Pause default pause
command Play default play/resume
command Stop default stop
Speaker command volumeAdd default volume up
command volumeSub default volume down
Fan command swing default swing
command timer default set timer
command lowSpeed default set fan speed to low
command middleSpeed default set fan speed to medium
command highSpeed default set fan speed to high
Light command brightnessUp default brightness up
command brightnessDown default brightness down

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.

Path parameters

Name Type Required Description
deviceId String Yes device ID

Request body parameters

Name Type Required Description
command String Yes the name of the command
parameter String No some commands require parameters, such as SetChannel
commandType String No for customized buttons, this needs to be set to customzie

Response

The response is basically a JSON object, which contains the following properties,

Key Name Value Type
statusCode Integer
message String
body Object

Errors

Error code/message Description
{"message": "Unauthorized"} Http 401 Error. User permission is denied due to invalid token.
151 device type error
152 device not found
160 command is not supported
161 device offline
171 hub device is offline
190 Device internal error due to device states not synchronized with server. Or command format is invalid.

Sample

Keypad example

Create a temporary passcode

Request

POST https://api.switch-bot.com/v1.1/devices/F7538E1ABCEB/commands
{
    "commandType": "command",
    "command": "createKey",
    "parameter": {
        "name": "Guest Code",
        "type": "timeLimit",
        "password": "12345678",
        "startTime": 1664640056,
        "endTime": 1665331432
    }
}

Response

{
    "statusCode": 100,
    "body": {
        "commandId": "CMD166444044923602"
    },
    "message": "success"
}
Bot example

Turn a Bot on

Request

POST https://api.switch-bot.com/v1.1/devices/210/commands
{
    "command": "turnOn",
    "parameter": "default",
    "commandType": "command"
}

Response

{
    "statusCode": 100,
    "body": {},
    "message": "success"
}

Set the color value of a Color Bulb Request

POST https://api.switch-bot.com/v1.1/devices/84F70353A411/commands
{
    "command": "setColor",
    "parameter": "122:80:20", // yellow
    "commandType": "command"
}

Response

{
    "statusCode": 100,
    "body": {},
    "message": "success"
}
Infrared remote device example

Set an Air Conditioner

Request

POST https://api.switch-bot.com/v1.1/devices/02-202007201626-70/commands
{
    "command": "setAll",
    "parameter": "26,1,3,on",
    "commandType": "command"
}

Response

{
    "statusCode": 100,
    "body": {},
    "message": "success"
}

Trigger a customized button

Request

POST https://api.switch-bot.com/v1.1/devices/02-202007201626-10/commands
{
    "command": "ボタン", // the name of the customized button
    "parameter": "default",
    "commandType": "customize"
}

Response

{
    "statusCode": 100,
    "body": {},
    "message": "success"
}

Scenes

The scenes API is used to access the smart scenes created by a user and to execute manual scenes.

Get scene list

GET /v1.1/scenes

Description

Get a list of manual scenes created by the current user.

Response

The response is basically a JSON object, which contains the following properties,

Key Name Value Type
statusCode Integer
message String
body Object

The body object contains a list of objects, which has the following properties,

Key Type Description
sceneId String a scene's ID
sceneName String a scene's name

Errors

Error code/message Description
{"message": "Unauthorized"} Http 401 Error. User permission is denied due to invalid token.
190 Device internal error due to device states not synchronized with server

Sample

Get all scenes

Request

GET https://api.switch-bot.com/v1.1/scenes

Response

{
    "statusCode": 100,
    "body": [
        {
            "sceneId": "T02-20200804130110",
            "sceneName": "Close Office Devices"
        },
        {
            "sceneId": "T02-202009221414-48924101",
            "sceneName": "Set Office AC to 25"
        },
        {
            "sceneId": "T02-202011051830-39363561",
            "sceneName": "Set Bedroom to 24"
        },
        {
            "sceneId": "T02-202011051831-82928991",
            "sceneName": "Turn off home devices"
        },
        {
            "sceneId": "T02-202011062059-26364981",
            "sceneName": "Set Bedroom to 26 degree"
        }
    ],
    "message": "success"
}

Execute manual scenes

POST /v1.1/scenes/{sceneId}/execute

Description

Sends a request to execute a manual scene.

Path parameters

Name Type Required Description
sceneId String Yes scene ID

The response is basically a JSON object, which contains the following properties,

Key Name Value Type
statusCode Integer
message String
body Object

Errors

Error code/message Description
{"message": "Unauthorized"} Http 401 Error. User permission is denied due to invalid token.
190 Device internal error due to device states not synchronized with server

Sample

Execute a scene

Request

POST https://api.switch-bot.com/v1.1/scenes/T02-202009221414-48924101/execute

Response

{
    "statusCode": 100,
    "body": {},
    "message": "success"
}

Webhook

Configure webhook

Description

Configure the url that all the webhook events will be sent to

Request

POST https://api.switch-bot.com/v1.1/webhook/setupWebhook
Request body parameters
Key Name Value Type Description
action String the type of actions
url String the url where all the events are sent to
deviceList String the list of device ids, currently only supports "ALL"

Head

{
    "Content-type":"application/json",
    "Authorization":your_token // enter your API token
}

Body

{
    "action":"setupWebhook",
    "url":url1, // enter your url
    "deviceList":"ALL"
}

Response

Sample

{
    "statusCode": 100,
    "body": {},
    "message": ""
}

Get webhook configuration

Description

Get the current configuration info of the webhook

Request

POST https://api.switch-bot.com/v1.1/webhook/queryWebhook
Request body parameters
Key Name Value Type Description
action String the type of actions, currently supports "queryUrl", "queryDetails"
url String the url where all the events are sent to. you need to specify the url when using queryDetails
queryUrl

Head

{
    "Content-type":"application/json",
    "Authorization":your_token // enter your API token
}

Body

{
    "action": "queryUrl"
}
queryDetails

Head

{
    "Content-type":"application/json",
    "Authorization":your_token // enter your API token
}

Body

{
    "action": "queryDetails",
    "urls":[url1] // get infos of a url
}

Response

queryUrl
{
    "statusCode": 100,
    "body": {
        "urls": [url1] // the target url
    },
    "message": ""
}
queryDetails
{
    "statusCode": 100,
    "body": [
        {
            "url":url1,
            "createTime":123456,
            "lastUpdateTime":123456,
            "deviceList": "ALL",
            "enable":true
        }
    ],
    "message": ""
}

Update webhook configuration

Description

Update the configuration of the webhook

Request

POST https://api.switch-bot.com/v1.1/webhook/updateWebhook
Request body parameters
Key Name Value Type Description
action String the type of actions
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

Head

{
    "Content-type":"application/json",
    "Authorization":your_token // enter your API token
}

Body

{
    "action": "updateWebhook",
    "config":{
        "url":url1,
        "enable":true
    }
}

Response

{
    "statusCode": 100,
    "body": {},
    "message": ""
}

Delete webhook

Description

Delete the configuration of the webhook

Request

POST https://api.switch-bot.com/v1.1/webhook/deleteWebhook
Request body parameters
Key Name Value Type Description
action String the type of actions
url String the url where all the events are sent to

Head

{
    "Content-type":"application/json",
    "Authorization":your_token // enter your API token
}

Body

{
    "action": "deleteWebhook",
    "url":url1
}

Response

{
    "statusCode": 100,
    "body": {},
    "message": ""
}

Receive events from webhook

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.

Device Type Product
WoHand Bot
WoCurtain Curtain
WoPresence Motion Sensor
WoContact Contact Sensor
WoLock Lock
WoCamera Indoor Cam
WoPanTiltCam Pan/Tilt Cam
WoBulb Color Bulb
WoStrip LED Strip Light
WoPlugUS Plug Mini (US)
WoPlugJP Plug Mini (JP)
WoMeter Meter
WoMeterPlus Meter Plus
WoIOSensor Outdoor Meter
WoSweeper Robot Vacuum Cleaner S1
WoSweeperPlus Robot Vacuum Cleaner S1 Plus
WoCeiling Ceiling Light
WoCeilingPro Ceiling Light Pro
WoKeypad Keypad
WoKeypadTouch Keypad Touch
WoHub2 Hub 2

Bot

Key Name Value Type Description
eventType String the type of events
eventVersion String the current event version
context Object the detail info of the event
deviceType String the type of the device
deviceMac String the MAC address of the device
power String the current state of the device. This state is only valid for Switch Mode, where "on" stands for on and "off" stands for off. It will return "on" or "off" in Press Mode or Customize Mode, but the returned value can be neglected.
timeOfSample Long the time stamp when the event is sent 
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoHand",
        "deviceMac": DEVICE_MAC_ADDR,
        "power": "on",//"on"or"off"
        "battery": 10,
        "deviceMode": "pressMode",//pressMode,switchMode,customizeMode
        "timeOfSample": 123456789
    }
}

Curtain

Key Name Value Type Description
eventType String the type of events
eventVersion String the current event version
context Object the detail info of the event
deviceType String the type of the device
deviceMac String the MAC address of the device
calibrate Boolean determines if the open position and the close position of a device have been properly calibrated or not
group Boolean determines if a Curtain is paired with or grouped with another Curtain or not
slidePosition Integer the percentage of the distance between the calibrated open position and closed position that Curtain has traversed
battery Integer the battery level of a Curtain
timeOfSample Long the time stamp when the event is sent 
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoCurtain",
        "deviceMac": DEVICE_MAC_ADDR,
        "calibrate":false,
        "group":false,
        "slidePosition":50, //0~100
        "battery":100,
        "timeOfSample": 123456789
    }
}

Motion Sensor

Key Name Value Type Description
eventType String the type of events
eventVersion String the current event version
context Object the detail info of the event
deviceType String the type of the device
deviceMac String the MAC address of the device
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
timeOfSample Long the time stamp when the event is sent 
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoPresence",
        "deviceMac": DEVICE_MAC_ADDR,
        "detectionState": "NOT_DETECTED",
        "timeOfSample": 123456789
    }
}

Contact Sensor

Key Name Value Type Description
eventType String the type of events
eventVersion String the current event version
context Object the detail info of the event
deviceType String the type of the device
deviceMac String the MAC address of the device
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
doorMode String when the enter or exit mode gets triggered, "IN_DOOR" or "OUT_DOOR" is returned
brightness String the level of brightness, can be "bright" or "dim"
openState String the state of the contact sensor, can be "open" or "close" or "timeOutNotClose"
timeOfSample Long the time stamp when the event is sent 
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoContact",
        "deviceMac": DEVICE_MAC_ADDR,
        "detectionState": "NOT_DETECTED",
        "doorMode":"OUT_DOOR",
        "brightness": "dim",
        "openState": "open",
        "timeOfSample": 123456789
    }
}

Meter

Key Name Value Type Description
eventType String the type of events
eventVersion String the current event version
context Object the detail info of the event
deviceType String the type of the device
deviceMac String the MAC address of the device
temperature Float the current temperature reading
scale String the current temperature unit being used
humidity Integer the current humidity reading in percentage
timeOfSample Long the time stamp when the event is sent 
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoMeter",
        "deviceMac": DEVICE_MAC_ADDR,
        "temperature": 22.5,
        "scale": "CELSIUS",
        "humidity": 31,
        "timeOfSample": 123456789
    }
}

Meter Plus

Key Name Value Type Description
eventType String the type of events
eventVersion String the current event version
context Object the detail info of the event
deviceType String the type of the device
deviceMac String the MAC address of the device
temperature Float the current temperature reading
scale String the current temperature unit being used
humidity Integer the current humidity reading in percentage
timeOfSample Long the time stamp when the event is sent 
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoMeter",
        "deviceMac": DEVICE_MAC_ADDR,
        "temperature": 22.5,
        "scale": "CELSIUS",
        "humidity": 31,
        "timeOfSample": 123456789
    }
}

Outdoor Meter

Key Name Value Type Description
eventType String the type of events
eventVersion String the current event version
context Object the detail info of the event
deviceType String the type of the device
deviceMac String the MAC address of the device
temperature Float the current temperature reading
scale String the current temperature unit being used
humidity Integer the current humidity reading in percentage
timeOfSample Long the time stamp when the event is sent 
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoIOSensor",
        "deviceMac": DEVICE_MAC_ADDR,
        "temperature": 22.5,
        "scale": "CELSIUS",
        "humidity": 31,
        "timeOfSample": 123456789
    }
}

Lock

Key Name Value Type Description
eventType String the type of events
eventVersion String the current event version
context Object the detail info of the event
deviceType String the type of the device
deviceMac String the MAC address of the device
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
timeOfSample Long the time stamp when the event is sent 
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoLock",
        "deviceMac": DEVICE_MAC_ADDR,
        "lockState": "LOCKED",
        "timeOfSample": 123456789
    }
}

Indoor Cam

Key Name Value Type Description
eventType String the type of events
eventVersion String the current event version
context Object the detail info of the event
deviceType String the type of the device
deviceMac String the MAC address of the device
detectionState String the detection state of the device, "DETECTED" stands for motion is detected
timeOfSample Long the time stamp when the event is sent 
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoCamera",
        "deviceMac": DEVICE_MAC_ADDR,
        "detectionState": "DETECTED",
        "timeOfSample": 123456789
    }
}

Pan/Tilt Cam

Key Name Value Type Description
eventType String the type of events
eventVersion String the current event version
context Object the detail info of the event
deviceType String the type of the device
deviceMac String the MAC address of the device
detectionState String the detection state of the device, "DETECTED" stands for motion is detected
timeOfSample Long the time stamp when the event is sent 
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoPanTiltCam",
        "deviceMac": DEVICE_MAC_ADDR,
        "detectionState": "DETECTED",
        "timeOfSample": 123456789
    }
}

Color Bulb

Key Name Value Type Description
eventType String the type of events
eventVersion String the current event version
context Object the detail info of the event
deviceType String the type of the device
deviceMac String the MAC address of the device
powerState String the current power state of the device, "ON" or "OFF"
brightness Integer the brightness value, range from 1 to 100
color String the color value, in the format of RGB value, "255:255:255"
colorTemperature Integer the color temperature value, range from 2700 to 6500
timeOfSample Long the time stamp when the event is sent 
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoBulb",
        "deviceMac": DEVICE_MAC_ADDR,
        "powerState": "ON",
        "brightness": 10,
        "color":"255:245:235",
        "colorTemperature":3500,
        "timeOfSample": 123456789
    }
}

LED Strip Light

Key Name Value Type Description
eventType String the type of events
eventVersion String the current event version
context Object the detail info of the event
deviceType String the type of the device
deviceMac String the MAC address of the device
powerState String the current power state of the device, "ON" or "OFF"
brightness Integer the brightness value, range from 1 to 100
color String the color value, in the format of RGB value, "255:255:255"
timeOfSample Long the time stamp when the event is sent 
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoStrip",
        "deviceMac": DEVICE_MAC_ADDR,
        "powerState": "ON",
        "brightness": 10,
        "color": "255:245:235",
        "timeOfSample": 123456789
    }
}

Plug Mini (US)

Key Name Value Type Description
eventType String the type of events
eventVersion String the current event version
context Object the detail info of the event
deviceType String the type of the device
deviceMac String the MAC address of the device
powerState String the current power state of the device, "ON" or "OFF"
timeOfSample Long the time stamp when the event is sent 
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoPlugUS",
        "deviceMac": DEVICE_MAC_ADDR,
        "powerState": "ON",
        "timeOfSample": 123456789
    }
}

Plug Mini (JP)

Key Name Value Type Description
eventType String the type of events
eventVersion String the current event version
context Object the detail info of the event
deviceType String the type of the device
deviceMac String the MAC address of the device
powerState String the current power state of the device, "ON" or "OFF"
timeOfSample Long the time stamp when the event is sent 
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoPlugJP",
        "deviceMac": DEVICE_MAC_ADDR,
        "powerState": "ON",
        "timeOfSample": 123456789
    }
}

Robot Vacuum Cleaner S1

Key Name Value Type Description
eventType String the type of events
eventVersion String the current event version
context Object the detail info of the event
deviceType String attributes of the context object. the type of the device
deviceMac String attributes of the context object. the MAC address of the device
workingStatus String attributes of the context object. the working status of the device. StandBy, Clearing, Paused, GotoChargeBase, Charging, ChargeDone, Dormant, InTrouble, InRemoteControl, or InDustCollecting
onlineStatus String attributes of the context object. the connection status of the device. online or offline
battery Integer attributes of the context object. the battery level, range from 0 to 100
timeOfSample Long attributes of the context object. the time stamp when the event is sent 
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoSweeper",
        "deviceMac": DEVICE_MAC_ADDR,
        "workingStatus"："StandBy",
        "onlineStatus": "online",
        "battery": 100,
        "timeOfSample": 123456789
    }
}

Robot Vacuum Cleaner S1 Plus

Key Name Value Type Description
eventType String the type of events
eventVersion String the current event version
context Object the detail info of the event
deviceType String attributes of the context object. the type of the device
deviceMac String attributes of the context object. the MAC address of the device
workingStatus String attributes of the context object. the working status of the device. StandBy, Clearing, Paused, GotoChargeBase, Charging, ChargeDone, Dormant, InTrouble, InRemoteControl, or InDustCollecting
onlineStatus String attributes of the context object. the connection status of the device. online or offline
battery Integer attributes of the context object. the battery level, range from 0 to 100
timeOfSample Long attributes of the context object. the time stamp when the event is sent 
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoSweeperPlus",
        "deviceMac": DEVICE_MAC_ADDR,
        "workingStatus"："StandBy",
        "onlineStatus": "online",
        "battery": 100,
        "timeOfSample": 123456789
    }
}

Ceiling Light

Key Name Value Type Description
eventType String the type of events
eventVersion String the current event version
context Object the detail info of the event
deviceType String attributes of the context object. the type of the device
deviceMac String attributes of the context object. the MAC address of the device
powerState String attributes of the context object. ON/OFF state
brightness Integer attributes of the context object. the brightness value, range from 1 to 100
colorTemperature Integer attributes of the context object. the color temperature value, range from 2700 to 6500
timeOfSample Long attributes of the context object. the time stamp when the event is sent 
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoCeiling",
        "deviceMac": DEVICE_MAC_ADDR,
        "powerState": "ON",
        "brightness": 10,
        "colorTemperature": 3500,
        "timeOfSample": 123456789
    }
}

Ceiling Light Pro

Key Name Value Type Description
eventType String the type of events
eventVersion String the current event version
context Object the detail info of the event
deviceType String attributes of the context object. the type of the device
deviceMac String attributes of the context object. the MAC address of the device
powerState String attributes of the context object. ON/OFF state
brightness Integer attributes of the context object. the brightness value, range from 1 to 100
colorTemperature Integer attributes of the context object. the color temperature value, range from 2700 to 6500
timeOfSample Long attributes of the context object. the time stamp when the event is sent 
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoCeilingPro",
        "deviceMac": DEVICE_MAC_ADDR,
        "powerState": "ON",
        "brightness": 10,
        "colorTemperature": 3500,
        "timeOfSample": 123456789
    }
}

Keypad

Key Name Value Type Description
eventType String the type of events
eventVersion String the current event version
context Object the detail info of the event
deviceType String attributes of the context object. the type of the device
deviceMac String attributes of the context object. the MAC address of the device
eventName String attributes of the context object. the name of the command being sent
commandId String attributes of the context object. the command id
result String attributes of the context object. the result of the command. success, failed, or timeout. timeout duration is 1 minute
timeOfSample Long attributes of the context object. the time stamp when the event is sent
Create a passcode
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoKeypad",
        "deviceMac": DEVICE_MAC_ADDR,
        "eventName": "createKey",
        "commandId": "CMD-1663558451952-01",
        "result": "success",
        "timeOfSample": 123456789
    }
}
Delete a passcode
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoKeypad",
        "deviceMac": DEVICE_MAC_ADDR,
        "eventName": "deleteKey ",
        "commandId": "CMD-1663558451952-01",
        "result": "success",
        "timeOfSample": 123456789
    }
}

Keypad Touch

Key Name Value Type Description
eventType String the type of events
eventVersion String the current event version
context Object the detail info of the event
deviceType String attributes of the context object. the type of the device
deviceMac String attributes of the context object. the MAC address of the device
eventName String attributes of the context object. the name of the command being sent
commandId String attributes of the context object. the command id
result String attributes of the context object. the result of the command. success, failed, or timeout. timeout duration is 1 minute
timeOfSample Long attributes of the context object. the time stamp when the event is sent
Create a passcode
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoKeypadTouch",
        "deviceMac": DEVICE_MAC_ADDR,
        "eventName": "createKey",
        "commandId": "CMD-1663558451952-01",
        "result": "success",
        "timeOfSample": 123456789
    }
}
Delete a passcode
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoKeypadTouch",
        "deviceMac": DEVICE_MAC_ADDR,
        "eventName": "deleteKey ",
        "commandId": "CMD-1663558451952-01",
        "result": "success",
        "timeOfSample": 123456789
    }
}

Hub 2

Key Name Value Type Description
eventType String the type of events
eventVersion String the current event version
context Object the detail info of the event
deviceType String attributes of the context object. the type of the device
deviceMac String attributes of the context object. the MAC address of the device
temperature Float the current temperature reading
humidity Integer the current humidity reading in percentage
lightLevel Integer the level of illuminance of the ambience light, 1~20
scale String the current temperature unit being used
timeOfSample Long attributes of the context object. the time stamp when the event is sent 
{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoHub2",
        "deviceMac": DEVICE_MAC_ADDR,
        "temperature":13,
        "humidity":18,
        "lightLevel": 19,
        "scale": "CELSIUS",
        "timeOfSample": 123456789
    }
}

About

SwitchBot Open API Documents

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published