The Octave Developer Hub

Welcome to the Octave developer hub. You'll find comprehensive guides and documentation to help you start working with Octave as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

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"
}

Updated 2 months ago

Consuming Events via WebSocket


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.