API Documentation
Use the SiteBotGPT API to send messages to your chatbot from your app, backend, or scripts. API access is available on Scale and Enterprise plans.
Authentication
For programmatic access, create an API key in Dashboard → API. Send it in one of these ways:
Authorization: Bearer YOUR_API_KEYx-api-key: YOUR_API_KEY
For the embed widget, use the bot's public key (x-bot-key or x-atlas-key) from your embed code. No API key required for widget usage.
Chat API
Send a user message and receive the bot's reply. Conversations are tracked by chatId.
Endpoint
POST https://www.sitebotgpt.com/api/chat
Headers
| Header | Required | Description |
|---|---|---|
| Content-Type | Yes | application/json |
| Authorization / x-api-key | For API access | API key (Scale/Enterprise) |
| x-bot-key / x-atlas-key | Widget | Bot public key (atlas_...) |
| x-visitor-id | No | Anonymous visitor ID for session |
Request body
| Field | Type | Description |
|---|---|---|
| message | string | Required. User message (max 4000 chars). |
| botId | string | Required when using API key. Bot ID or public key (atlas_...). |
| chatId | string | Optional. Continue an existing conversation. |
| history | array | Optional. Previous messages { role, content } for context. |
Response (200)
{
"response": "The bot's reply text",
"sources": ["url1", "url2"],
"chatId": "clx...",
"confidence": 0.92,
"shouldCaptureLead": false
}Example: cURL (API key)
curl -X POST https://www.sitebotgpt.com/api/chat \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"botId": "YOUR_BOT_ID", "message": "What are your opening hours?"}'Example: JavaScript (fetch)
const res = await fetch("https://www.sitebotgpt.com/api/chat", {
method: "POST",
headers: {
"Authorization": "Bearer sk_live_YOUR_API_KEY",
"Content-Type": "application/json"},
body: JSON.stringify({
botId: "YOUR_BOT_ID",
message: "What are your opening hours?",
chatId: "optional-existing-chat-id"})});
const data = await res.json();
console.log(data.response);Embed info (widget)
Fetch greeting and quick prompts for a bot. Used by the chat widget; no API key required.
GET https://www.sitebotgpt.com/api/embed/info?botId=atlas_xxxx
Response: { greeting, quickPrompts }
Webhooks
Receive HTTP POST requests at your endpoint when events occur. Available on Scale and Enterprise plans. Create webhooks in Dashboard → Webhooks.
Events
| Event | When |
|---|---|
| lead.captured | A visitor submits their contact (name, email, etc.) via the chat widget. |
| chat.message | A chat turn completes (user message + assistant reply). |
Request
We send a POST to your URL with:
Content-Type: application/jsonX-Webhook-Signature: sha256=<hex>— HMAC-SHA256 of the raw body using your signing secretX-Webhook-Event: <event>— e.g. lead.captured, chat.message
Payload: lead.captured
{
"event": "lead.captured",
"botId": "clx...",
"lead": {
"id": "clx...",
"name": "Jane",
"email": "jane@example.com",
"phone": "+1...",
"message": "I need help with...",
"pageUrl": "https://...",
"status": "new",
"createdAt": "2025-01-01T12:00:00.000Z"
}
}Payload: chat.message
{
"event": "chat.message",
"botId": "clx...",
"chatId": "clx...",
"userMessage": "What are your hours?",
"assistantResponse": "We're open 9am–5pm...",
"sources": ["https://..."],
"confidence": 0.92
}Verifying the signature
Compute HMAC-SHA256(secret, rawRequestBody) and compare with the X-Webhook-Signature value (after sha256=). Return 200 quickly to acknowledge receipt; process asynchronously if needed.
// Node.js example
const crypto = require("crypto");
const signature = req.headers["x-webhook-signature"]; // "sha256=abc123..."
const expected = "sha256=" + crypto.createHmac("sha256", process.env.WEBHOOK_SECRET).update(rawBody).digest("hex");
if (signature !== expected) return res.status(401).send("Invalid signature");Errors
| Status | Meaning |
|---|---|
| 400 | Bad request (e.g. missing message, bot not found) |
| 401 | Invalid API key or plan does not include API access |
| 402 | Daily message limit reached (upgrade plan) |
| 429 | Rate limit exceeded (30 req/min per bot/visitor) |
| 500 | Server error |
Rate limits
Chat API: 30 requests per minute per bot/visitor (or per API key + visitor). Message limits per day depend on your plan (see Pricing).