JSON Format

This file is a digital representation of a conversation between a customer and a service agent (or AI). It contains all the important details of the conversation, including when it started, who participated, what was said, what actions occurred, and feedback given during the conversation.

What's Inside the File

Field	Type	Required	Description
`conversation_id`	string	Yes	Unique identifier for each conversation
`timestamp`	string	Yes	Start time in ISO 8601 format
`agent_id`	string	Yes	Agent or bot identifier
`is_resolved`	boolean	No	Whether the conversation was resolved (true/false)
`csat_score`	number	No	Customer satisfaction rating (0–5 scale)
`missing_info`	boolean	No	Flag for incomplete conversation data
`user_data`	object	No	User metadata — account type, subscription tier, preferences, etc. When provided and Personal Data profiles are configured, the system can match this data against profiles to provide personalized context (matched live when viewed or validated)
`additional_info`	object	No	Flexible metadata container for any extra information about the conversation. All keys are displayed in the "More Information" panel in the UI. See Additional Info for details
`messages`	array	Yes	Array of exchanged messages (see below)

Message Object

Field	Type	Required	Description
`message_id`	string	Yes	Unique message identifier
`conversation_id`	string	Yes	Parent conversation reference
`role`	string	Yes	Sender type: `"customer"`, `"agent"`, or `"system"`
`sender_id`	string	Yes	Unique sender identifier
`content`	string	Yes	Message text
`timestamp`	string	Yes	ISO 8601 send time
`logs`	array	No	Array of log entries documenting actions taken during message generation
`feedback`	object	No	Thumbs-up/thumbs-down reaction with optional note

Both JSON array ([{...}, {...}]) and JSONL (one object per line) formats are accepted.

JSON Format Example

[
  {
    "conversation_id": "conv-001",
    "timestamp": "2026-03-10T09:00:00.000Z",
    "agent_id": "support-agent",
    "is_resolved": true,
    "csat_score": 4.5,
    "user_data": {
      "subscription_tier": "premium",
      "customer_name": "Sarah Johnson",
      "renewal_date": "April 15, 2026"
    },
    "additional_info": {
      "language": "en",
      "agent_version": "2.1.0",
      "channel": "web_chat"
    },
    "messages": [
      {
        "message_id": "msg-01",
        "conversation_id": "conv-001",
        "role": "customer",
        "sender_id": "user-sarah",
        "content": "Hi, can you help me with my billing? I want to know my plan details and how to reset my password.",
        "timestamp": "2026-03-10T09:00:00.000Z"
      },
      {
        "message_id": "msg-02",
        "conversation_id": "conv-001",
        "role": "agent",
        "sender_id": "support-agent",
        "content": "Hello Sarah! You're on our Premium plan at $99/month. Your renewal date is April 15, 2026. To reset your password, go to Settings > Security > Change Password. Your new password must be at least 8 characters with one uppercase letter and one number.",
        "timestamp": "2026-03-10T09:00:15.000Z",
        "logs": [
          {
            "name": "tool_call_1",
            "tool": "GetAccountDetails",
            "status": "completed",
            "content": {
              "account_id": "acct-sarah-001",
              "plan": "Premium",
              "monthly_price": 99,
              "currency": "USD",
              "renewal_date": "2026-04-15"
            }
          },
          {
            "name": "context",
            "content": [
              {
                "id": "kb-pw-reset-001",
                "content": "Password Reset Guide: Navigate to Settings > Security > Change Password. Requirements: minimum 8 characters, at least one uppercase letter and one number."
              }
            ]
          },
          {"name": "personal_data"}
        ],
        "feedback": {
          "value": "positive",
          "note": "Helpful and accurate response"
        }
      },
      {
        "message_id": "msg-03",
        "conversation_id": "conv-001",
        "role": "customer",
        "sender_id": "user-sarah",
        "content": "Thank you, that's exactly what I needed!",
        "timestamp": "2026-03-10T09:01:00.000Z"
      }
    ]
  }
]

