Filter results by

WebSockets API

By using WebSockets, you can set up a connection between ARTIK cloud services and compatible devices or applications to receive and/or send messages in real-time.

There are three types of WebSockets: Firehose, event feed, and device channel. Your application uses a Firehose WebSocket to listen to messages sent by the source devices that the application monitors. It would likewise use an event feed to receive updates on the status of devices, such as when they are enabled, modified, or deleted.

You would use a device channel WebSocket to receive messages targeted to your applications or devices. The device channel WebSocket also allows the applications or devices to send messages back to ARTIK cloud services.

See WebSocket errors for a list of error codes that can be returned for WebSockets.

Endpoints

API calls (with access token)

1
wss://api.artik.cloud/v1.1

Authentication (to get access token)

1
https://accounts.artik.cloud

WebSockets channels

Firehose WebSocket

WebSocket /live

The Firehose WebSocket is primarily used by applications with monitoring functionalities. This call sets up a one-directional data connection from ARTIK cloud services to a WebSocket client. The application, as the client, listens in real-time for any new messages sent to ARTIK cloud services by the specified source devices.

Messages received at this WebSocket endpoint are not necessarily ordered based on the ts field.

Request parameters

Parameter Description
Authorization Access token (user, device, or application token)
sdids (Optional) Comma-separated list of source device IDs. Accepts a single device ID.
sdtids (Optional) Comma-separated list of source device type IDs. Accepts a single device type ID.
uid User ID of the target stream. Optional for single device ID and single device type ID.
includeSharedDevices (Optional) Boolean (true/false). Include shared devices (default: false). Only applies when connecting per user (with uid).

You can use different URL query parameter combinations to get messages by device, by device type, or by user.

Combination Required Parameters Description
Get by devices sdids, uid, Authorization uid is optional for a single device ID. Receive messages from the devices specified by sdids. Passing a user token returns messages from devices owned by that user. Passing an application token returns messages from devices to which the application has been granted READ permission.
Get by device type sdtids, uid, Authorization uid is optional for a single device type ID. Receive messages from devices with the device type specified by sdtids. Passing a user token returns messages from devices owned by that user. Passing an application token returns messages from devices to which the application has been granted READ permission.
Get by user uid, Authorization Receive messages from devices owned by the user specified by uid. Passing an application token returns messages from devices to which the application has been granted READ permission.

We do not support "Get by device type" when a device token is provided as the access token.

For better performance, we suggest being as specific as possible when passing API call parameters. For example, the "Get by devices" combination returns the result more quickly than the "Get by user" combination.

In the following example we use Tyrus, a Java API for WebSockets suitable for web applications. We listen to the messages sent to ARTIK cloud services by the two source devices. In this specific example, the provided access token could be an application token or a user token.

Example

1
java -jar tyrus-client-cli-1.3.3.jar "wss://api.artik.cloud/v1.1/live?sdids=12345,6789&uid=10022&Authorization=bearer+1c20060d9b9f4ad09ee16919a45c71b7"

In the below example, the client receives a copy of the message that one of the source devices sends to ARTIK cloud services.

Example message received by client

1
2
3
4
5
6
7
8
9
10
11
{
  "sdtid":"nike_fuelband",
  "data":{
    "stepCount":5000
  },
  "mid":"c7f88d4367394fb696eee413666c83d9",
  "ts":1377793344153,
  "cts":1377793344153,
  "uid":"10022",
  "sdid":"12345"
} 

Ping

ARTIK cloud services send a ping every 30 seconds to the client. If a ping is not received, the connection has stalled and the WebSocket client must reconnect.

Example ping message sent by server

1
2
3
{
  "type": "ping"
}         

Event feed WebSocket

1
WebSocket /events

Like the Firehose WebSocket, this call sets up a one-directional data connection from ARTIK cloud services to a WebSocket client. The application, as the client, listens in real-time for events sent to ARTIK cloud services that pertain to the specified source devices.

Request parameters

Parameter Description
authorization Access token (user, device, or application token)
uid (Optional) User ID of the target stream. If not specified, the uid implied in the access token is assumed.
did (Optional) Device ID for which to receive events.
dids (Optional) Comma-separated list of device IDs. Specifies a list of devices for which to receive events.
events (Optional) Comma-separated list of event names or event names with wildcard (e.g., device.*, user.profile.updated). If not specified, events = * is assumed.

Supported events

