API Reference

Authentication

Include your API key in the Authorization header as a Bearer token:

curl -X POST https://api.getchattery.com/api/chat/bot_abc123 \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'

Note:API keys are available on Business and Enterprise plans. You can generate and manage keys from your dashboard under Settings → API Keys.

Chat API

POST/api/chat/{chatbotId}Send a message and receive a streamed response

Request body

{
  "message": "How do I reset my password?",
  "visitorId": "vis_abc123",
  "conversationId": "conv_xyz789",  // optional, omit to start new
  "language": "en"                  // optional, defaults to "en"
}

Response (SSE stream)

data: {"text": "You can reset your ", "conversationId": "conv_xyz789"}
data: {"text": "password by clicking ", "conversationId": "conv_xyz789"}
data: {"text": "the 'Forgot Password' link.", "conversationId": "conv_xyz789"}
data: [DONE]

Note: This is the main endpoint your widget uses. Each chunk contains a partial text response and the conversation ID for follow-up messages.

Chatbots API

GET/api/chatbotsList all your chatbots

POST/api/chatbotsCreate a new chatbot

Request body

{
  "name": "Support Bot",
  "website": "https://example.com"  // optional
}

PATCH/api/chatbots/{id}Update chatbot settings (name, personality, appearance, etc.)

DELETE/api/chatbots/{id}Permanently delete a chatbot and all associated data

Knowledge API

POST/api/knowledgeAdd a knowledge item (URL, Q&A pair, or text)

Request body

{
  "chatbotId": "bot_abc123",
  "type": "url",           // "url" | "qa" | "text" | "document"
  "source": "https://example.com/faq",
  "content": null           // required for "qa" and "text" types
}

POST/api/knowledge/uploadUpload a PDF, DOCX, TXT, or MD file (multipart/form-data)

POST/api/knowledge/scrapeTrigger scraping of a URL or sitemap

Conversations API

POST/api/conversations/{id}/replySend an admin reply to an escalated conversation

POST/api/conversations/{id}/tagsAdd or replace tags on a conversation

GET/api/conversations/{id}/export?format=csvExport a conversation as CSV or transcript

Webhooks

Configure webhook endpoints in your dashboard to receive real-time event notifications. All payloads are signed with HMAC-SHA256 for verification.

Available events

new_conversation — A visitor starts a new conversation
new_message — A new message is sent in a conversation
escalation — A conversation is escalated to a human
feedback_received — A visitor submits feedback (thumbs up/down)
admin_reply — An admin replies to a conversation

Example payload

{
  "event": "new_message",
  "timestamp": "2026-04-12T14:30:00Z",
  "data": {
    "conversationId": "conv_xyz789",
    "chatbotId": "bot_abc123",
    "message": "How do I cancel my plan?",
    "sender": "visitor",
    "visitorId": "vis_def456"
  }
}

Signature verification

Each webhook request includes an X-Chattery-Signature header. Verify it by computing an HMAC-SHA256 of the raw request body using your webhook secret:

const crypto = require("crypto");

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Rate Limits

Rate limits are enforced per-IP or per-user depending on the endpoint. When a limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header.

Endpoint	Limit	Window	Scope
Chat	10 requests	1 minute	Per IP
Knowledge scrape	10 requests	5 minutes	Per user
File upload	5 requests	5 minutes	Per user