Chat WebSocket

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 — common 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:

Coval sends an HTTP request to your setup endpoint
Your API returns a response containing the WebSocket URL
Coval connects to that WebSocket URL

Configuration

Direct Mode Fields

Field	Required	Description
WebSocket Endpoint	Yes	The `wss://` URL to connect to
Initialization JSON	No	JSON payload sent immediately after connection
Authorization Header	No	Auth value sent during the WebSocket handshake
Custom Headers	No	Additional headers for the WebSocket handshake

HTTP-First Mode Fields

Field	Required	Description
HTTP Endpoint URL	Yes	The `https://` URL to call for session setup
HTTP Method	No	Request method (default: POST)
Request Body	No	JSON body for the HTTP request
HTTP Headers	No	Headers for the HTTP request
WebSocket URL Response Path	Yes	Dot-notation path to the WebSocket URL in the response
Authorization Header	No	Auth value for the WebSocket connection (separate from HTTP headers)
Initialization JSON	No	JSON payload sent after WebSocket connection
Custom Headers	No	Additional 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:

Setting	Default	Description
Message type path	`type`	Path to the message type field
Text message type values	`message`	Type value(s) that indicate a text message
Message text path	`text`	Path 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:

Setting	Default	Description
Ready message type	(empty — no wait)	The message type value that signals readiness
Handshake timeout	30 seconds	How 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:

Setting	Description
Direction path	JSON path to the direction field (e.g., `direction`)
Outbound direction value	The 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

Create the agent — Navigate to Agents, select Chat as the agent type, then toggle to WebSocket protocol
Choose connection mode — Select Direct or HTTP-First depending on your platform
Configure the endpoint — Enter your wss:// URL (Direct) or HTTP setup endpoint (HTTP-First)
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
Test — Create a test set with a single test case and launch a simulation to verify connectivity

Sending Traces

WebSocket agents can send traces to Coval. Set Custom Headers to {"X-Coval-Simulation-Id": "{{simulation_id}}"}. Read that header during the WebSocket upgrade and use its value as the X-Simulation-Id header when exporting OTLP spans. See WebSocket agents for the full setup.

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

Requirement	Details
Protocol	`wss://` (TLS-encrypted WebSocket)
Message format	JSON with configurable paths
Accessibility	Must be publicly accessible from Coval servers
Concurrency limit	8 simultaneous simulations

Simulate

Evaluate

Observe

Review

Cookbooks

Sofia

Reference

Overview

Connection Modes

Direct Mode (Default)

HTTP-First Mode

Configuration

Direct Mode Fields

HTTP-First Mode Fields

Message Format

Sending Messages (Coval to Agent)

Receiving Messages (Agent to Coval)

Message Coalescing

Handshake

Direction Filtering

Setup Instructions

Sending Traces

Common Patterns

Pattern 1: Simple Direct Connection

Pattern 2: Authenticated Direct Connection

Pattern 3: HTTP-First with Session Provisioning

Pattern 4: Custom Message Format

Troubleshooting

Connection Failures

No Messages Received

Handshake Timeout

Messages Getting Dropped

Technical Requirements

​Overview

​Connection Modes

​Direct Mode (Default)

​HTTP-First Mode

​Configuration

​Direct Mode Fields

​HTTP-First Mode Fields

​Message Format

​Sending Messages (Coval to Agent)

​Receiving Messages (Agent to Coval)

​Message Coalescing

​Handshake

​Direction Filtering

​Setup Instructions

​Sending Traces

​Common Patterns

​Pattern 1: Simple Direct Connection

​Pattern 2: Authenticated Direct Connection

​Pattern 3: HTTP-First with Session Provisioning

​Pattern 4: Custom Message Format

​Troubleshooting

​Connection Failures

​No Messages Received

​Handshake Timeout

​Messages Getting Dropped

​Technical Requirements

Overview

Connection Modes

Direct Mode (Default)

HTTP-First Mode

Configuration

Direct Mode Fields

HTTP-First Mode Fields

Message Format

Sending Messages (Coval to Agent)

Receiving Messages (Agent to Coval)

Message Coalescing

Handshake

Direction Filtering

Setup Instructions

Sending Traces

Common Patterns

Pattern 1: Simple Direct Connection

Pattern 2: Authenticated Direct Connection

Pattern 3: HTTP-First with Session Provisioning

Pattern 4: Custom Message Format

Troubleshooting

Connection Failures

No Messages Received

Handshake Timeout

Messages Getting Dropped

Technical Requirements