Event name Description Occurs when
device.new A new device has been created. After a device is created in My ARTIK Cloud or using the POST /devices API.
device.connected A device has been enabled. After device.new (since it is enabled by default), or when device is switched back from disconnected state using the PUT /devices/<deviceID> API.
device.updated A device has been modified. After a device was modified in My ARTIK Cloud or using the PUT /devices/<deviceID> API.
device.disconnected A device has been disabled. After a device has been marked as disabled using the PUT /devices/<deviceID> API and before device.deleted.
device.deleted A device has been deleted. After a device is deleted from My ARTIK Cloud or using the DELETE /devices/<deviceID> API.
user.profile.updated A user's profile has been modified. After the user's profile information is changed.
device.status.online A device went online. After a device makes an active connection to an API with presence support (WebSockets, MQTT, CoAP), or when it gets a ping while actively connected.
device.status.offline A device went offline. After a device succesfully closes active connection from ARTIK cloud services (WebSockets, MQTT, CoAP), or the platform reports the active connection to the client was lost.

The behavior of device.status.online may be changed in the future.

Examples of event feeds

Listen for all supported events for a user ID:

1
wss://api.artik.cloud/v1.1/events?authorization=bearer+6fb02e864c1247ad9c3fcfeb5a94f913&uid=4ece85e077c945ebbdd3d0613ab659c0

Listen for all supported events pertaining to a device:

1
wss://api.artik.cloud/v1.1/events?authorization=bearer+6fb02e864c1247ad9c3fcfeb5a94f913&did=38d3590f705b461f8b4c71a6da80ff31&events=device.*

Listen for update and deletion events for a device:

1
wss://api.artik.cloud/v1.1/events?authorization=bearer+6fb02e864c1247ad9c3fcfeb5a94f913&did=38d3590f705b461f8b4c71a6da80ff31&events=device.updated,device.deleted

Listen for presence events (reported online and offline status) for a device:

1
wss://api.artik.cloud/v1.1/events?authorization=bearer+6fb02e864c1247ad9c3fcfeb5a94f913&uid=4ece85e077c945ebbdd3d0613ab659c0&dids=38d3590f705b461f8b4c71a6da80ff31,37a3475b9e284ae18d98f1071e691753&events=device.status.*

Example output

Below are examples of the JSON returned for events pertaining to the example device ID 38d3590f705b461f8b4c71a6da80ff31 used above.

The device just went online (via WebSockets, MQTT, or CoAP), or got a PING while actively connected:

1
2
3
4
5
6
7
8
{
  "event":"device.status.online",
  "ts":1475521086554,
  "data":{
    "uid":"4ece85e077c945ebbdd3d0613ab659c0", // Owner of the device
    "did":"38d3590f705b461f8b4c71a6da80ff31" // Device that is actively connected
  }
}

The device was deleted:

1
2
3
4
5
6
7
8
9
10
{
  "event": "device.deleted",
  "ts": 1475521114668,
  "data": {
    "uid": "4ece85e077c945ebbdd3d0613ab659c0", // Owner of the device
    "aid": "068fa23cc68b40bbb9df68ff24b3de5e", // Application ID through which the device was deleted
    "did": "38d3590f705b461f8b4c71a6da80ff31", // Device that was deleted
    "dtid": "dtf9d52ea094424f4da00d802aa9ec856e" // Device's device type ID
  }
}

Device channel WebSocket

WebSocket /websocket

This call opens a data connection between ARTIK cloud services and a device or device list.

Available URL query parameters

Parameter Description
ack (Optional) Boolean (true/false). WebSocket returns ACK messages for each message sent by client. If not specified, defaults to false.

Register a device

All client applications, including device proxies, must register after opening the connection. Otherwise client messages will be discarded and clients will not be sent messages.

Multiple messages can be sent to register more than one device. These devices can then send and receive messages over a single device channel WebSocket.

If the client app does not register within 30 seconds of opening the connection, the WebSocket will be closed automatically.

Example registration message sent by client

1
2
3
4
5
6
{
  "sdid": "DFKK234-JJO5",
  "Authorization": "bearer d77054a9b0874ba884499eef7768b7b9",
  "type": "register",
  "cid": "1234567890"
}         

Request body parameters

Parameter Description
sdid Source device ID.
Authorization Access token with READ and WRITE access to sdid.
type Type of message. Can be register, unregister, or list.
cid (Optional) Client (application) ID. Can be used when ack=true.

Example ACK message

