NAV
JS cURL

Introduction

Welcome to the WiZ Pro API! You can use our API to retrieve building topology and control WiZ Devices.

We have language samples in Shell (cURL) and Javascript! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authorisation

Authorisation is based on OAuth protocol with PKCE extension enabled. Before start, you need to obtain clientId from WiZ and provide us with the redirectUri, which stands for the endpoint on your side that WiZ will use to redirect the user after the permission has been granted.

To initiate accounts linking you need to open the webpage with the URL

https://pro.wizconnected.com/dashboard/#/oauth/authorize?client_id=clientId&code_challenge=codeChallenge&code_challenge_method=S256

where clientId is the client ID provided by WiZ, codeChallenge is the encrypted code verifier value (used in authorisation code -> access token exchange), codeChallengeMethod is the method that was used for encrypting the codeChallenge (currently only S256 for SHA256 hashing (recommended) and Plain for passing without encryption are supported).

Obtaining token

To obtain accessToken and refreshToken using the authorizationCode use this code:

curl -X POST -d '{
  "grantType": "authorizationCode",
  "authorizationCode": "receivedAuthorizationCode",
  "clientId": "yourClientId",
  "codeVerifier": "yourCodeVerifier"
}' -H "Content-type: application/json" "https://api.pro.wizconnected.com/api/oauth/token"
const request = require("request");

request.post(
  "https://api.pro.wizconnected.com/api/oauth/token",
  {
    json: true,
    body: {
      grantType: "authorizationCode",
      authorizationCode: "receivedAuthorizationCode",
      clientId: "yourClientId",
      codeVerifier: "yourCodeVerifier"
    }
  },
  (error, response, body) => {
    console.log(body);
  }
);

To run authorization flow open the page with URL: https://pro.wizconnected.com/dashboard/#/oauth/authorize?client_id=yourclientid&code_challenge=codeChallenge&code_challenge_method=S256&redirect_uri=https://yourdomain.com

After signing in and confirming the access to the building you will receive the callback with authorization_code.

Example: https://yourdomain.com/?code=712cf1fd-3fd2-4b24-beb4-5bd980ad0c24&expires_at=2019-09-19T11:10:59.084Z

This code then can be used to obtain accessToken and refreshToken using the call to the /oauth/token

You will receive the reply similar to this one

{
  "accessToken": "d156d13cf7bed8364a6406cc5dd518f026d5ee9bde1db522750699bd7271ce77",
  "tokenType": "Bearer",
  "expiresAt": "2019-07-03T10:57:55.397Z",
  "refreshToken": "c2e7c44dfc5a7dd75d773a4d6834d5a3c85984af9735b7754a775da54a6827a6"
}

Refreshing tokens

To refresh accessToken and refreshToken please use this code:

curl -X POST -d '{
  "grantType": "refreshToken",
  "refreshToken": "yourRefreshToken"
}' -H "Content-type: application/json"
"https://api.pro.wizconnected.com/api/oauth/token"
const request = require("request");

request.post(
  "https://api.pro.wizconnected.com/api/oauth/token",
  {
    json: true,
    body: {
      grantType: "refreshToken",
      refreshToken:
        "6631e841044c06e570105b99adc2390d00fa1a0297c8e006113165d39393dc61"
    }
  },
  (error, response, body) => {
    console.log(body);
  }
);

accessToken lifetime is limited to 3 hours.

To refresh the token please call the /oauth/token endpoint with "grantType":"refreshToken"

Using API

WiZ Pro API leverages GraphQL to run queries for obtaining data and controlling the lights. Number of libraries exist for different languages. It's also possible to run queries using raw POST requests.

You must include authorisation header with access token in each request to GraphQL API Authorization: Bearer {{accessToken}}

Endpoint URL: https://api.pro.wizconnected.com/api/graphql

GraphQL Schema

type BuildingMetaData {
  id: ID!
  name: String!
}

type BuildingTopology {
  id: ID!
  name: String!
  floors(ids: [String!]): [BuildingFloor!]!
}

