Documentation Index
Fetch the complete documentation index at: https://docs.coval.dev/llms.txt
Use this file to discover all available pages before exploring further.
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:
- 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 |
Sending Messages (Coval to Agent)
Messages are sent as JSON using a configurable template. The default template:
{"type": "message", "text": "{{message}}"}
{{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 |
{"event": "reply", "data": {"content": "Hello!"}}
- 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 |
{"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) |
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
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
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 |
