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

# Messages

> Understanding message structure and roles

# Messages

Messages represent individual turns in a conversation. Each message has a role and content. The order is automatically inferred from the message's position in the array.

## Structure

```json theme={null}
{
  "role": "assistant",
  "content": "How can I help you today?",
  "steps": [...],
  "meta": {...}
}
```

## Required Fields

### role

The role of the message sender. Must be one of:

| Role        | Description                    |
| ----------- | ------------------------------ |
| `user`      | Message from the human user    |
| `assistant` | Message from the AI agent      |
| `system`    | System instructions or context |
| `tool`      | Output from a tool execution   |

### content

The text content of the message. This field is required.

```json theme={null}
"content": "I'd like to return my order"
```

## Optional Fields

### steps

Array of processing steps. See [Steps](/data-format/steps) for details. Typically used for assistant messages to capture reasoning and tool usage.

### meta

Custom metadata for the message.

```json theme={null}
"meta": {
  "timestamp": "2024-01-20T14:30:00Z",
  "latency_ms": 150
}
```

## Role Examples

### User Messages

```json theme={null}
{
  "role": "user",
  "content": "I need to cancel my subscription"
}
```

### Assistant Messages

```json theme={null}
{
  "role": "assistant",
  "content": "I can help you cancel. Can you confirm your account email?",
  "steps": [
    {
      "thinking": "User wants to cancel. Need account info first.",
      "output_content": "I can help you cancel. Can you confirm your account email?"
    }
  ]
}
```

### System Messages

```json theme={null}
{
  "role": "system",
  "content": "You are a helpful customer service agent for Acme Corp."
}
```

### Tool Messages

```json theme={null}
{
  "role": "tool",
  "content": "{\"order_id\": \"ORD-123\", \"status\": \"shipped\"}",
  "meta": {
    "tool_name": "lookup_order"
  }
}
```

## Best Practices

<Tip>
  **Message order is automatic**: The order of messages is automatically inferred from their position in the array. Keep messages in chronological order.
</Tip>

<Tip>
  **Use steps for assistant messages**: Capturing the reasoning process enables more detailed evaluation of agent behavior.
</Tip>

<Tip>
  **Store raw content**: Keep the original message content even if you also use steps, for easier human review.
</Tip>