Consuming Events via WebSocket

WebSocket allows you to connect external clients to Octave. Using WebSocket, external clients can subscribe to and receive events from Cloud Streams in Octave.

Establishing a WebSocket connection to Octave is a two-step process:

1. Request a session ID via an authenticated HTTP Post.
2. Use the session ID in the WSS URL.

A quick way to get started with WebSocket is to use an interactive command-line tool. In the following examples we'll use wscat, which is a Node.js-based tool. You can download and install wscat via npm using the following command:

npm install -g wscat

Requesting a Session ID

Get the user, company, and master token from the Master Token screen in the Octave dashboard.

Send a POST request from your client to https://octave-ws.sierrawireless.io/session to request a session. When using a restricted token, omit the X-Auth-User header. For example:

Request

$ curl -X "POST" https://octave-ws.sierrawireless.io/session \
  -H "X-Auth-User: <user>" \
  -H "X-Auth-Company: <company_name>" \
  -H "X-Auth-Token: <token>"

Response

{
  "head": {
    "ok": true,
    "status": 201,
    "errors": []
  },
  "body": {
    "id": "n2fBC9YeE6g.qsQNPOZfoSRP3brEY_9QWapawcjXl04Y"
  }
}

Establishing a WSS Connection

Take the session ID obtained above and add that to the wss:// URL used to connect. For example:

wscat -c "wss://octave-ws.sierrawireless.io/session/n2fBC9YeE6g.rQzrm_RDmpaiDKcyAYEwzZnQ9EU6ukN5/ws"

connected (press CTRL+C to quit)
>

📘

Note

The session IDs provided in the POST request expire if there is no active connection, so make sure to have wscat ready to connect before you request a session ID.

When you see the > prompt above, you are connected.

Subscribing to Events in a Stream

WebSocket is a push-based transport mechanism, so you can subscribe to one or many Streams and receive all Events in real time by issuing a subscription request for an individual stream. You can subscribe by either Stream ID or path. For example:

{
  "msgId": "my-request",
  "object": "event",
  "type": "subscribe",
  "streamId": "s53b1d1600cf27b75148de0ac"
}

{
  "msgId": "my-path-request",
  "object": "event",
  "type": "subscribe",
  "path": "/my/stream/path"
}

Subscription Acknowledgment

Each subscription request will receive an acknowledgment that echoes the user-supplied msgId. For example:

{
  "head": {
    "msgId": "my-path-request",
    "ok": true,
    "errors": [],
    "messages": ["Your request has been processed successfully."]
  },
  "body": {}
}

Incoming Events

When an Event is sent to the specified Stream, it will be delivered in the following message format:

{
  "type": "message",
  "resource": "s53b1d1600cf27b75148de0ac",
  "value": {
    // <... Event object here ...>
  }
}

Unsubscribing

To unsubscribe from a Stream, send the same message with type set to unsubscribe. For example:

{
  "msgId": "my-request",
  "object": "event",
  "type": "unsubscribe",
  "streamId": "s53b1d1600cf27b75148de0ac"
}