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

# Browse and Search Agent Chat Conversations in BotSmith

> Browse every conversation your BotSmith agents have had, read full message transcripts, and retrieve conversation data programmatically via the REST API.

BotSmith stores every conversation your agents have. From the Conversations view in your agent builder, you can browse conversation history, read full transcripts, and monitor response quality.

## Accessing Conversations

<Steps>
  <Step title="Open the agent builder">
    Navigate to your agent from the **Dashboard** and click to open it.
  </Step>

  <Step title="Click the Conversations tab">
    Select **Conversations** in the top navigation of the agent builder.
  </Step>
</Steps>

A list of all chat sessions for that agent appears, sorted by most recent first. Each row shows a short preview of the first user message alongside the session timestamp.

## Reading a Transcript

Click any conversation in the list to open the full message exchange. The transcript view displays:

* **User messages** — aligned to the right, showing exactly what visitors typed.
* **Agent responses** — aligned to the left, showing exactly what your agent replied.

Scroll through the thread from top to bottom to follow the conversation in chronological order.

## Conversation Metadata

Every conversation entry surfaces the following fields:

| Field              | Description                                               |
| ------------------ | --------------------------------------------------------- |
| **id**             | Unique conversation identifier                            |
| **chatbot\_id**    | The agent this conversation belongs to                    |
| **session\_id**    | The visitor's browser session identifier (if available)   |
| **user\_name**     | The visitor's name, if provided during the chat           |
| **user\_email**    | The visitor's email address, if provided during the chat  |
| **status**         | Conversation status: `active`, `resolved`, or `escalated` |
| **rating**         | Optional 1–5 star rating submitted by the visitor         |
| **created\_at**    | Timestamp when the first message was sent                 |
| **updated\_at**    | Timestamp of the most recent message                      |
| **message\_count** | Total number of messages exchanged in this session        |

## Understanding Conversation IDs

Each conversation is assigned a unique identifier. This ID is:

* Used as the path parameter when querying conversations and messages via the REST API.
* Included in webhook payloads when you configure outbound webhooks for your agent.

Keep the conversation ID handy whenever you need to reference a specific session in integrations or support queries.

## API Access to Conversations

You can retrieve conversations and their messages programmatically using the BotSmith REST API. See the [Chat API Reference](/api-reference/chat) for full request and response schemas.

To fetch all conversations for a specific agent, send a `GET` request with your bearer token:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://app.botsmith.ai/api/chat/conversations/YOUR_CHATBOT_ID"
```

Replace `YOUR_TOKEN` with your API token from **Account → API Keys** and `YOUR_CHATBOT_ID` with the agent's ID, visible in the agent builder URL.

To fetch all messages within a specific conversation, use the conversation's ID:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://app.botsmith.ai/api/chat/messages/YOUR_CONVERSATION_ID"
```

<CodeGroup>
  ```json Conversation list response (example) theme={null}
  [
    {
      "id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "chatbot_id": "bot_abc123",
      "session_id": "sess_xyz789",
      "user_name": "Jane Smith",
      "user_email": "jane@example.com",
      "status": "active",
      "rating": 5,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:45:00Z",
      "message_count": 8
    }
  ]
  ```

  ```json Message list response (example) theme={null}
  [
    {
      "id": "msg_111aaa",
      "role": "user",
      "content": "What are your business hours?",
      "timestamp": "2025-01-15T10:30:00Z"
    },
    {
      "id": "msg_222bbb",
      "role": "assistant",
      "content": "We're open Monday–Friday, 9 AM to 6 PM EST.",
      "timestamp": "2025-01-15T10:30:02Z"
    }
  ]
  ```
</CodeGroup>