Skip to main content

Websocket

Subscribe to a stream​

You can subscribe a stream using a simple setup of socket.io.

We will provide an example using javascript, but you can connect to your websocket endpoint using anything that implements the v4 or above of the socket.io standard. As a standard we tried to simplify as much as possible de configs and setup required to get message from you websockets.

Code Example​

import { io } from 'socket.io-client';

const host = 'https://api.bloomr.stream/';
const socket = io(host, {
    query: {
        stream: 'dwd23RWdwE', // the id of your script
        token: 'your-token-here', // the token you generated in your settings
    },
});

// event on connect
socket.on('connect', () => {
    console.log('Connected to', host);
});

// event on error
socket.on('error', arg => {
    console.error('ERROR =>', arg);
});

// event on message
socket.on('message', arg => {
    console.error('MESSAGE =>', arg);
});

Token​

To be able to use your script's websocket, you first have to generate a token. To do so, please follow this link : (TODO: linkhere) You will be able to generate a token usable for your scripts.

Replay Phase​

In order to make things as simple as possible we decided to offer on each connection an optional "replay phase".

This will resend already sent message back to your websocket connection.

With this activated at connection, you could make sure that you did not miss any messages. By checking the messages id agaisn't what you already received

After this replay phase, we start sending you all the messages back in 'stream' mode.

NB: We made sure you do not miss any message even with replay phase activated on connection.

⚠️ To be able to use the replay functionality, you have to toggle 'store_history' functionality

Query Arguments​

    query: {
        stream: 'dwd23RWdwE', // the id of your script
        token: 'your-token-here', // the token you generated in your settings
        replayLimit: 123,  // Optional, number of messages max replayed at connection
        replay: '2h', // Optional
        includeMetadata: false,
        channel: 'errors'
    },
});

stream is the unique id of your script. It is refered in our website as the connect-id or the stream-id.

token is the token you generated in your settings.

channel (optional) is the name of the channel you want to subscribe to. It can be either ''(empty or not refered) , meaning you will subscribe to the standard output of your script (most common usage). It can be equal to 'errors' , to subscribe to all errors from your script. It can be equal to a name you set yourself. i.e : 'myChannel'. that you will emit to in your script.

During the replay phase, replay and replayLimit are both optional value. If none are sent, we will not replay any messages back at the websocket connection.

replayLimit is the maximum number of message you want to receive on the replay phase. if you do not provide this option and have one of the 'replaySince', 'replayDate' or 'replayId' filled. This will be defaulted to 10000. It is the maximum amount of message allowed.

replay is the maximum 'age' of the messages your want to receive during the replay phase. we accept multiple formats.

  • the format ISO8601, ie: 2024-03-26T15:24:57Z
  • the format date, ie: '1hour' (Accepted 'h' | 'hour' | 'hours' | 'm' | 'min' | 'mins' | 'd' | 'day' | 'days' | 's' | 'sec' | 'seconds')
  • the id of a message you want to replay from (ie: '8006d38c-e838-11ee-9353-c87f546d0e60')

⚠️ For any scripts websocket we do not allow the replay phase to exceed 10000 messages. Even with contrary arguments. We recommend to use HTTP Polling or Webhooks if you have to. If with the argument you provided the number of reran messages exceed the limit. the websocket will emit a message in the 'warning' channel. You will then receive message replayed back to you not exceeding 10 000 messages

Events​

we recommend 5 events when you connect to our websockets

connect to make sure you are connected to our services disconnect to be able to react to a disconnection. warning in case the replay phase exceed 10000 messages, this will be triggered. error for any error either during connection or during the 'live stream' phase. message the channel you receive messages to.