type BuildingFloor {
  id: ID!
  name: String!
  rooms: [BuildingRoom!]!
}

type BuildingRoom {
  id: ID!
  name: String!
  favorite1: FavoriteState!
  favorite2: FavoriteState!
  favorite3: FavoriteState!
  favorite4: FavoriteState!
  roomScenes: [BuildingRoomScene!]!
  lights: [BuildingLight!]!
  groups: [BuildingGroup!]!
}

type BuildingLight {
  id: ID!
  name: String!
  mac: String!
  currentState: BuildingLightState!
}

type BuildingLightState {
  r: Int
  g: Int
  b: Int
  cw: Int
  ww: Int
  dimming: Int
  sceneId: Int
  speed: Int
  ratio: Int
  state: Boolean
  temperature: Int
}

type BuildingGroup {
  id: ID!
  name: String!
  lights: [BuildingLight!]!
}

type BuildingRoomScene {
  id: ID!
  name: String!
}

union FavoriteState = FavoriteStateStatus | FavoriteStateScene | FavoriteStateCustomWhite | FavoriteStateCustomColor | FavoriteStateMoment

type FavoriteStateStatus {
  status: Boolean!
}

type FavoriteStateScene {
  sceneId: Int!
  specificDimming: Int
  speed: Int
}

type FavoriteStateCustomWhite {
  temperature: Int!
  dimming: Int!
}

type FavoriteStateCustomColor {
  r: Int!
  g: Int!
  b: Int!
  cw: Int!
  ww: Int!
  dimming: Int!
}

type FavoriteStateMoment {
  momentId: String!
}

input PilotingLightStateInput {
  r: Int
  g: Int
  b: Int
  cw: Int
  ww: Int
  dimming: Int
  sceneId: Int
  speed: Int
  ratio: Int
  state: Boolean
  temperature: Int
}

type Query {
  buildings: [BuildingMetaData!]!
  buildingTopology(buildingId: String!): BuildingTopology!
}

type Mutation {
  changeLightState(
    floorId: String!
    lightId: String!
    provider: String!
    mac: String
    state: PilotingLightStateInput!
  ): Boolean
  changeGroupState(
    floorId: String!
    groupId: String!
    state: PilotingLightStateInput!
  ): Boolean
  changeRoomState(
    floorId: String!
    roomId: String!
    provider: String!
    state: PilotingLightStateInput!
  ): Boolean
  applyRoomScene(roomSceneId: String!): Boolean
  changeFloorState(floorId: String!, state: PilotingLightStateInput!): Boolean
  changeBuildingState(
    buildingId: String!
    state: PilotingLightStateInput!
  ): Boolean
}

Schema exposes 2 queries and several mutations.

Queries:

  1. buildings - returns the list of buildings. Only ID and name of the building is returned from this query. Please use buildingTopology query to get the detailed information about the building
  2. buildingTopology - provided with building id it will return the building data according to the query. It's up to a developer to request full tree of data or only some fields that are relevant to the business needs.

Mutations:

  1. changeLightState - change the state of individual light
  2. changeGroupState - change the state of the group
  3. changeRoomState - change the state of the whole room
  4. changeFloorState - change the state of lights connected to the provided floor
  5. changeBuildingState - control all devices in the building
  6. applyRoomScene - activates the RoomScene in the room

Light state input

You need to pass the structure compliant with PilotingLightStateInput type providing the following fields:

  1. r - type Int, Red track value. Valid range: 0-255
  2. g - type Int, Green track value. Valid range: 0-255
  3. b - type Int, Blue track value. Valid range: 0-255
  4. cw - type Int, Cool White track value. Valid range: 0-255
  5. ww - type Int, Warm White track value. Valid range: 0-255
  6. dimming - type Int, Brightness value. Valid range: 10-100
  7. sceneId - type Int, one of predefined light modes. Valid range: 1-32. Full list
  8. speed - type Int, Speed of dynamic light modes (Ocean, Romance, Forest, etc). Valid range: 20-200
  9. ratio - type Int, Ratio for dual-zone devices. Valid range: 0-100
  10. state - type Boolean, State of the device. true - the device is turned on, false - the device is turned off
  11. temperature - type Int, CCT value, measured in Kelvins. Valid range depends on the product, common range is 2700-6500K

