Skip to main content
This reference covers the transcript and audio formats Coval accepts when you submit an uploaded conversation for evaluation.

​
Required Fields

Essential transcript fields:
  • role: Must be one of "user", "assistant", "system", or "tool"
  • content: The actual message content (string)
  • beginning: Index position in the conversation (number)
  • end: End position in the conversation (number)

​
Optional Fields

  • start_timestamp: Unix timestamp for when the message started (number)
  • end_timestamp: Unix timestamp for when the message ended (number)
  • error: Error message if transcription failed (string)
  • transcriptionError: Boolean flag indicating transcription error
  • name: Name identifier for the message (string)

​
Supported Formats

The system primarily expects transcripts in OpenAI’s chat completion format:

​
Tool Call Messages

For tool call messages, the content field should contain a JSON string that can be parsed to extract tool information.

​
Tool Call Content Examples

​
Alternative Tool Call Formats

The system supports these formats in the content field:
  1. Function format: {"function": "name", "arguments": {...}}
  2. Tool format: {"tool": "name", ...} (other fields become arguments)
  3. Custom backend format: {tool_call: name, arguments: {...}}

​
Validation Rules

​
Content Limits

The request body is capped at 10 MB, covering the transcript, any inline base64 audio, and the rest of the payload together. Individual messages and message counts are not capped separately. Audio sent out of band — upload_id, audio_url, or audio_reference — is bounded by the audio limits rather than by the request body.

​
Role Validation

  • Only "user", "assistant", "system", and "tool" roles are accepted
  • Each message must have role, content, start_time, and end_time fields
  • start_time and end_time must be float values representing seconds

​
Role Normalization

For evaluation purposes, roles may be normalized:
  • "system" messages with tool call content may be treated as "tool" for display purposes
  • Tool calls in "system" role are automatically detected and parsed
  • The UI will display tool calls with appropriate icons and formatting regardless of the original role

​
Timing Validation

  • beginning and end values should be sequential integers
  • start_timestamp and end_timestamp should be valid Unix timestamps
  • If timestamps are provided, end_timestamp should be greater than start_timestamp

​
Audio Requirements

Whichever limit binds first applies. An hour of 16 kHz stereo audio is roughly 230 MB, so a full-length call fits within the size limit; narrowband telephony recordings are considerably smaller. Endpoints that issue an upload URL report the size limit as max_size_bytes, so you can check a file before transferring it rather than finding out from a rejected upload. Both stereo and mono audio files are supported. Stereo is recommended when available because speaker roles are assigned deterministically from channel position; mono roles are inferred from transcript content. Stereo (recommended): Upload audio with the agent and user on separate channels. Channel position determines role: Mono: Upload a single-channel file. Roles are assigned by classifying the transcript content with an LLM — typically accurate, but less reliable than channel-based stereo mapping for short or ambiguous conversations.

​
Filtering out Coval simulation calls

If your pipeline uploads every call your agent handles, it also uploads the calls Coval’s simulator placed to your agent. Those simulations are already evaluated inside their runs, so you may not want them duplicated in your conversations. Coval can drop these uploads for you at submit time:
  1. Read the X-Coval-Simulation-Id header that Coval delivers with every inbound simulation call. See Identifying simulation calls for how the header reaches your agent on different connection types.
  2. Store the header value with the call record, and pass it as metadata.coval_simulation_id when you submit the conversation.
  3. Ask Coval to enable the simulation filter for your organization.
Once enabled, a submit whose coval_simulation_id matches a simulation in your organization returns HTTP 200 without creating a conversation:
Filtered uploads are not billed and do not count against your conversation allowance. Submits without the metadata key, or whose value does not match a simulation, are processed normally, so the filter is safe to add to a pipeline that uploads simulation and production calls together.