1
2
3
4
5
6
7
{
  "data":{
    "code":"200",
    "message":"OK",
    "cid":"1234567890"
  }
}

List registered devices

This message type returns a list of devices currently registered on the WebSocket. The devices are listed by sdid.

Example list message sent by client

1
2
3
4
{
  "type": "list",
  "cid": "1234567890"
}         

Example ACK message

An ACK message is returned regardless of the ack value.

1
2
3
4
5
6
7
8
9
10
11
{
  "data":{
    "code":"200",
    "message":[
      "DFKK234-JJO5", 
      "DEVICE_ID_X",
      "DEVICE_ID_Y"
    ],
    "cid":"1234567890"
  }
}

Unregister a device

A message can be sent to unregister a device identified by sdid. This removes the device from the list of registered devices on the WebSocket.

Example unregister message sent by client

1
2
3
4
5
{
  "sdid": "DFKK234-JJO5",
  "type": "unregister",
  "cid": "1234567890"
}         

Example ACK message

1
2
3
4
5
6
7
{
  "data":{
    "code":"200",
    "message":"OK",
    "cid":"1234567890"
  }
}

If the last remaining device on the WebSocket is unregistered, the WebSocket connection will be disconnected.

Example ACK message (last device unregistered)

1
2
3
4
5
6
7
{
  "data":{
    "code":"400",
    "message":"No registered device",
    "cid":"1234567890"
  }
}

Example error message

1
2
3
4
5
6
7
{
  "error":{
    "code":"404",
    "message":"Device(s) not found",
    "cid":"errorCid"
  }
}

Ping

ARTIK cloud services send a ping every 30 seconds to the client. If a ping is not received, the connection has stalled and the client must reconnect.

Example ping message sent by server

1
2
3
{
  "type": "ping"
}         

Sending messages

You can send a message with

  • type as "message" to ARTIK cloud services.
  • type as "action" to another device. You must specify ddid in your request.

Sending a message via WebSockets differs from performing the REST call in that cid can be included. Responses from ARTIK cloud services include cid to facilitate client side validations.

Example request

1
2
3
4
5
6
7
8
{
  "sdid": "d597a8ffb3364f98a904515cbc574cb2",
  "cid":"1234567890", 
  "type": "message",
  "data":{
    "someField": "someValue"
  }
}

Request body parameters

Parameter Description
sdid (Optional) Source device ID. The ID of one of the devices registered on the device channel WebSocket.
data Data. Can be a simple text field, or a JSON document.
ddid (Optional) Destination device ID. Must be used when sending an Action to another device. Otherwise, only sends to ARTIK cloud services to store.
ts (Optional) Message timestamp. Must be a valid time: past time, present or future up to the current server timestamp grace period. Current time if omitted.
type Type of message: message or action (default: message).
cid (Optional) Client (application) ID. Can be used when ack=true. ARTIK cloud services will return cid (in addition to mid) in its ACK messages to facilitate client side validations. This helps to clarify which response is for which message.

Example ACK message

1
2
3
4
5
6
{
  "data":{
    "mid": "6d002024824746649766743582c9f005", 
    "cid": "1234567890"
  }
}

Receiving messages

Devices connected to the device channel WebSocket receive messages that contain their corresponding ddid (destination device ID) and have type as "action".

Example message received by client

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "ddid": "<destination device ID = this client device ID>",
  "mid": "<message ID>",
  "type": "action",
  "data": {
    "actions": [
      {
        "name": "setOn",
        "parameters": {}
      }
    ]
  }
}    

WebSocket errors

Code Error message Condition
400 Bad Request Invalid JSON
400 Missing sdid value Missing sdid
400 Missing ddid value Missing ddid
400 Registration timeout Client connects and does not register
400 Invalid ts value Invalid timestamp or timestamp less than 0
400 Invalid ts value (in future) Timestamp greater than FUTURE_GRACE_PERIOD
401 Please provide a valid authorization header Missing auth token
401 Device not registered Unregistered sdid
403 You do not have the right permission: devices No WRITE permission
403 Wrong cid Mismatch cid
404 Device(s) not found sdid not found for unregistration
429 DAILY rate limit exceeded Rate limit exceeded
429 Plan quota exceeded for organization <organizationID>. Reason: Monthly message limit. Monthly quota exceeded
413 Plan quota exceeded for organization <organizationID>. Reason: Max payload size limit. Payload size exceeded
400 Quota validation error for organization <organizationID>. Reason: Plan limits have not been set. Organization quota plan has not been configured