ROQ Suite ships with a message center that contains a fully functioning chat system. This system is based on the WebSocket protocol rather than GraphQL. Once the connection is established, the socket is represented as a stream with the ability to send events with specific name and payload (data). You can find a full working implementation in ROQ One.

Document image

How it works

If you are building on top of ROQ One, this logic is already implemented and working out of the box, so you don’t need to do anything! You can still read this documentation, though, if you want to customize it or you are just curious about how things work.


To secure a socket connection, a few steps are required to authorize new stream. Through the authorization process, socket stream might be in a different states:

  • unverified stream (doesn’t able to make any API request)

  • verified stream (allowed only to be authorized with user)

  • authorized stream (full access to the API)

  • closed stream (in case of any error during authorization process)

Stream verification via ROQ Platform Token

ROQ Gateway provides a specific API to validate whether a service has permission to access data through GCL API. Because the Chat is not fully independent and constantly uses information from ROQ Platform Data, we use authorization mechanisms for security purposes. This means the chat instance may request information from ROQ Gateway.

ROQ One instance (aka client), which connects to ROQ Platform Chat through the socket, communicates with the provided API from the browser. During the user authorization process, the client is provided a Platform Token from ROQ Gateway. This token is unique for each ROQ One instance and generated from private and public API keys (configurable via environment variables).

Document image

The ROQ Chat Service validates the token during socket stream opening flow. As many clients may be connected to a single ROQ Chat service, we provide the PlatformToken variable inside the stream opening HTTP query to verify the token is not expired, invalid, etc.

Even once the connection established and the client is granted access to the ROQ platform data, it still cannot fully use the Chat API.

Stream authorization

Opposite to the HTTP/GCL queries, the socket stream doesn’t allow for providing additional meta information inside each query (except to pass data inside request payload). Also, in order to use a single verified socket stream with different users, we must authorize the stream with users currently logged in to the system.

To connect a verified stream to a logged in user, the client must call a userConnected event.

After successful authorization, the current stream is mapped with the specific user, and the client is allowed to execute any API request. Moreover, each response is personalized to the authorized user (for example, fetching a list of conversations).