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.
Handshake
Property |
Datatype |
Example value |
Required |
Comment |
type |
string |
handshake |
✓ |
|
channel |
string |
channel_id |
✓ |
Channel ID from dashboard |
callback |
integer |
0 |
✓ |
Unique integer to reference this message |
client_data |
json |
{"data": 123} |
✗ |
|
{
"type": "handshake",
"channel": "3xmbUiTsqTzukjf7",
"callback": 0,
"client_data": {"data": 123}
}
Handshake callback
Property |
Datatype |
Example value |
Required |
Comment |
callback |
integer |
0 |
✓ |
Callback ID from request |
client_id |
string |
hCzb:J2Fn |
✗ |
UID to identify the client |
version |
string |
1.7.3 |
✗ |
Scaledrone internal version |
error |
string |
Channel does not exist |
✗ |
Error if handshake failed |
{
"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.
Subscribe
Property |
Datatype |
Example value |
Required |
Comment |
type |
string |
subscribe |
✓ |
|
room |
string |
myRoom1 |
✓ |
Room name |
callback |
integer |
1 |
✓ |
Unique integer to reference this message |
history_count |
integer |
25 |
✗ |
The number of messages to retrieve from the room's history |
{
"type": "subscribe",
"room": "myRoom1",
"callback": 1
}
Subscribe callback
Property |
Datatype |
Example value |
Required |
Comment |
callback |
integer |
1 |
✓ |
Callback ID from request |
error |
string |
Unable to subscribe to room |
✗ |
Error when subscribing to room |
{
"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.
Authenticate
Property |
Datatype |
Example value |
Required |
Comment |
type |
string |
authenticate |
✓ |
|
token |
string |
eyJ0eXAiOiJ... |
✓ |
JSON Web Token |
callback |
integer |
2 |
✓ |
Unique integer to reference this message |
{
"type": "authenticate",
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"callback": 2
}
Authenticate callback
Property |
Datatype |
Example value |
Required |
Comment |
callback |
integer |
2 |
✓ |
Callback ID from request |
error |
string |
Invalid JWT |
✗ |
Error with authentication |
{
"callback": 2
}
{
"callback": 2,
"error": "Invalid JWT"
}
Message publishing
Publish
Property |
Datatype |
Example value |
Required |
Comment |
type |
string |
publish |
✓ |
|
room |
string |
myRoom1 |
✓ |
Room name |
message |
JSON/string/number |
Hello world |
✓ |
Message sent to the room |
{
"type": "publish",
"room": "myRoom1",
"message": "Hello world"
}
Publish
Property |
Datatype |
Example value |
Required |
Comment |
type |
string |
publish |
✓ |
|
room |
string |
myRoom1 |
✓ |
Room name |
client_id |
string |
hCzb:J2Fn |
✗ |
UID of the sender. If undefined message was sent using the REST API |
message |
JSON/string/number |
Hello world |
✓ |
Message sent to the room |
{
"type": "publish",
"room": "myRoom1",
"client_id": "hCzb:J2Fn",
"message": "Hello world"
}
Observable events
Members
Property |
Datatype |
Example value |
Required |
Comment |
type |
string |
observable_members |
✓ |
|
room |
string |
observable-room |
✓ |
Room name |
data |
JSON |
[{"id":"gIPLr76Qbi:LPj7mm9cY0"},{"id":"h0zbhCzb:J1WnJ2Fn"}] |
✓ |
Array of users in the observable room, including the client themselves |
{
"type": "observable_members",
"room": "observable-room",
"data": [{"id":"gIPLr76Qbi:LPj7mm9cY0"},{"id":"h0zbhCzb:J1WnJ2Fn"}]
}
Member joins
Property |
Datatype |
Example value |
Required |
Comment |
type |
string |
observable_member_join |
✓ |
|
room |
string |
observable-room |
✓ |
Room name |
data |
JSON |
{"id":"gIPLr76Qbi:LPj7mm9cY0"} |
✓ |
Data of the connected user |
{
"type": "observable_member_join",
"room": "observable-room",
"data": {"id":"gIPLr76Qbi:LPj7mm9cY0"}
}
Member leaves
Property |
Datatype |
Example value |
Required |
Comment |
type |
string |
observable_member_leave |
✓ |
|
room |
string |
observable-room |
✓ |
Room name |
data |
JSON |
{"id":"gIPLr76Qbi:LPj7mm9cY0"} |
✓ |
ID of the leaving user |
{
"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.
History Message
Property |
Datatype |
Example value |
Required |
Comment |
type |
string |
history_message |
✓ |
|
id |
string |
6YJ7WoiDgs |
✓ |
UID to identify the message |
client_id |
string |
hCzb:J2Fn |
✓ |
UID to identify the client |
index |
integer |
0 |
✓ |
Index of the returned message. Used for maintaining the order of messages from the history. Message with index 0 is the latest and should be delivered to the user first. |
message |
JSON/string/number |
Hello world |
✓ |
Message sent to the room |
room |
string |
myRoom1 |
✓ |
Room name |
timestamp |
integer |
1528814484 |
✓ |
Unix timestamp when the message was originally sent |
{
"id": "5mwlEafeEZ",
"timestamp": 1528814485,
"type": "history_message",
"room": "feed",
"client_id": "25OyQAjAn9:OBoxyMU7jJ",
"message": {"feedMessage": "Hey there!", "color": "#c586cc"},
"index": 45
}