Qntrl WebSocket: Real-Time Communication, Setup & Message Routing | Qntrl Online Help

Configure a WebSocket Connection

WebSocket enables real-time, persistent communication between your application and Qntrl. Unlike REST or SOAP APIs, WebSocket maintains an active connection, allowing continuous data exchange without repeated requests.

Use WebSocket when your application requires instant updates without refreshing or repeated API calls.
 

Key Benefits   

  • Real-time communication

  • Reduced API calls

  • Efficient handling of multiple workflows

  • Supports event-driven architecture

 

How WebSocket differs from REST/SOAP   

Feature

REST / SOAP

WebSocket

Connection Type

Stateless

Persistent

Communication

Request → Response

Continuous (bi-directional)

Reconnection

Required for every request

Not required

Use Case

Standard API calls

Real-time updates

 

  • In REST/SOAP, each request is independent and returns a response immediately.

  • In WebSocket, once connected, the connection stays active until manually disconnected.

 

Common Use Cases   

  • Live dashboards (e.g., ticket counts updating in real time)

  • Chat applications / chatbots

  • Real-time notifications (e.g., transaction updates)

  • Live data streams (e.g., sports scores)   


Configure a WebSocket Endpoint   

To configure a WebSocket in Qntrl:

1. Navigate to WebSocket:

  • Log in to Qntrl.

  • Click the Web Services icon on the left panel.

  • Under Inbound select WebSocket.

2. Start by entering the basic information under Connection Settings:

  • Connection Name: A name to identify the WebSocket connection

  • WebSocket URL: The endpoint URL used to establish the connection.

  • Authentication Type: OAuth or API Key

    • When establishing a connection, pass the query parameter: wss://<URL>?auth_type=<auth_type>

      • auth_type=oauth → OAuth authentication

      • auth_type=apikey → API Key authentication

  • Message routing Path – A JSON path used to route incoming messages (e.g., $.module)

3. Define how the system should behave during different connection events. The Resource Type dropdown lists all resources created with the module type 'Webservice WebSocket'.

  • Connect Route: Action to execute when a client connects

  • Disconnect Route: Action to execute when a client disconnects

  • Default Route: Fallback action when no specific message route matches

For each of the above, select:

  • Resource Type (e.g., Function)

  • Resource (the specific function or action to execute)

4. Message Routing: Handles incoming messages dynamically by reading the value from the Resource Selection Path and triggering an action based on the matched value.

For each route, define:

  • Route Value: Value to match from the request

  • Resource Type: Type of action

  • Resource: Action to execute

Ex: Input JSON:

{
  "module": "task_engine"
}

Configuration:

  • Resource Selection Path: $.module

  • For Route Value:

    • task_engine → Execute Function A

    • db_engine → Execute Function B

    • No match → Default Route executes

This allows a single WebSocket endpoint to handle multiple workflows.

​

5. Policy: Policies control the number of messages allowed per connection.

  • Select an existing policy or click Add New Policy

  • Fill in the following details:

    • Policy Name: Name of the policy 

    • Requests Allowed: Maximum messages allowed

    • Time Window (Minutes): provide the time window in minutes

    • Error Code: Returned when limit is exceeded

    • Message: Error message shown

    • Click Save to create a policy


  • Click the edit (✎) icon adjacent to the field to update the rate policy configuration.

6. Once all configurations are complete, click Save.

The WebSocket URL will be generated automatically and the connection will be listed under WebSocket Connections.

  

Establish WebSocket Session 

To establish a session, connect using: wss://<URL>?auth_type=<auth_type>

On Successful Connection   

  • A Session ID is returned in the response header

  • This session is used for message exchange

 

Optional Parameters   

  • session_id (Header): Reuse an existing session by passing the session ID to reconnect and retain the same session.
  • session_name (Query Parameter): Assign a unique name to the session. This can be used later to identify and send messages to that session.

 

Session Behavior   

  • If no message is exchanged for 1.5 minutes, the session is automatically disconnected

 

Using WebSocket    

Send Messages  (Client → Qntrl)

  • Messages are sent continuously over the active connection

  • Routed based on Message Routes

 

Send Messages  (Qntrl → Client)

You can send messages from Codex Functions (standalone, job after save, etc.):

  • Using Session ID  : WebSocket.sendMessage(<session_id>, <message>);

  • Using Session Name  : WebSocket.sendMessagebyName(<websocket_id>, <session_name>, <message>);

  • Using User ID (OAuth)  : WebSocket.sendMessageForUser(<websocket_id>, <user_id>, <message>);

 

View and Manage Connections   

  • Select a WebSocket from the WebSocket Resources list.

  • In the WebSocket Details section, you can modify the configuration if required and click Save to apply the changes.

  • Navigate to the Session Details section to view all active and past connections along with their status.

  • Use the Status toggle to connect or disconnect a session.

  • When a session is disconnected, messages will no longer be delivered to that connection.

 

User-Based Notifications (OAuth)   

When using OAuth:

  • Connection is tied to a user

  • Notifications can be sent to a specific user

Example  

  • Event: Transaction completed

  • Action: Send message to user

  • Result: User receives instant notification across all active sessions