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

# BotSmith Chat API: Send Messages and Get Transcripts

> Send chat messages to BotSmith agents, retrieve conversation history, and access message transcripts via the public and authenticated REST API.

The Chat API lets you interact with BotSmith agents programmatically — send user messages, retrieve conversation lists, and fetch message transcripts. Public endpoints require no authentication, making them suitable for widget integrations and third-party site embeds.

## Public: Get Agent Info

**`GET /api/public/chatbot/{chatbot_id}`**

Returns the public-facing configuration for an agent — name, welcome message, and widget appearance settings. No authentication required. Use this to render a custom chat UI with the correct branding.

```bash theme={null}
curl https://app.botsmith.ai/api/public/chatbot/CHATBOT_ID
```

**Path parameters:**

<ParamField path="chatbot_id" type="string" required>
  The unique ID of the agent.
</ParamField>

**Response (`200 OK`):**

```json theme={null}
{
  "id": "abc123",
  "name": "Support Bot",
  "welcome_message": "Hi! How can I help you today?",
  "primary_color": "#7c3aed",
  "secondary_color": "#a78bfa",
  "accent_color": "#ec4899",
  "logo_url": null,
  "avatar_url": null,
  "font_family": "Inter, system-ui, sans-serif",
  "font_size": "medium",
  "bubble_style": "rounded",
  "widget_theme": "light",
  "widget_position": "bottom-right",
  "widget_size": "medium",
  "auto_expand": false,
  "lead_capture_enabled": true,
  "powered_by_text": null
}
```

<ResponseField name="id" type="string">
  The agent's unique identifier.
</ResponseField>

<ResponseField name="name" type="string">
  The agent's display name.
</ResponseField>

<ResponseField name="welcome_message" type="string">
  The first message shown to users when the chat widget opens.
</ResponseField>

<ResponseField name="primary_color" type="string">
  Primary hex color for the widget UI.
</ResponseField>

<ResponseField name="widget_position" type="string">
  Where the widget appears on the page: `"bottom-right"`, `"bottom-left"`, `"top-right"`, or `"top-left"`.
</ResponseField>

<ResponseField name="lead_capture_enabled" type="boolean">
  Whether the widget shows a lead capture form before the first message.
</ResponseField>

<ResponseField name="powered_by_text" type="string | null">
  Custom branding text shown at the bottom of the widget (available on paid plans), or `null` to show the default branding.
</ResponseField>

***

## Public: Send a Message

**`POST /api/public/chat/{chatbot_id}`**

Sends a message to a publicly accessible agent. No authentication required — this endpoint is designed for end-users visiting your website.

To maintain conversation context across multiple messages, pass the same `session_id` in every request for a given user session. BotSmith uses the `session_id` to group messages into a single conversation thread.

<Note>
  The agent must have `public_access` enabled and `status` set to `"active"`. If the agent is inactive, this endpoint returns a `400` error.
</Note>

```bash theme={null}
curl -X POST https://app.botsmith.ai/api/public/chat/CHATBOT_ID \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are your business hours?",
    "session_id": "sess_xyz789",
    "user_name": "Jane Smith",
    "user_email": "jane@example.com"
  }'
```

**Path parameters:**

<ParamField path="chatbot_id" type="string" required>
  The unique ID of the agent to chat with.
</ParamField>

**Request body:**

<ParamField body="message" type="string" required>
  The user's message text.
</ParamField>

<ParamField body="session_id" type="string" required>
  A client-generated session identifier. Use the same value across all messages from the same user session so the agent retains conversation context. Generate a UUID on first load and store it for the duration of the session.
</ParamField>

<ParamField body="user_name" type="string">
  Optional display name for the user. Stored against the conversation for reference.
</ParamField>

<ParamField body="user_email" type="string">
  Optional email address for the user. Stored against the conversation for reference.
</ParamField>

**Response (`200 OK`):**

```json theme={null}
{
  "message": "We are open Monday through Friday, 9am to 6pm Eastern Time.",
  "conversation_id": "conv_abc123",
  "session_id": "sess_xyz789"
}
```

<ResponseField name="message" type="string">
  The agent's reply to the user's message.
