WebSocket

​

Overview

​

Connection Modes

​

Direct Mode (Default)

​

HTTP-First Mode

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 Requirements

​

WebSocket Endpoint

• Field: endpoint
• Type: String (required)
• Purpose: The WebSocket URL that Coval connects to for simulations
• Format: Must start with wss:// (secure WebSocket)
• Example: wss://your-api.com/ws/voice

​

Initialization JSON

• Field: initialization_json
• Type: JSON object (optional)
• Purpose: Initial payload sent to your WebSocket endpoint when the connection is established
• Format: Valid JSON object
• Use Cases: Session initialization, authentication handshakes, context setup

{
  "action": "start_session",
  "session_type": "simulation",
  "metadata": {
    "source": "coval",
    "test_mode": true
  }
}

​

Authorization Header

• Field: authorization_header
• Type: String (optional)
• Purpose: Authentication value sent in the Authorization header during the WebSocket handshake
• Format: Standard authorization header value
• Security: Stored encrypted and handled securely

• Bearer token: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
• API key: X-API-Key your-api-key-here
• Basic auth: Basic base64-encoded-credentials

​

Custom Headers

• Field: custom_headers
• Type: JSON object (optional)
• Purpose: Additional HTTP headers sent during the WebSocket handshake
• Format: Valid JSON object with string key-value pairs
• Use Cases: Custom authentication, routing headers, client identification

{
  "X-Client-ID": "coval-simulation",
  "X-API-Version": "2024-01",
  "X-Environment": "production"
}

​

Media Send Template

• Field: send_media_template
• Type: String (optional)
• Purpose: Controls how Coval sends an attached image to your agent during WebSocket voice simulations
• Applies When: A test case includes an image attachment and the persona decides to send it

{
  "type": "media",
  "name": "{{media_name}}",
  "mime_type": "{{mime_type}}",
  "data": "{{media_data}}"
}

• {{media_data}} is required.
• {{media_name}} and {{mime_type}} are optional placeholders.
• If the template is exactly {{media_data}}, Coval sends raw bytes.
• Otherwise, Coval base64-encodes the image and substitutes it into your JSON template.

​

Advanced Configuration

​

Sample Rates

​

Handshake

{
  "type": "session_ready",
  "session_id": "abc123"
}

​

Audio Format

​

Media Format

​

Setup Instructions

1. Prepare your WebSocket endpoint
   • Ensure your endpoint accepts secure WebSocket connections (wss://)
   • Configure your server to handle the authorization header if authentication is required
   • Set up message handling for the conversation flow
   • If you want to receive test-case images, decide whether your endpoint expects raw bytes or a JSON payload with base64 media data
   • Configure audio handling for the expected sample rates
2. Create the agent in Coval
   • Navigate to app.coval.dev/agents/create
   • Select WebSocket as the connection type
   • For Direct Mode: enter your WebSocket endpoint URL (must start with wss://)
   • For HTTP-First Mode: enter your HTTP setup URL (https://), HTTP method/body/headers, and the WebSocket URL response path
   • Add authorization header if your endpoint requires authentication
   • Configure initialization JSON if you need to send a setup payload
   • Add any custom headers required by your endpoint
   • Set Media Send Template if your agent needs a specific image payload shape
   • Configure advanced settings like sample rates if needed
3. Test the connection
   • Create a simple test set with a few scenarios
   • Add an image attachment to one test case if you want to test multimodal behavior
   • Launch a simulation to verify end-to-end connectivity
   • Check that audio is being sent and received correctly

​

How Simulations Work

1. HTTP-first setup (if applicable) — If using HTTP-First mode, calls the HTTP endpoint first to get the WebSocket URL
2. Establishes the connection — Opens a secure WebSocket connection to your endpoint (either the direct endpoint or the URL returned from HTTP setup)
3. Sends initialization payload — If configured, sends the initialization JSON immediately after connection
4. Waits for handshake (if configured) — Waits for a ready message from the agent if a ready message type is configured
5. Exchanges audio — Sends audio chunks and receives audio responses according to the persona behavior, including attached test-case images when relevant
6. Records the transcript — Captures the full conversation for evaluation
7. Runs metrics — Evaluates the conversation against your configured metrics
8. Closes the connection — Cleanly terminates the WebSocket connection

​

Message Format

​

Outbound Audio (Coval → Your Agent)

• By default, Coval sends audio as JSON like {"type": "audio_chunk", "data": "..."}.
• You can customize that payload under Send Audio Template.
• If the template is just {{audio_data}}, Coval sends raw bytes.
• Audio data is base64-encoded when using JSON templates.

​

Inbound Audio (Your Agent → Coval)

• By default, Coval looks for incoming JSON audio messages where type is audio_chunk and the audio bytes are in data.
• Incoming audio can also be raw binary PCM when your integration sends binary frames.
• audio_encoding controls how incoming audio is decoded: pcm by default, or mp3.

​

Technical Requirements

​

Running Locally

ngrok http 8080
# Use the generated wss:// URL as your endpoint
# Note: if ngrok gives you an https:// tunnel URL, use the corresponding wss:// URL in Coval

​

Troubleshooting

​

Connection Failures

• Verify your endpoint starts with wss:// (not ws://, http://, or https://)
• Check that the URL is properly formatted with no trailing spaces

• Ensure your WebSocket server is running and accessible
• Check firewall rules allow inbound connections on the WebSocket port
• Verify the endpoint URL is correct

• Confirm your authorization header value is correct
• Check that the header format matches what your server expects
• Verify the API key or token hasn’t expired

​

Audio Quality Issues

• Check your Send Sample Rate and Receive Sample Rate settings match what your agent expects
• Verify your agent can handle the configured sample rates (8,000 / 16,000 / 24,000 / 48,000 Hz)
• Ensure audio encoding (pcm vs mp3) is supported by your agent

• If your agent expects 48,000 Hz but you set Send Sample Rate to 16,000 Hz, audio quality may be affected
• If your agent sends audio at 8,000 Hz but you set Receive Sample Rate to 48,000 Hz, audio quality may be affected

​

Message Handling Issues

• Ensure your agent sends audio responses in the configured JSON format with type and data fields
• Check that your agent is processing and responding to incoming audio messages
• Verify there are no errors in your agent’s logs

• Confirm your agent returns valid JSON for audio messages
• Check for proper encoding of special characters
• Ensure the type and data fields are properly formatted

• Verify your audio template matches your agent’s expected format
• Ensure audio encoding (pcm vs mp3) is supported by your agent
• Check that audio data is properly base64-encoded when using JSON templates
• For raw PCM frames, verify the format matches what Coval expects

• If your agent expects JSON, use a JSON send_media_template
• If your agent expects raw bytes, set send_media_template to exactly {{media_data}}
• Remember that {{media_data}} is base64-encoded when used inside a JSON template
• Include {{mime_type}} and {{media_name}} if your agent needs file metadata

​

Timeout Issues

• Verify your agent responds within a reasonable time
• Check for any blocking operations in your agent’s message handler
• Monitor your agent’s resource usage during simulations

​

Best Practices

1. Use persistent connections — Voice WebSocket agents should maintain the connection throughout the conversation
2. Handle reconnection gracefully — If your agent supports it, configure automatic reconnection
3. Log initialization payloads — Track the initialization JSON in your server logs for debugging
4. Implement health checks — Add a ping/pong mechanism to detect connection issues early
5. Secure your endpoint — Always use wss:// and implement proper authentication
6. Match sample rates — Set Send and Receive sample rates to match your agent’s capabilities