Subscribe API

The Subscribe API allows you to connect to a conversation or a meeting in listen-only mode.

Using this API, you can allow users to subscribe to webinars or conferences where there are only a handful of speakers and most participants are only listening in.

While users connected on WebSocket are charged per user, the listen-only participants can stream the transcription and insight services at no cost.

This can be turned on or off for a conversation, on demand.

📘

The Subscribe API allows you to add up to 10,000 participants per call.

API Endpoint

wss://api.symbl.ai/v1/subscribe/{connectionId}?access_token={accessToken}

This is a WebSocket endpoint that lets you subscribe to all the real-time updates. Often, this URL is auto-generated by services such as the inbound-stream-integration.

ParameterDescription
connectionIdString, mandatory

The same connectionId that is generated with the Streaming API can be used to subscribe to this API.
accessTokenString, mandatory

The Symbl's Authentication token you get from the Authentication process.

Request Body

const WebSocket = require('ws');
const accessToken = "<accessToken>";
const connectionID = "<connectionID>";

const symblEndpoint = 'wss://api.symbl.ai/v1/subscribe/${connectionID}?access_token=${accessToken}';
const ws = new WebSocket(symblEndpoint);

// Fired when a message is received from the WebSocket server
ws.onmessage = (event) => {
    // You can find the conversationId in event.message.data.conversationId;
    const data = JSON.parse(event.data);
    if (data.type === 'message' && data.message.hasOwnProperty('data')) {
        console.log('conversationId', data.message.data.conversationId);
    }
    if (data.type === 'message_response') {
        for (let message of data.messages) {
            console.log('Transcript (more accurate): ', message.payload.content);
        }
    }
    if (data.type === 'topic_response') {
        for (let topic of data.topics) {
            console.log('Topic detected: ', topic.phrases)
        }
    }
    if (data.type === 'tracker_response') {
        for (let trackers of data.trackers) {
            console.log('Trackers detected: ', trackers);
        }
    }
    if (data.type === 'insight_response') {
        for (let insight of data.insights) {
            console.log('Insight detected: ', insight.payload.content);
        }
    }
    if (data.type === 'entity_response') {
        for (let entity of data.entities) {
            console.log('Entity detected: ', entity);
        }
    }
    if (data.type === 'message' && data.message.hasOwnProperty('punctuated')) {
        console.log('Live transcript (less accurate): ', data.message.punctuated.transcript)
    }
    console.log('Response type: ${data.type}. Object: ', data);
};
// Fired when the WebSocket closes unexpectedly due to an error or lost connection
ws.onerror = (err) => {
    console.error(err);
};
// Fired when the WebSocket connection has been closed
ws.onclose = (event) => {
    console.info('Connection to websocket closed');
};

Response Body

Example of the message_response object:

{
  "type": "message_response",
  "messages": [
    {
      "from": {
        "name": "Jane",
        "userId": "[email protected]"
      },
      "payload": {
        "content": "I was very impressed by your profile, and I am excited to know more about you.",
        "contentType": "text/plain"
      }
    },
    {
      "from": {
        "name": "Jane",
        "userId": "[email protected]"
      },
      "payload": {
        "content": "So tell me, what is the most important quality that you acquired over all of your professional career?",
        "contentType": "text/plain"
      }
    }
  ]
}

Example of the insight_response object:

{
  "type": "insight_response",
  "insights": [
    {
      "type": "question",
      "text": "So tell me, what is the most important quality that you acquired over all of your professional career?",
      "confidence": 0.9997962117195129,
      "hints": [],
      "tags": []
    },
    {
      "type": "action_item",
      "text": "Jane will look into the requirements on the hiring for coming financial year.",
      "confidence": 0.9972074778643447,
      "hints": [],
      "tags": [
        {
          "type": "person",
          "text": "Jane",
          "beginOffset": 0,
          "value": {
            "value": {
              "name": "Jane",
              "alias": "Jane",
              "userId": "[email protected]"
            }
          }
        }
      ]
    }
  ]
}

Example of the tracker_response object:

{
  "type": "tracker_response",
  "isFinal": false,
  "trackers": [
    {
      "name": "Catch Phrases",
      "matches": [
        {
          "type": "vocabulary",
          "value": "That's the way the news goes",
          "messageRefs": [
            {
              "text": "That's how the news goes"
            }
          ]
        }
      ]
    }
  ]
}

Example of the topic_response object:

{
  "type": "topic_response",
  "topics": [
    {
      "id": "a3896596-34db-11ed-8f60-0ec59813cce9",
      "messageReferences": [
        {
          "id": "00b44fd7-626e-441d-bded-c8eff13f8200",
          "relation": "text instance"
        }
      ],
      "phrases": "instagram stories",
      "rootWords": [
        {
          "text": "Instagram"
        }
      ],
      "score": 0.9,
      "type": "topic",
      "messageIndex": 4
    },
    {
      "id": "a38994d0-34db-11ed-8f60-0ec59813cce9",
      "messageReferences": [
        {
          "id": "db333333-1b9b-4d0c-8732-5fea879dc667",
          "relation": "text instance"
        },
        {
          "id": "00b44fd7-626e-441d-bded-c8eff13f8200",
          "relation": "dominant context"
        }
      ],
      "phrases": "causal",
      "rootWords": [
        {
          "text": "causal"
        }
      ],
      "score": 0.09,
      "type": "topic",
      "messageIndex": 5
    }
  ]
}