Skip to main content
This reference covers the transcript and audio formats Coval accepts when you upload a 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 monitoring and 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.