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

# Conversations

> View and manage bot conversations

The Conversations page shows all interactions between your bot and users across all connected channels. Each conversation maintains message history and context for better AI responses.

<Frame caption="List of bot conversations">
  <img src="https://mintcdn.com/chatbotplatform/QhGUbEN05MzAjt2K/images/screenshots/06-conversations/02_conversations_list.png?fit=max&auto=format&n=QhGUbEN05MzAjt2K&q=85&s=9e55d327938a117a7e0dce8efdddc1bf" alt="Conversations list" width="1920" height="941" data-path="images/screenshots/06-conversations/02_conversations_list.png" />
</Frame>

## Overview

A conversation is a grouped series of messages between a user and your bot. Conversations are automatically created and managed based on your bot's message detection settings.

<Frame caption="Single conversation with message history">
  <img src="https://mintcdn.com/chatbotplatform/3g1ISN1rzBY15nxY/images/screenshots/06-conversations/01_conversation_with_detection.png?fit=max&auto=format&n=3g1ISN1rzBY15nxY&q=85&s=8bfb25e5c3a66da99ba0df846f666c03" alt="Conversation detail" width="1920" height="941" data-path="images/screenshots/06-conversations/01_conversation_with_detection.png" />
</Frame>

## Conversation Structure

Each conversation includes:

* **Unique ID**: Persistent identifier
* **User Information**: Platform, username, display name
* **Channel**: Which platform the conversation is on
* **Message History**: All messages in chronological order
* **Metadata**: Timestamps, platform-specific data
* **Context**: Recent messages sent to AI integration

## Viewing Conversations

<Steps>
  <Step title="Navigate to Conversations">
    From your bot page, click **Conversations** in the sidebar.
  </Step>

  <Step title="Browse List">
    See all conversations ordered by most recent activity.
  </Step>

  <Step title="Open Conversation">
    Click on a conversation to view full message history.
  </Step>

  <Step title="Review Messages">
    See user messages, bot responses, and timestamps.
  </Step>
</Steps>

## Conversation Attributes

### User Information

* **User ID**: Unique platform identifier
* **Username**: Platform username (if available)
* **Display Name**: User's display name
* **Platform**: telegram, slack, discord, etc.

### Channel Information

* **Channel Type**: Platform name
* **Channel ID**: Unique channel identifier
* **Chat ID**: Specific chat or thread identifier
* **Metadata**: Platform-specific context

### Message History

* **Messages**: Ordered list of user and assistant messages
* **Timestamps**: When each message was sent
* **Roles**: `user`, `assistant`, or `system`
* **Content**: Message text or multimodal content (text + images)
* **Message Types**: Regular messages or synthetic messages (system-generated)

### Synthetic Messages

Synthetic messages are system-generated messages injected into conversations by features like reminders:

* **Created by System**: Not sent by users, but appear as user messages in the conversation
* **Trigger Bot Responses**: Bot responds as if the user sent the message
* **Scheduled**: Created at specific times (e.g., reminder triggers)
* **Use Cases**: Reminders, scheduled notifications, automated follow-ups

Example: When a reminder triggers, a synthetic message is created in the conversation prompting the bot to remind the user about something.

## Message Detection

How messages are grouped into conversations depends on your bot's detection settings:

### Thread-Based (Slack)

Each Slack thread is a separate conversation:

```
Main Message → Conversation A
  ↳ Reply 1 → Conversation A
  ↳ Reply 2 → Conversation A
New Main Message → Conversation B
```

### User-Based (Telegram Groups)

Each user in a group has their own conversation:

```
Group: Support
  User A → Conversation A
  User B → Conversation B
  User A again → Still Conversation A
```

### Session-Based (Custom)

Conversations expire after inactivity:

```
User Message (10:00) → Conversation A
User Message (10:05) → Conversation A
[30 minute timeout]
User Message (10:40) → Conversation B (new)
```

Learn more in [Should Respond Detection](/bots/behaviors/should-respond).

## Context Window

The context window determines how many recent messages are included when calling your AI integration:

| Window Size  | Messages Sent     | Use Case           |
| ------------ | ----------------- | ------------------ |
| 5            | Last 5 messages   | Short-term context |
| 10 (default) | Last 10 messages  | Balanced           |
| 20           | Last 20 messages  | Long conversations |
| 50+          | Last 50+ messages | Maximum context    |

### Configuring Context Window

Set this in bot behavior settings:

<Steps>
  <Step title="Go to Bot Settings">
    Navigate to your bot's settings page.
  </Step>

  <Step title="Find Context Window">
    Look for the **Context Window** or **Message History** setting.
  </Step>

  <Step title="Set Size">
    Enter the number of messages to include (e.g., 10).
  </Step>

  <Step title="Save">
    Click **Save** to apply changes.
  </Step>
</Steps>

<Callout type="info">
  Larger context windows use more tokens and increase costs, but provide better context for the AI.
</Callout>

## Conversation Lifecycle

### Creation

Conversations are created automatically when:

* First message from a new user
* New thread started (Slack)
* Session timeout expired

### Updates

Conversations are updated when:

* User sends new message
* Bot sends response
* Context changes (group, thread, etc.)

### Archival