All control methods return Boolean value, indicating whether piloting was successful or not.

NB! If the light cannot apply the light mode (for example you ask the tunable white/CCT bulb to change color), it will apply the closest possible light mode (or at least will be turned).

You can find some examples in Examples section below.

Room scenes

BuildingRoom.roomScenes contains the list of scenes saved for this room. A scene for a room is a saved snapshot of the state of all the devices in the room. Scenes allow users to save finely tuned state for their room in order to restore it later easily by applying the scene to all the devices at once.

General information

curl -X POST \
  -d '{ "query": "{buildingTopology(buildingId:\"buiding_id\") { id name }}" }' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer access_token" \
  "https://api.pro.wizconnected.com/api/graphql"
const GraphQLClient = require("graphql-request").GraphQLClient;

const endpoint = "https://api.pro.wizconnected.com/api/graphql";
const client = new GraphQLClient(endpoint, {
  headers: {
    Authorization: "Bearer access_token"
  }
});

const query = `query($buildingId: String!) {
  buildingTopology(buildingId: $buildingId) {
    id
    name
  }
}`;

client
  .request(query, {
    buildingId: "building_id"
  })
  .then(data => console.log(data));

While it's possible to run raw POST queries to the GraphQL API and parse the response, it's usually way simpler to use one of the client libraries. They provide convenient way of passing GraphQL query, setting variables and processing the response.

All major languages have GraphQL client library (and some have more than one!).

You can find the list of the most popular client libs here

Javascript example shows how to use one of them (graphql-request) with WiZ Pro external API.

cURL example demonstrates how to call the GraphQL endpoint using command line tools.

Queries

Obtaining the list of all buildings

{
  buildings {
    id
    name
  }
}

Returns the list of buildings (id and name)

Obtaining building id and name

{
  buildingTopology(buildingId: "building_id") {
    id
    name
  }
}

Returns building ID and name

Parameter Description
building_id WiZ Pro Building ID

Obtaining building id + all floors with ids and names

{
  buildingTopology(buildingId: "building_id") {
    id
    floors {
      id
      name
    }
  }
}

Returns Building ID and array of all floors with names and IDs

Parameter Description
building_id WiZ Pro Building ID

Mutations

Controlling individual light

mutation{
  changeLightState(
    floorId: String!
    lightId: String!
    provider: String!
    mac: String
    state: PilotingLightStateInput!
  )
}

Changes state of individual light

Parameter Description Type Example
floorId Floor ID String "cjra8mkw7hy8y06381cg4dmw1"
lightId Light ID String "23232"
provider Should always be "WiZ" String "WiZ"
mac MAC Address of the bulb String "a8bb5031020a"
state Control settings LightStateInput {"state":true}

Controling group of lights

mutation{
  changeGroupState(
    floorId: String!
    groupId: String!
    state: PilotingLightStateInput!
  )
}

Changes the state for all lights in the group

Parameter Description Type Example
floorId Floor ID String "cjra8mkw7hy8y06381cg4dmw1"
groupId Group ID String "1113"
state Control settings LightStateInput {"state":true}

Controlling the room

mutation{
  changeRoomState(
    floorId: String!
    roomId: String!
    provider: String!
    state: PilotingLightStateInput!
  )
}

Changes the state for all lights in the room

Parameter Description Type Example
floorId Floor ID String "cjra8mkw7hy8y06381cg4dmw1"
roomId Room ID String "45323"
state Control settings LightStateInput {"state":true}

Controlling the floor

mutation{
  changeFloorState(floorId: String!, state: PilotingLightStateInput!)
}

Changes the state for all lights in the floor

