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!
  model: LightModel!
  currentState: BuildingLightState!
}

type LightModel {
  id: ID!
  brand: String!
  name: String!
  moduleNameId: Int!
  lifetime: Int!
  hasRatio: Boolean!
  fanSpeedSteps: Int!
  idlePowerConsumptionPerHour?: Float
  customPowerConsumptionAllowed: Boolean!
  temperatureMin: Int!
  temperatureMax: Int!
}

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

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

Mutations

Controlling individual light

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

Changes state of individual light

Controling group of lights

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

Changes the state for all lights in the group

Controlling the room

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

Changes the state for all lights in the room

Controlling the floor

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

Changes the state for all lights in the floor

Controlling the building

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

Changes the state for all lights in the building

Activating the room scene

mutation{
  applyRoomScene(
    roomSceneId: String!
  )
}

Restores the scene that was saved for the room

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

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

Header

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

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}

Event types

• STATUSCHANGE - device status changed: turned on/off, brightness change, etc.