Key Benefits   

• Real-time communication

• Reduced API calls

• Efficient handling of multiple workflows

• Supports event-driven architecture

How WebSocket differs from REST/SOAP   

• 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.

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