</ResponseField>

<ResponseField name="conversation_id" type="string">
  The unique ID of the conversation this message belongs to.
</ResponseField>

<ResponseField name="session_id" type="string">
  The session ID echoed back from the request.
</ResponseField>

***

## Authenticated: Send a Message

**`POST /api/chat`**

Sends a message to an agent from a server-side or authenticated context. Requires a valid Bearer token. Use the same `session_id` across requests to maintain conversation context.

```bash theme={null}
curl -X POST https://app.botsmith.ai/api/chat \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Summarise our return policy.",
    "chatbot_id": "abc123",
    "session_id": "sess_dashboard_001"
  }'
```

**Request body:**

<ParamField body="message" type="string" required>
  The user's message text.
</ParamField>

<ParamField body="chatbot_id" type="string" required>
  The unique ID of the agent to send the message to.
</ParamField>

<ParamField body="session_id" type="string">
  A session identifier. Use a consistent value across messages to maintain conversation context.
</ParamField>

<ParamField body="user_name" type="string">
  Optional display name for the user.
</ParamField>

<ParamField body="user_email" type="string">
  Optional email address for the user.
</ParamField>

**Response (`200 OK`):**

```json theme={null}
{
  "message": "Our return policy allows customers to return any item within 30 days of purchase for a full refund.",
  "conversation_id": "conv_abc123",
  "session_id": "sess_dashboard_001"
}
```

***

## List Conversations

**`GET /api/chat/conversations/{chatbot_id}`**

Returns all conversations for the specified agent, sorted by most recently updated. Requires authentication.

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

**Path parameters:**

<ParamField path="chatbot_id" type="string" required>
  The unique ID of the agent whose conversations you want to list.
</ParamField>

**Response (`200 OK`):**

```json theme={null}
[
  {
    "id": "conv_abc123",
    "chatbot_id": "abc123",
    "session_id": "sess_xyz789",
    "user_name": "Jane Smith",
    "user_email": "jane@example.com",
    "status": "active",
    "rating": null,
    "message_count": 6,
    "messages_count": 6,
    "created_at": "2024-06-01T09:00:00Z",
    "updated_at": "2024-06-01T09:05:00Z"
  }
]
```

<ResponseField name="id" type="string">
  Unique identifier for the conversation.
</ResponseField>

<ResponseField name="session_id" type="string | null">
  The session ID associated with this conversation.
</ResponseField>

<ResponseField name="user_name" type="string | null">
  The name of the user who started the conversation, if provided.
</ResponseField>

<ResponseField name="user_email" type="string | null">
  The email of the user, if provided.
</ResponseField>

<ResponseField name="status" type="string">
  Conversation status: `"active"`, `"resolved"`, or `"escalated"`.
</ResponseField>

<ResponseField name="rating" type="integer | null">
  User-submitted satisfaction rating (1–5 stars), or `null` if not rated.
</ResponseField>

<ResponseField name="message_count" type="integer">
  Total number of messages (user + assistant combined) in the conversation.
</ResponseField>

***

## Get Messages in a Conversation

**`GET /api/chat/messages/{conversation_id}`**

Returns all messages in a conversation in chronological order. Requires authentication.

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

**Path parameters:**

<ParamField path="conversation_id" type="string" required>
  The unique ID of the conversation to fetch messages from.
</ParamField>

**Response (`200 OK`):**

```json theme={null}
[
  {
    "id": "msg_001",
    "role": "user",
    "content": "What are your business hours?",
    "timestamp": "2024-06-01T09:00:00Z"
  },
  {
    "id": "msg_002",
    "role": "assistant",
    "content": "We are open Monday through Friday, 9am to 6pm Eastern Time.",
    "timestamp": "2024-06-01T09:00:02Z"
  }
]
```

<ResponseField name="id" type="string">
  Unique identifier for the message.
</ResponseField>

<ResponseField name="role" type="string">
  Who sent the message: `"user"` or `"assistant"`.
</ResponseField>

<ResponseField name="content" type="string">
  The text content of the message.
</ResponseField>

<ResponseField name="timestamp" type="string">
  ISO 8601 timestamp of when the message was sent.
</ResponseField>