Conversations

Structure of conversation objects

Conversations

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

Structure

{
  "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.

"name": "Order Refund Request #12345"

description (optional)

Additional context about the conversation.

"description": "Customer requesting refund for delayed order placed on 2024-01-15"

agents (optional)

Array of agent definitions. See 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 for details.

meta (optional)

Custom metadata object for storing any additional information.

"meta": {
  "customer_id": "cust_123",
  "priority": "high",
  "tags": ["refund", "escalation"]
}

Example

{
  "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:

{
  "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.