Skip to main content

​
Overview

Chat WebSocket agents communicate via text messages over a persistent WebSocket connection. Unlike the standard Chat (HTTP) integration which uses request-response, Chat WebSocket maintains a single connection for the entire conversation — ideal for agents built on platforms like Genesys, NICE, or custom WebSocket-based chat systems. When to use Chat WebSocket instead of Chat (HTTP):
  • Your agent communicates over WebSocket rather than HTTP POST
  • Your agent sends multiple messages in response to a single user message
  • Your platform requires a persistent connection for the conversation lifecycle

​
Connection Modes

Chat WebSocket supports two connection modes:

​
Direct Mode (Default)

Connect directly to a WebSocket endpoint. 
wss://your-agent.example.com/ws/chat

​
HTTP-First Mode

Call an HTTP endpoint first to create a session, then connect to the WebSocket URL returned in the response. Common with platforms that require session provisioning before establishing a WebSocket connection. Flow:
  1. Coval sends an HTTP request to your setup endpoint
  2. Your API returns a response containing the WebSocket URL
  3. Coval connects to that WebSocket URL

​
Configuration

​
Direct Mode Fields

FieldRequiredDescription
WebSocket EndpointYesThe wss:// URL to connect to
Initialization JSONNoJSON payload sent immediately after connection
Authorization HeaderNoAuth value sent during the WebSocket handshake
Custom HeadersNoAdditional headers for the WebSocket handshake

​
HTTP-First Mode Fields

FieldRequiredDescription
HTTP Endpoint URLYesThe https:// URL to call for session setup
HTTP MethodNoRequest method (default: POST)
Request BodyNoJSON body for the HTTP request
HTTP HeadersNoHeaders for the HTTP request
WebSocket URL Response PathYesDot-notation path to the WebSocket URL in the response
Authorization HeaderNoAuth value for the WebSocket connection (separate from HTTP headers)
Initialization JSONNoJSON payload sent after WebSocket connection
Custom HeadersNoAdditional headers for the WebSocket connection

​
Message Format

​
Sending Messages (Coval to Agent)

Messages are sent as JSON using a configurable template. The default template: 
{"type": "message", "text": "{{message}}"}
The {{message}} placeholder is replaced with the actual message text. Customize the template to match your agent’s expected format: 
{"event": "chat", "body": "{{message}}"}

​
Receiving Messages (Agent to Coval)

Coval extracts text from incoming WebSocket messages using configurable JSON paths:
SettingDefaultDescription
Message type pathtypePath to the message type field
Text message type valuesmessageType value(s) that indicate a text message
Message text pathtextPath to the actual message content
Example: For an agent that sends: 
{"event": "reply", "data": {"content": "Hello!"}}
Configure:
  • Message type path: event
  • Text message type values: reply
  • Message text path: data.content

​
Message Coalescing

Many chat agents send multiple messages in quick succession (e.g., a greeting followed by a question). Coval batches these into a single response using a configurable quiet period.
  • Default: 2.0 seconds
  • Set to 0: Deliver each message immediately (no batching)
  • Increase: For agents that send messages with longer pauses between them

​
Handshake

Some WebSocket agents send a “ready” message before accepting conversation messages. Configure the handshake to wait for this signal:
SettingDefaultDescription
Ready message type(empty — no wait)The message type value that signals readiness
Handshake timeout30 secondsHow long to wait before timing out
Example: If your agent sends {"type": "session_ready"} when it’s ready:
  • Set Ready message type to session_ready

​
Direction Filtering

If your agent echoes back your outbound messages (common with Genesys), configure direction filtering to skip those echoes:
SettingDescription
Direction pathJSON path to the direction field (e.g., direction)
Outbound direction valueThe value indicating an agent-to-user message (e.g., outbound)
When configured, only messages matching the outbound direction value are processed. Messages without a direction field or with a different value are skipped.

​
Setup Instructions

  1. Create the agent — Navigate to Agents, select Chat as the agent type, then toggle to WebSocket protocol
  2. Choose connection mode — Select Direct or HTTP-First depending on your platform
  3. Configure the endpoint — Enter your wss:// URL (Direct) or HTTP setup endpoint (HTTP-First)
  4. Set message format — If your agent doesn’t use the default {"type": "message", "text": "..."} format, customize the send template and receive paths under Advanced Configuration
  5. Test — Create a test set with a single test case and launch a simulation to verify connectivity

​
Common Patterns

​
Pattern 1: Simple Direct Connection

Connection Mode: Direct
Endpoint: wss://chat.example.com/ws

​
Pattern 2: Authenticated Direct Connection

Connection Mode: Direct
Endpoint: wss://chat.example.com/ws
Authorization Header: Bearer your-token-here
Initialization JSON: {"action": "start_session", "channel": "web"}

​
Pattern 3: HTTP-First with Session Provisioning

Connection Mode: HTTP-First
HTTP URL: https://api.example.com/v1/sessions
HTTP Method: POST
Request Body: {"channel": "web", "language": "en"}
HTTP Headers: {"Authorization": "Bearer your-token"}
WebSocket URL Response Path: data.websocket_url

​
Pattern 4: Custom Message Format

Connection Mode: Direct
Endpoint: wss://chat.example.com/ws
Send Template: {"event": "user_message", "payload": {"text": "{{message}}"}}
Message Type Path: event
Text Message Type Values: agent_message
Message Text Path: payload.text

​
Troubleshooting

​
Connection Failures

“Timeout connecting to WebSocket”
  • Verify the wss:// URL is correct and publicly accessible
  • Check that your server accepts WebSocket upgrade requests
  • Ensure firewall rules allow inbound WebSocket connections
“Failed to connect to WebSocket”
  • Confirm the endpoint is running and healthy
  • Check authorization header format matches what your server expects
  • For HTTP-First: verify the HTTP setup endpoint returns a valid WebSocket URL

​
No Messages Received

  • Check that your message type path and text message type values match what your agent actually sends
  • Verify the message text path points to the correct field
  • If using direction filtering, confirm the outbound direction value is correct
  • Try increasing the coalesce timeout if messages arrive after the batch window closes

​
Handshake Timeout

  • Confirm your agent sends the expected ready message type
  • Check that the ready message is sent before the timeout (default 30s)
  • Verify the message type path resolves correctly on the ready message

​
Messages Getting Dropped

  • If your agent echoes your messages back, configure direction filtering
  • Ensure text_message_type_values includes all message types your agent uses for text responses
  • Check agent logs for messages with unexpected type values

​
Technical Requirements

RequirementDetails
Protocolwss:// (TLS-encrypted WebSocket)
Message formatJSON with configurable paths
AccessibilityMust be publicly accessible from Coval servers
Concurrency limit8 simultaneous simulations