> ## Documentation Index
> Fetch the complete documentation index at: https://turnwise.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversations

> Structure of conversation objects

# Conversations

A conversation represents a single interaction thread between a user and one or more AI agents.

## Structure

```json theme={null}
{
  "conversations": [
    {
      "name": "Customer Support Request",
      "description": "User asking about order refund",
      "agents": [...],
      "messages": [...],
      "meta": {...}
    }
  ]
}
```

## Fields

### name (optional)

A human-readable name for the conversation. Useful for identifying specific conversations in the UI.

```json theme={null}
"name": "Order Refund Request #12345"
```

### description (optional)

Additional context about the conversation.

```json theme={null}
"description": "Customer requesting refund for delayed order placed on 2024-01-15"
```

### agents (optional)

Array of agent definitions. See [Agents](/data-format/agents) for details.

**Note**: If no agents are provided, TurnWise will automatically create a default "basic agent" for the conversation. This ensures all conversations have at least one agent reference.

### messages (required)

Array of message objects. See [Messages](/data-format/messages) for details.

### meta (optional)

Custom metadata object for storing any additional information.

```json theme={null}
"meta": {
  "customer_id": "cust_123",
  "priority": "high",
  "tags": ["refund", "escalation"]
}
```

## Example

```json theme={null}
{
  "conversations": [
    {
      "name": "Product Inquiry",
      "description": "Customer asking about wireless mouse compatibility",
      "agents": [
        {
          "name": "Sales Agent",
          "tools": {
            "search_products": {...}
          }
        }
      ],
      "messages": [
        {
          "role": "user",
          "content": "Do you have wireless mice that work with Mac?"
        },
        {
          "role": "assistant",
          "content": "Yes! We have several options..."
        }
      ],
      "meta": {
        "source": "website_chat",
        "session_id": "sess_abc123"
      }
    }
  ]
}
```

## Multiple Conversations

A single file can contain multiple conversations:

```json theme={null}
{
  "conversations": [
    {
      "name": "Conversation 1",
      "messages": [...]
    },
    {
      "name": "Conversation 2",
      "messages": [...]
    },
    {
      "name": "Conversation 3",
      "messages": [...]
    }
  ]
}
```

This is useful for batch importing data or organizing related conversations together.