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

# Uploading Conversations

> Transcript and audio formats for uploading conversations to Coval for evaluation.

This reference covers the transcript and audio formats Coval accepts when you upload a [conversation](/concepts/conversations/overview) for evaluation.

### Required Fields

<Info>
  **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)
</Info>

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

<Tabs>
  <Tab title="OpenAI Format (Recommended)">
    The system primarily expects transcripts in OpenAI's chat completion format:

    ```json theme={null}
    [
      {
        "role": "user",
        "content": "Hello, I would like assistance.",
        "start_time": 0.0,
        "end_time": 3.2
      },
      {
        "role": "assistant", 
        "content": "Of course! How can I help you today?",
        "start_time": 3.2,
        "end_time": 6.8
      },
      {
        "role": "user",
        "content": "I'm having an issue with my recent order.",
        "start_time": 6.8,
        "end_time": 10.5
      },
      {
        "role": "assistant",
        "content": "I'm sorry to hear that. Could you provide me with your order number?",
        "start_time": 10.5,
        "end_time": 14.2
      }
    ]
    ```
  </Tab>

  <Tab title="Extended Studio Format">
    For detailed transcripts with timing information:

    ```json theme={null}
    [
      {
        "role": "user",
        "content": "Hello, I would like assistance.",
        "start_time": 0.0,
        "end_time": 3.2,
        "beginning": 0,
        "end": 1,
        "start_timestamp": 1640995200,
        "end_timestamp": 1640995210
      },
      {
        "role": "assistant",
        "content": "Of course! How can I help you today?",
        "start_time": 3.2,
        "end_time": 6.8,
        "beginning": 1,
        "end": 2,
        "start_timestamp": 1640995210,
        "end_timestamp": 1640995220
      }
    ]
    ```
  </Tab>

  <Tab title="Raw Text Format">
    The system can also accept raw text, which will be automatically converted:

    ```
    User: Hello, I would like assistance.
    Assistant: Of course! How can I help you today?
    User: I'm having an issue with my recent order.
    Assistant: I'm sorry to hear that. Could you provide me with your order number?
    ```
  </Tab>
</Tabs>

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

<CodeGroup>
  ```json Simple Tool Call theme={null}
  {
    "role": "tool",
    "content": "{\"tool\": \"waiting_on_customer\"}",
    "start_time": 12.0,
    "end_time": 12.5,
    "beginning": 3,
    "end": 4
  }
  ```

  ```json Tool Call with Arguments theme={null}
  {
    "role": "tool", 
    "content": "{\"query\": \"search term\", \"tool\": \"query_knowledge\"}",
    "start_time": 15.2,
    "end_time": 15.8,
    "beginning": 4,
    "end": 5
  }
  ```

  ```json Standard Tool Call Format theme={null}
  {
    "role": "tool",
    "content": "{\"tool_call\": \"function_name\", \"arguments\": {\"param1\": \"value1\"}}",
    "start_time": 18.5,
    "end_time": 19.1,
    "beginning": 5,
    "end": 6,
    "name": "function_name"
  }
  ```

  ```json System Role with Tool Call theme={null}
  {
    "role": "system",
    "content": "{\"tool_call\": \"database_query\", \"arguments\": {\"table\": \"users\"}}",
    "start_time": 22.0,
    "end_time": 22.3,
    "beginning": 6,
    "end": 7
  }
  ```
</CodeGroup>

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

<Warning>
  **Important limits to keep in mind:**

  * **Individual message content**: Maximum 1,000 characters
  * **Total transcript size**: Maximum 40MB
  * **Number of messages**: Maximum 1,000 messages per transcript
</Warning>

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

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:

| Channel   | Position | Role  |
| --------- | -------- | ----- |
| Channel 0 | Left     | Agent |
| Channel 1 | Right    | User  |

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