Conversations may be archived:

* After long inactivity
* When user blocks bot
* Manual archival (coming soon)

## Searching Conversations

Search and filter conversations by:

* **User**: Find conversations with specific users
* **Date Range**: Messages within timeframe
* **Channel**: Filter by platform
* **Content**: Search message text (coming soon)

## Privacy and Data

### Data Storage

Conversations are stored:

* Encrypted at rest
* Per-team isolation
* Retained according to your plan

### Data Access

* **Team Members**: Can view all team conversations
* **API Access**: Retrieve via API with authentication
* **Exports**: Export conversation history (coming soon)

### Data Deletion

Delete conversations:

* Individual conversations (coming soon)
* Bulk deletion (coming soon)
* Account deletion (removes all data)

<Callout type="warning">
  Deleted conversations cannot be recovered. Ensure you export any needed data first.
</Callout>

## Conversation Insights

Use conversations to:

* **Improve Bot Performance**: See where bot struggles
* **Improve Prompts**: Identify common misunderstandings
* **Track Usage**: Understand user behavior
* **Debug Issues**: Investigate error reports

## Best Practices

<CardGroup cols={2}>
  <Card title="Review Regularly" icon="eye">
    Check conversations to identify improvements
  </Card>

  <Card title="Right Context Size" icon="window">
    Configure message history for your use case
  </Card>

  <Card title="Privacy Awareness" icon="lock">
    Handle user data responsibly
  </Card>

  <Card title="Use Insights" icon="chart-line">
    Learn from conversation patterns
  </Card>
</CardGroup>

## API Access

Retrieve and manage conversations programmatically using the API.

<AccordionGroup>
  <Accordion title="List bot conversations">
    <Tabs>
      <Tab title="cURL">
        ```bash theme={null}
        curl https://api.chatbotplatform.io/v1/bots/bot_123/conversations \
          -H "Authorization: Bearer YOUR_API_KEY"
        ```
      </Tab>

      <Tab title="JavaScript">
        ```javascript theme={null}
        const response = await fetch('https://api.chatbotplatform.io/v1/bots/bot_123/conversations', {
          headers: {
            'Authorization': 'Bearer YOUR_API_KEY'
          }
        });
        const { data } = await response.json();
        ```
      </Tab>

      <Tab title="PHP">
        ```php theme={null}
        $response = Http::withToken('YOUR_API_KEY')
            ->get('https://api.chatbotplatform.io/v1/bots/bot_123/conversations');

        $conversations = $response->json('data');
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        response = requests.get(
            'https://api.chatbotplatform.io/v1/bots/bot_123/conversations',
            headers={'Authorization': 'Bearer YOUR_API_KEY'}
        )
        conversations = response.json()['data']
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Get conversation details">
    <Tabs>
      <Tab title="cURL">
        ```bash theme={null}
        curl https://api.chatbotplatform.io/v1/conversations/conv_123 \
          -H "Authorization: Bearer YOUR_API_KEY"
        ```
      </Tab>

      <Tab title="JavaScript">
        ```javascript theme={null}
        const response = await fetch('https://api.chatbotplatform.io/v1/conversations/conv_123', {
          headers: {
            'Authorization': 'Bearer YOUR_API_KEY'
          }
        });
        const conversation = await response.json();
        ```
      </Tab>

      <Tab title="PHP">
        ```php theme={null}
        $response = Http::withToken('YOUR_API_KEY')
            ->get('https://api.chatbotplatform.io/v1/conversations/conv_123');

        $conversation = $response->json();
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        response = requests.get(
            'https://api.chatbotplatform.io/v1/conversations/conv_123',
            headers={'Authorization': 'Bearer YOUR_API_KEY'}
        )
        conversation = response.json()
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Get conversation messages">
    <Tabs>
      <Tab title="cURL">
        ```bash theme={null}
        curl https://api.chatbotplatform.io/v1/conversations/conv_123/messages \
          -H "Authorization: Bearer YOUR_API_KEY"
        ```
      </Tab>

      <Tab title="JavaScript">
        ```javascript theme={null}
        const response = await fetch('https://api.chatbotplatform.io/v1/conversations/conv_123/messages', {
          headers: {
            'Authorization': 'Bearer YOUR_API_KEY'
          }
        });
        const { data } = await response.json();
        ```
      </Tab>

      <Tab title="PHP">
        ```php theme={null}
        $response = Http::withToken('YOUR_API_KEY')
            ->get('https://api.chatbotplatform.io/v1/conversations/conv_123/messages');

        $messages = $response->json('data');
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        response = requests.get(
            'https://api.chatbotplatform.io/v1/conversations/conv_123/messages',
            headers={'Authorization': 'Bearer YOUR_API_KEY'}
        )
        messages = response.json()['data']
        ```
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

<Card title="Complete API Reference" icon="code" href="https://app.chatbotplatform.io/openapi">
  View the full API specification with all endpoints, parameters, and response schemas.
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Message History" icon="clock-rotate-left" href="/bots/conversations/message-history">
    Configure context window
  </Card>

  <Card title="Should Respond Detection" icon="magnifying-glass" href="/bots/behaviors/should-respond">
    Control when bot responds
  </Card>
</CardGroup>