Logs

Each log entry documents an action or step that occurred during message generation. Log entries use name and content fields.

Field	Type	Required	Description
`name`	string	Yes	Label for the logged action
`content`	string, array, or null	No	Details or result of the action

"logs": [
  {"name": "Account Lookup", "content": "Found account: Premium tier, active since 2024"},
  {"name": "Database Query", "content": "Retrieved 3 matching records"},
  {"name": "Processing", "content": null}
]

Context Logs

Context logs are a special category of log entries that carry the knowledge sources (retrieved documents) the agent used to generate its response. These are critical for validators like the hallucination detector and contradiction detector.

A log entry qualifies as a context log when the name field contains "context" (case-insensitive).

Plain text format

A single string with all context content. This works for the contradiction detector but displays as a plain text block in the UI (no source cards).

{
  "name": "context",
  "content": "All the context the agent used to generate the response..."
}

Structured format (recommended)

When content is an array of objects with id and content fields, each item renders as an expandable knowledge source card in the UI:

{
  "name": "context",
  "content": [
    {
      "id": "kb-article-001",
      "content": "Password Reset Guide: Navigate to Settings > Security > Change Password. Requirements: minimum 8 characters, at least one uppercase letter and one number."
    },
    {
      "id": "kb-article-002",
      "content": "Account Security: We recommend enabling two-factor authentication for all accounts."
    }
  ]
}

The structured format is recommended because:

Each source displays as an individual expandable card in the conversation detail view
The contradiction detector can reference specific knowledge items when flagging issues
Sources are easier to review and audit

Personal Data Log

The personal_data log indicates that an agent message used personalized data from the Personal Data Engine (PDE) to generate its response.

{
  "name": "personal_data"
}

No content is needed — this is a presence indicator only. When the contradiction detector is configured with context_sources: "both" or "personal_data", and personal_data_check_scope is set to "flagged", it uses this log to identify which agent messages should be checked against the user's personal data profile.

How it works: When a conversation has user_data, the system matches it against configured Personal Data profiles live (when the conversation is viewed or validated — not at ingestion time). The personal_data log on a message tells the validator "this message used personalized data." When personal_data_check_scope is "flagged", only messages with this log are checked. When set to "all" (the default), all agent messages are checked regardless of this log.

The log name is configurable via the personal_data_log_name setting in the contradiction detector configuration (default: "personal_data").

Tool Call Logs

Tool call logs record the tools (functions) your agent called and their responses during message generation. The tools hallucination detector uses these logs to verify that the agent's response accurately reflects the data returned by its tools.

Log entry fields

Field	Type	Required	Description
`name`	string	Yes	Log name with a `"tool_call"` prefix (e.g. `"tool_call_1"`, `"tool_call_GetBalance"`)
`tool`	string	No	The tool/function name (e.g. `"GetBalance"`, `"SearchOrders"`). Used for display and filtering. Falls back to `name` if not provided
`status`	string	No	Completion status. Only `"completed"` or `"success"` are processed. Logs with `"error"`, `"skipped"`, or other values are ignored. If omitted, the log is processed normally
`content`	object, array, or string	Yes	The tool's response data. Can be a JSON object, array, JSON-encoded string, or plain text. Empty content causes the log to be skipped

Example

"logs": [
  {
    "name": "tool_call_1",
    "tool": "GetAccountDetails",
    "status": "completed",
    "content": {
      "account_id": "acct-001",
      "plan": "Premium",
      "monthly_price": 99,
      "currency": "USD"
    }
  },
  {
    "name": "tool_call_2",
    "tool": "SearchKnowledgeBase",
    "status": "completed",
    "content": [
      {"title": "Password Reset Guide", "body": "Navigate to Settings > Security > Change Password."}
    ]
  }
]

How the name prefix works

