> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat WebSocket

> Connect to text chat agents over a persistent WebSocket connection

## Overview

Chat WebSocket agents communicate via text messages over a persistent WebSocket connection. Unlike the standard [Chat (HTTP)](/concepts/agents/connections/chat) 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:**

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

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

```json theme={null}
{"type": "message", "text": "{{message}}"}
```

The `{{message}}` placeholder is replaced with the actual message text. Customize the template to match your agent's expected format:

```json theme={null}
{"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:

```json theme={null}
{"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

1. **Create the agent** — Navigate to [Agents](https://app.coval.dev/agents/create), 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

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