BotSmith Chat API: Send Messages and Get Transcripts

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.

curl https://app.botsmith.ai/api/public/chatbot/CHATBOT_ID

Path parameters:

string

required

The unique ID of the agent.

Response (200 OK):

{
  "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
}

string

The agent’s unique identifier.

string

The agent’s display name.

string

The first message shown to users when the chat widget opens.

string

Primary hex color for the widget UI.

Where the widget appears on the page: "bottom-right", "bottom-left", "top-right", or "top-left".

boolean

Whether the widget shows a lead capture form before the first message.

string | null

Custom branding text shown at the bottom of the widget (available on paid plans), or null to show the default branding.

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.

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

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:

string

required

The unique ID of the agent to chat with.

Request body:

string

required

The user’s message text.

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.

string

Optional display name for the user. Stored against the conversation for reference.

string

Optional email address for the user. Stored against the conversation for reference.

Response (200 OK):

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

string

The agent’s reply to the user’s message.

string

The unique ID of the conversation this message belongs to.

string

The session ID echoed back from the request.

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.

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:

string

required

The user’s message text.

string

required

The unique ID of the agent to send the message to.

string

A session identifier. Use a consistent value across messages to maintain conversation context.

string

Optional display name for the user.

string

Optional email address for the user.

Response (200 OK):

{
  "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.

curl -H "Authorization: Bearer TOKEN" \
  https://app.botsmith.ai/api/chat/conversations/CHATBOT_ID

Path parameters:

string

required

The unique ID of the agent whose conversations you want to list.

Response (200 OK):

[
  {
    "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"
  }
]

string

Unique identifier for the conversation.

string | null

The session ID associated with this conversation.

string | null

The name of the user who started the conversation, if provided.

string | null

The email of the user, if provided.

string

Conversation status: "active", "resolved", or "escalated".

integer | null

User-submitted satisfaction rating (1–5 stars), or null if not rated.

integer

Total number of messages (user + assistant combined) in the conversation.

Get Messages in a Conversation

GET /api/chat/messages/{conversation_id} Returns all messages in a conversation in chronological order. Requires authentication.

curl -H "Authorization: Bearer TOKEN" \
  https://app.botsmith.ai/api/chat/messages/CONVERSATION_ID

Path parameters:

string

required

The unique ID of the conversation to fetch messages from.

Response (200 OK):

[
  {
    "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"
  }
]

string

Unique identifier for the message.

string

Who sent the message: "user" or "assistant".

string

The text content of the message.

string

ISO 8601 timestamp of when the message was sent.

Overview

Endpoints

BotSmith Chat API: Send Messages and Get Transcripts

Public: Get Agent Info

Public: Send a Message

Authenticated: Send a Message

List Conversations

Get Messages in a Conversation

​Public: Get Agent Info

​Public: Send a Message

​Authenticated: Send a Message

​List Conversations

​Get Messages in a Conversation

Public: Get Agent Info

Public: Send a Message

Authenticated: Send a Message

List Conversations

Get Messages in a Conversation