A log entry is recognized as a tool call when its name starts with one of the configured prefixes. The default prefix is "tool_call", so any of these names will match:

"tool_call_1", "tool_call_2", ...
"tool_call_GetBalance"
"tool_call" (the prefix itself)

The prefix list is configurable via the tool_log_names setting in the tools hallucination detector configuration.

Content formats

The content field accepts several formats:

JSON object (recommended) — structured tool response data:

{
  "content": {
    "balance": 500,
    "currency": "USD",
    "last_transaction": "2026-03-10"
  }
}

JSON array — list of results:

{
  "content": [
    {"id": "order-1", "status": "shipped"},
    {"id": "order-2", "status": "processing"}
  ]
}

Plain text string — when the tool returns a simple text response:

{
  "content": "Transfer completed successfully. Reference: TXN-12345"
}

Multiple tool calls per message

An agent message can have multiple tool call logs. Each tool call is validated independently — the detector checks the agent's response against the data returned by each tool:

"logs": [
  {
    "name": "tool_call_1",
    "tool": "GetBalance",
    "status": "completed",
    "content": {"balance": 500, "currency": "USD"}
  },
  {
    "name": "tool_call_2",
    "tool": "GetTransactions",
    "status": "completed",
    "content": [
      {"date": "2026-03-09", "amount": -50, "description": "Coffee Shop"},
      {"date": "2026-03-08", "amount": 1000, "description": "Salary Deposit"}
    ]
  }
]

A claim in the agent's response is only flagged as unsupported if it contradicts all tool sources. If any single tool's data supports the claim, it is considered valid.

Filtering by tool name

You can configure the tools hallucination detector to only check specific tools using the tool_names setting. This filters on the tool field (not the name field):

Exact match: "GetBalance" matches only that tool
Wildcard prefix: "tools_*" matches "tools_getBalance", "tools_search", etc.
Empty list (default): all tool call logs are included

Tip: Each agent message is validated against only its own tool call logs, not logs from other messages in the conversation. This means tool data is always scoped to the message that used it.

Additional Info

The additional_info field is a flexible metadata container — a key-value object where you can store any extra information about the conversation. All keys are displayed in the "More Information" panel in the UI, each as its own expandable section.

"additional_info": {
  "language": "en",
  "agent_version": "2.1.0",
  "channel": "web_chat",
  "department": "billing",
  "session_duration_seconds": 340
}

You can use any keys you want. Common examples:

Key	Description
`language`	Conversation language code
`agent_version`	Version of the agent that handled the conversation
`channel`	Communication channel (web_chat, phone, email, etc.)
`department`	Department or team that handled the conversation
`region`	Geographic region of the customer
`session_duration_seconds`	Total session duration

Values can be strings, numbers, booleans, or nested objects. Nested objects are rendered as key-value tables in the UI.

Note: The additional_info field is purely for your custom metadata. Personal Data profile matching happens live when the conversation is viewed or validated — no system-generated keys are added to this field during ingestion.

Feedback

Message-level feedback captures user reactions to agent responses.

Field	Type	Required	Description
`value`	string	Yes	`"positive"` or `"negative"`
`note`	string	No	Free-text explanation

"feedback": {
  "value": "positive",
  "note": "Helpful and accurate response"
}

How can I adjust my JSON to link it to the correct agent?

You need to update the agent_id field in your JSON to match the ID of the agent you want to link. You can find the agent's ID in their settings: click the three-dot menu next to the agent and look under the General section to see the Agent ID. Enter that ID in the agent_id field in your JSON file.

What's Inside the File​

Message Object​

JSON Format Example​

Logs​

Context Logs​

Plain text format​

Structured format (recommended)​

Personal Data Log​

Tool Call Logs​

Log entry fields​

Example​

How the name prefix works​

Content formats​

Multiple tool calls per message​

Filtering by tool name​

Additional Info​

Feedback​

How can I adjust my JSON to link it to the correct agent?​