​
Overview

Websocket API comes as an alternative to the integration of the ingress (via HTTP Gateway) and the egress connection (via Egress Service) that combines the two in a single, easier to manage, connection. The connection is managed by the WS Gateway component and it can be used as a bot ingress and egress connection, or only as an ingress connection. The Egress Service can be used along side with the WS Gateway to retrieve the results of the websocket-initiated stream from multiple clients.

​
Diagrams

General workflow

​
Authentication

A client can authenticate to the websocket API by providing either a Basic or a Bearer token. The token can be placed in either the Authorization or Sec-WebSocket-Protocol headers.
  • Authorization: Basic <basic_token>
  • Authorization: Bearer <basic_token>

​
Basic token

The basic token is a base64 encoded string of the username:password pair. The username is the client_id and the password is the client_secret.

​
Bearer token

Generate a bearer token using the authentication endpoint.
Use this authentication method when the token will reach a front channel (e.g. website)

​
Configuration

The stream configuration options will be passed as query parameters to the websocket connection URL or using the configuration message. By default, no configuration message is expected, and sending one will result in an error. To enable the configuration message, set the configuration message query parameter in the connection URL, then send the configuration message after the connection is established. Learn about configuration patches here. For more details, please check the WS Gateway API Reference and the properties of the stream configuration template you’re planning to use.

​
Stream metadata

Right after the client connects, and attempt to create the stream is made. If successful, a stream metadata message will be sent to the client. Otherwise, an error will be emitted and the connection will be closed.
Message schema: StreamMetadataMessageDto

​
Responses

The server will respond in one of the following formats based on the configured egress format:
  • EVENTS: wrap the processor response in a metadata JSON object
  • RAW: return the processor response as is, generally as a websocket binary message The default format is EVENTS, that will be suited for most of the use-cases.
Message schema: ResponseMessageDto
Use the RAW format only when a binary response is expected

​
Timeouts

Generally the client will continuously send messages to the server, but there are scenarios where the client will stay idle (e.g. waiting for a new chunk of data to send or waiting for the end of stream signal).
The websocket connection will be closed after 10 seconds of inactivity. We define the period inactivity as the time elapsed since the last message was sent by the client. To prevent the connection to close, the client has two options:
  • send a KeepAlive message when the client becomes idle
  • send a Ping message to the server. This will trigger a Pong message from the server
In this case the connection will become idle. We define the idle period as the time elapsed since the last non-keep-alive message was sent by the client.
Message schema: KeepAliveMessageDto
Idle connections will timeout after 30 minutes
Timeout connections will be closed without any error message or signal
Use the ping-pong mechanism if the library provides it. Set the ping interval to 5 seconds

​
Diagrams

​
End of stream

After the client has sent all the data, it must signal this by sending an End of stream message. If the client is waiting for all responses, it must wait for the End of stream message from the server. After sending the End of stream message, the server will immediately close the connection.
Message schema: EndOfStreamMessageDto
A client disconnect will trigger the end of stream signal
The server will emit an End of Stream signal only if the websocket connection is also used as egress

​
Diagrams

​
Error handling

The server will emit an error message if the client sends an invalid message or if the server encounters an error while processing the message. The connection will be closed by the server immediately after sending the error message.
Message schema: ErrorMessageDto
Whether an error occurs or not, the connection will be closed with a 1000 - Normal Closure code

​
Diagrams

​
API reference

Please check the WS Gateway API Reference for API details.