Scaledrone API v3 socket protocol

This page describes the Scaledrone API v3 socket protocol. If you wish to push data over the REST API, it's easier to use the REST API.

Scaledrone uses WebSocket and other fallback technologies for continuous connections. For most non-browser environments WebSockets should be the choice of technology. This is why this page will focus on WebSocket connections, if you do wish to use another method of connection please contact support for additional guidance.

WebSocket

The base URL against which the connection should be initiated is wss://api.scaledrone.com/v3/websocket.

After connecting to the server, the client needs to go through series of JSON message exchanges.

Each JSON sent and received message needs to include one or more of the following properties: type, callback or error.

The type property will define the purpose of the message.

Callbacks

The callback property will define a reference number for the message when sent to the server a message will be sent back containing the same callback ID identifying the targeted message.

Each client needs to start it's own callback integer sequence from 0 to n. The first message would have a callback of 0, the second of 1 and so on.

Errors

When receiving a message with an error property something went wrong. When the same message also has a callback property the error is targeted to a specific message.

Tips & Tricks

A handy trick to see the protocol in action is to observe the Scaledrone JavaScript client WebSocket frames. You can do so in Chrome by opening the developer tools and navigating to Network → WS tab → websocket request → frames tab.

Protocol

Handshake process

Each client needs to start the connection by initiating a handshake process immediately after opening the WebSocket connection. The handshake process will define which channel the client is connecting.

{
  "type": "handshake",
  "channel": "3xmbUiTsqTzukjf7",
  "callback": 0,
  "client_data": {"data": 123}
}

{
  "callback": 0,
  "client_id": "hCzb:J2Fn",
  "version": "1.7.3"
}

{
  "callback": 0,
  "error": "Channel does not exist"
}

Subscribe process

The subscribing process is used to start listening to messages from a room.

{
  "type": "subscribe",
  "room": "myRoom1",
  "callback": 1
}

{
  "callback": 1
}

{
  "callback": 1,
  "error": "Unable to subscribe to room"
}

Authentication process

When using JSON Web Token authentication the authentication, process will need to be passed.

{
  "type": "authenticate",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "callback": 2
}

{
  "callback": 2
}

{
  "callback": 2,
  "error": "Invalid JWT"
}

Message publishing

{
  "type": "publish",
  "room": "myRoom1",
  "message": "Hello world"
}

{
  "type": "publish",
  "room": "myRoom1",
  "client_id": "hCzb:J2Fn",
  "message": "Hello world"
}

Observable events

{
  "type": "observable_members",
  "room": "observable-room",
  "data": [{"id":"gIPLr76Qbi:LPj7mm9cY0"},{"id":"h0zbhCzb:J1WnJ2Fn"}]
}

{
  "type": "observable_member_join",
  "room": "observable-room",
  "data": {"id":"gIPLr76Qbi:LPj7mm9cY0"}
}

{
  "type": "observable_member_leave",
  "room": "observable-room",
  "data": {"id":"gIPLr76Qbi:LPj7mm9cY0"}
}

Message History (in beta testing)

To receive history from a room, the user must first turn on message history for the channel from the dashboard. After enabling it the user can ask for up to 100 of the latest messages from a room when subscribing.

If the JWT authentication defines a lower number of history items than what the user is asking for themselves, the lower number will be used.

The messages are returned with an index parameter indicating their order. You might receive messages in a different order than 0..n. It's up to the API client to make sure they are delivered to the user in that order.

{
  "id": "5mwlEafeEZ",
  "timestamp": 1528814485,
  "type": "history_message",
  "room": "feed",
  "client_id": "25OyQAjAn9:OBoxyMU7jJ",
  "message": {"feedMessage": "Hey there!", "color": "#c586cc"},
  "index": 45
}