Subscribing to a channel

The WS API offers a variety of event channels to which users can subscribe to receive real-time updates from those channels (see Event notifications). Examples of these channels are session_emotions_counts or session_worker_state.

tip

Check the reference page of each channel to learn which data you can gather in real-time.

Using this endpoint you can subscribe to a channel to start receiving events by specifying the channel name and a key which specifies which data, how often etc. you will receive from that specific channel. For example, if you are subscribing to session_emotions_counts, the key will contain information like the ID of the session you want to receive updates from and the frequency with which you will receive these updates. Check each channel reference to learn how to build its key.

warning

The subscriptions are connection based. If you disconnect from the server, when you start a new connection you will need to send a new subscribe request again in order to start receiving events again.

Path

channels:subscribe

Request Body

channel

enum Channel

Required

Channel you want to subscribe to.

Possible enum values

session_emotions_counts
Receive periodical updates about the number of emotions detected in a session during the given period.

session_emotions_intensities
Receive periodical detailed updates about the count, the intensity etc. of the emotions detected in a session during the given period.

session_worker_state
Get updates about the state of the worker which is analyzing a session (only available for sessions created through the external API).

key

string

Required

Key to select the configuration of the channel you are subscribing to. Check each channel reference to learn how to build its key.

Response Body

subscriptionId

string

Required

Unique ID assigned for this subscription on this connection. You can use this ID identify to which subscription a received event belongs to and to stop receiving events from this subscription using the unsubscribe endpoint.

Example: luug96xrbbc594

channel

enum Channel

Channel have subscribed to.

Example: session_emotions_counts

key

string

Key you used for the subscription.

Example: 66151895e00a857bd76f889d:10s

Response codes

Code	Meaning	Description
200	OK	Success. You will receive events from the specifiec channel and key.
400	Bad Request	Server received an invalid request body.
404	Not Found	Channel and key combination not found or you do not have permissions for it.

Request example

channels:subscribe

// Connect to the server
const ws = new WebSocket('wss://api.emogg.com/ws/v1');

// Helper function for sending messages
const sendMessage = (path, body, id) => {
  const payload = {
    "id": id,
    "path": path,
    "body": body
  }
  
  console.log('// Request\n', payload)
  ws.send(JSON.stringify(payload));
}

// Authenticate connection
ws.onopen = () => sendMessage("auth:token", { "token": "YOUR_TOKEN" }, 1);

// Server messages callback
ws.onmessage = function (payload) {
  const message = JSON.parse(payload.data)
  console.log('// Response\n', message)

  const { id, path, status, body } = message
  if (path === 'auth:token' && status === 200) { // If successfully authenticated, send our message
    const message = {"channel":"session_emotions_counts","key":"66151895e00a857bd76f889d:10s"}
    sendMessage("channels:subscribe", message)
  }
};

Result

// Request
{ "id": 1, "path": "auth:token", "body": { "token": "YOUR_TOKEN" } }

// Response
{ "id": 1, "path": "auth:token", "status": 200 }

// Request
{ "path": "channels:subscribe", "body": {"channel":"session_emotions_counts","key":"66151895e00a857bd76f889d:10s"} }

// Response
{ "id": null, "path": "channels:subscribe", "status": 200, "body": {"channel":"session_emotions_counts","key":"66151895e00a857bd76f889d:10s","subscriptionId":"luug96xrbbc594"} }

// Events
[ "luug96xrbbc594", 1712794471965, "sec", [{ "exaltation": 11, "focus": 8 }] ]
{...}