JSON Formats for Conversations

Tovix accepts conversation logs as JSON. This page shows the minimal format and the recommended format with timestamps and citations, so you can get the best evaluations out of your data.

Minimal format (quick start)

This is the smallest valid payload. Use this if you just want to upload transcripts quickly.

{
  "conversation_id": "conv_123",
  "messages": [
    {
      "role": "user",
      "content": "Hi, my order hasn't arrived yet."
    },
    {
      "role": "assistant",
      "content": "Sorry about that! Can you share your order ID?"
    }
  ]
}
  • conversation_id: a string that uniquely identifies the conversation.
  • messages: array of message objects.
    • role: one of "system", "user", "assistant", "tool".
    • content: the text of the message.

Recommended format (with timestamps & responsiveness)

Add timestamps (and optionally latency) to evaluate responsiveness and see how long users wait for a reply.

{
  "conversation_id": "conv_123",
  "channel": "web_chat",
  "started_at": "2025-12-02T16:15:23Z",
  "ended_at": "2025-12-02T16:32:10Z",
  "messages": [
    {
      "index": 0,
      "role": "user",
      "content": "Hi, my order hasn't arrived yet.",
      "timestamp": "2025-12-02T16:15:23Z"
    },
    {
      "index": 1,
      "role": "assistant",
      "content": "Sorry about that! Can you share your order ID?",
      "timestamp": "2025-12-02T16:15:30Z",
      "latency_ms": 7000
    }
  ]
}

Optional but useful fields:

  • channel: where the conversation happened (e.g. "web_chat", "email").
  • started_at, ended_at: ISO timestamps for the whole conversation.
  • index: turn index starting from 0.
  • timestamp: ISO timestamp for each message.
  • latency_ms: assistant response time in milliseconds since the previous user message.

Adding citations & evidence (for factuality)

If your agent uses retrieval or external tools, you can include citations so Tovix can analyze how well answers are grounded in real data.

Simple inline citations

{
  "conversation_id": "conv_456",
  "messages": [
    {
      "role": "assistant",
      "content": "Your order #12345 is in transit and should arrive tomorrow.",
      "timestamp": "2025-12-02T16:16:05Z",
      "citations": [
        {
          "type": "internal_kb",
          "source_id": "order_12345",
          "uri": "https://internal.acme.com/orders/12345",
          "title": "Order 12345 status",
          "snippet": "Status: In transit. Estimated delivery: 2025-12-03.",
          "retrieved_at": "2025-12-02T16:16:02Z"
        }
      ]
    }
  ]
}

Using a shared evidence section

{
  "conversation_id": "conv_789",
  "evidence": [
    {
      "id": "ev_1",
      "type": "internal_kb",
      "source_id": "order_12345",
      "uri": "https://internal.acme.com/orders/12345",
      "title": "Order 12345 status",
      "snippet": "Status: In transit. Estimated delivery: 2025-12-03.",
      "retrieved_at": "2025-12-02T16:16:02Z"
    }
  ],
  "messages": [
    {
      "role": "assistant",
      "content": "Your order #12345 is in transit and should arrive tomorrow.",
      "timestamp": "2025-12-02T16:16:05Z",
      "citations": [
        { "evidence_id": "ev_1" }
      ]
    }
  ]
}

Summary

  • Minimum required: conversation_id, messages[], role, content.
  • Recommended: timestamps (timestamp), turn indices (index), and channel.
  • For factuality: use citations on assistant messages, optionally with a shared evidence array.

For additional support, please contact your administrator.