BotPlot API Documentation

The BotPlot API lets you programmatically send chat messages, manage conversations, and access knowledge sources. Use it to build custom integrations with your existing tools.

Authentication

All API requests require an API key. You can find your project API key in the dashboard settings. Pass it as a header:

curl https://botplot.app/api/v1/conversations \
  -H "Authorization: Bearer YOUR_API_KEY"

You can also use the x-api-key header. The Chat API uses x-api-key for widget compatibility.

Chat API

Send a message and receive a streamed AI response. This is the same endpoint the widget uses.

Auth: x-api-key header

Response: Server-Sent Events (SSE) stream. Each token is sent as data: {"token":"..."}. The final event includes conversationId, sources, and confidence.

curl -X POST https://botplot.app/api/chat \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "message": "What are your shipping options?",
    "visitorId": "visitor-123"
  }'

Widget Embed

Add the BotPlot chat widget to any website with a single script tag. The widget is under 15KB gzipped and loads asynchronously.

<!-- Add before </body> -->
<script
  src="https://botplot.app/widget/w.js"
  data-key="YOUR_API_KEY"
  async
></script>

The widget automatically inherits your project's customization (colors, logo, position, welcome message, starter questions).

Conversations API

Business plan only

List conversations

curl https://botplot.app/api/v1/conversations?limit=10 \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "conversations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "visitor_id": "visitor-123",
      "visitor_info": { "name": "John", "email": "john@example.com" },
      "status": "active",
      "handoff_requested": false,
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

Messages API

Business plan only

List messages in a conversation

curl https://botplot.app/api/v1/conversations/CONV_ID/messages \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "messages": [
    {
      "id": "msg-uuid",
      "role": "user",
      "content": "What are your business hours?",
      "sources": [],
      "created_at": "2025-01-15T10:30:05Z"
    },
    {
      "id": "msg-uuid-2",
      "role": "assistant",
      "content": "Our business hours are Monday to Friday, 9am to 5pm EST.",
      "sources": [{ "content": "Hours: Mon-Fri 9-5...", "similarity": 0.89 }],
      "created_at": "2025-01-15T10:30:07Z"
    }
  ]
}

Knowledge Sources API

Business plan only

List knowledge sources

curl https://botplot.app/api/v1/sources \
  -H "Authorization: Bearer YOUR_API_KEY"

Get source details

Delete a source

curl -X DELETE https://botplot.app/api/v1/sources/SOURCE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Webhook Events

BotPlot sends HTTP POST requests to your registered webhook endpoints when events occur. Configure webhooks in your project's dashboard.

Available events

Payload format

{
  "event": "message.received",
  "data": {
    "conversation_id": "uuid",
    "content": "What are your prices?",
    "role": "user"
  },
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Verifying signatures

Each webhook delivery includes an X-BotPlot-Signature header with an HMAC-SHA256 signature. Verify it using your endpoint's secret:

# The signature header looks like:
# X-BotPlot-Signature: sha256=abc123...
# Verify using your webhook secret