Skip to main content

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