Parameter Description Type Example
floorId Floor ID String "cjra8mkw7hy8y06381cg4dmw1"
state Control settings LightStateInput {"state":true}

Controlling the building

mutation{
  changeBuildingState(
    buildingId: String!
    state: PilotingLightStateInput!
  )
}

Changes the state for all lights in the building

Parameter Description Type Example
building Building ID String "cjos10ed7002o05p81e1lsi35"
state Control settings LightStateInput {"state":true}

Activating the room scene

mutation{
  applyRoomScene(
    roomSceneId: String!
  )
}

Restores the scene that was saved for the room

Parameter Description Type Example
roomSceneId RoomScene ID String "601"

Light modes

WiZ bulbs have different capabilities depending on the hardware configuration, but generally all devices could be split into several distinct groups:

  1. RGBTW - have Red, Green, Blue, Cool White and Warm White LEDs. These type of bulbs can support all the light modes provided by WiZ System
  2. TW - have Cool White and Warm White LEDs. Such devices support most static light modes + CCT control
  3. DW - have only Dimmable white LEDs. Such devices support only dimming, Wake up, Bedtime and Night light modes.

Summary of the light modes you can find in the following table

ID Name RGBTW TW DW Adjustable speed Adjustable dimming
1 Ocean
2 Romance
3 Sunset
4 Party
5 Fireplace
6 Cozy
7 Forest
8 Pastel Colors
9 Wake up
10 Bedtime
11 Warm white
12 Daylight
13 Cool white
14 Night light
15 Focus
16 Relax
17 True colors
18 TV Time
19 Plant growth
20 Spring
21 Summer
22 Fall
23 Deep dive
24 Jungle
25 Mojito
26 Club
27 Christmas
28 Halloween
29 Candlelight
30 Golden white
31 Pulse
32 Steampunk

Notifications

Introduction

In addition to controlling devices using GraphQL requests, WiZ Pro allows to subscribe to the notifications about device status changes.

When enabled, WiZ Pro will run REST POST calls to external endpoint with details about device status update, sensor events, etc. This data can be injected into some 3rd party solution to build dashboards, analytics reports, heat maps, etc.

To enable and configure the notifications:

  1. Navigate to WiZ Pro -> Settings -> Data export
  2. Flip the switch
  3. Enter Webhook URL (NB! only https endpoints supported)
  4. Press "Save"

Data format

Example - { floorId: 'cjra8mmk7hyew06385yib4d6b', type: 'STATUSCHANGE', payload: '...' }

Parameter Description Type Example
floorId ID of the floor that has the device triggered the message String ck0n5dftu0beu08182hrqvj6v
type Event type String STATUSCHANGE
payload JSON-encoded string containing the details about the event String Example

Payload - Status Change

Example - {"timestamp":1580366320,"mac":"a8bb50343f9a","connected":true,"rssi":-71,"state":true,"sceneId":0,"speed":0,"r":0,"g":0,"b":0,"c":0,"w":0,"colorTemperature":2700,"dimming":100,"consumptionRateInHour":0.0,"onSince":1580366320,"offSince":0}

Parameter Description Type Example
timestamp Event timestamp, UNIX time Long 1580366320
mac MAC address of the device String "a8bb50343f9a"
connected Connection status of the device: true if connected, false if not Boolean true
rssi WiFi signal strength, in negative dBm (for debugging purpose) Int -71
state Status of the Device : true if ON, false if OFF Boolean true
sceneId ID of the light mode being played Int 12
speed Transition speed in % Int 100
r Red component value Int 25
g Green component value Int 25
b Blue component value Int 25
c Cool white component value Int 25
w Warm white component value Int 25
colorTemperature Color temperature value, K Int 4200
dimming Brightness value, 0-100 Int 90
consumptionRateInHour How much does the device consume in 1h, W/h Float 9.6
onSince UNIX timestamp when the device was turned ON, 0 if it’s OFF now Long 1580366320
offSince UNIX timestamp when the device was turned OFF, 0 if it’s ON now Long 1580256641

Event types