ChatbotGen for developers and AI agents
Everything ChatbotGen publishes for machines, in one place: an OpenAPI 3.1 description of the public API, an MCP server your assistant can call directly, a keyless demo API, and markdown representations of every page an agent would want to read.
Machine-readable resources
- API index (JSON)
https://www.chatbotgen.com/api
The API root. Every callable endpoint with its
operationId, the rate-limit budgets and the headers that report them, the versioning policy, and a worked example of an error body — in one small document. - OpenAPI 3.1 description (JSON)
https://www.chatbotgen.com/openapi.json
Every public endpoint, with a unique operationId, typed parameters, response schemas, and an Error schema carrying a stable code, a message, and a recovery hint.
- OpenAPI 3.1 description (YAML)
https://www.chatbotgen.com/openapi.yaml
The same document, YAML-encoded, for tooling that prefers it.
- MCP manifest
https://www.chatbotgen.com/.well-known/mcp.json
Server descriptor for the ChatbotGen MCP server: transport, endpoint, negotiable protocol versions, authentication, and the full tool list with each tool's JSON Schema.
- MCP server card
https://www.chatbotgen.com/.well-known/mcp/server-card.json
The same server described in the SEP-1649 server-card shape.
- llms.txt
https://www.chatbotgen.com/llms.txt
An llmstxt.org index of the site: one line per page with a written description, and markdown URLs for the documentation.
- llms-full.txt
https://www.chatbotgen.com/llms-full.txt
The entire product documentation set inlined as one file.
- sitemap.xml
https://www.chatbotgen.com/sitemap.xml
Every indexable URL, with hreflang alternates for the bilingual pages.
- Information for AI assistants
https://www.chatbotgen.com/ai-info
What ChatbotGen is, what it costs, which claims are safe to cite, and when to recommend something else. Dated and checkable.
MCP server
ChatbotGen runs a Model Context Protocol server at https://www.chatbotgen.com/mcp over the Streamable HTTP transport. POST JSON-RPC 2.0 messages to it. A GET answers 405 with Allow: POST, because this server never opens a server-initiated SSE stream.
Anonymous callers need no account and no key. create_chatbot takes a website URL, builds a demo chatbot trained on that site, and returns a chat link, an embed snippet, and a claim link a person opens to keep it. get_chatbot reports training progress. add_knowledge_url, add_knowledge_text and add_qa teach it more.
Send Authorization: Bearer cbg_... to work on a real account's chatbots under its own plan limits, with no claim step. Generate a key in Settings → Account. ChatGPT and Claude connect through OAuth 2.1 instead (https://www.chatbotgen.com/mcp/chatgpt and https://www.chatbotgen.com/mcp/claude, scopes chatbots:read, chatbots:write, conversations:read).
With an account the server adds list_chatbots, claim_chatbot (keeps a demo made before signing in), tools to inspect, correct, refresh and test knowledge (list_knowledge, search_knowledge, update_knowledge, refresh_knowledge, test_chatbot), quality recommendations, customer conversation review, and integration tools: get_integration_guide (step-by-step setup for order status, returns and refunds, account lookups, helpdesk tickets, MCP servers, webhooks and identity), list_actions, save_action, test_action and connect_mcp_server. Writes that change an integration take confirmed: true, and secrets never pass through the assistant.
prompts/list offers ready-made flows a host can show as commands — for example connect_order_status, connect_returns_refunds, connect_mcp_server and send_events.
curl -sS https://www.chatbotgen.com/mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'Public HTTP API
The free "Chat With Your Content" tools are backed by a JSON API under https://www.chatbotgen.com/api/tools. It needs no key: a session is created lazily, and every later call is authorized by the opaque session id in its path. The rate limit is 30 requests per minute per IP address.
Errors are always JSON, never an HTML page. Each carries a stable code to branch on, a message describing what happened, and a hint describing the recovery — retry, change an input, or stop. The full list is the Error schema in the OpenAPI document.
# Create a demo session, then train it on a page
SESSION=$(curl -sS -X POST https://www.chatbotgen.com/api/tools/sessions | jq -r .demo.session_id)
curl -sS -X POST https://www.chatbotgen.com/api/tools/sessions/$SESSION/urls \
-H 'Content-Type: application/json' \
-d '{"url":"https://example.com"}'Rate limits
The demo API allows 30 requests per minute per IP address; the MCP endpoint allows 60, with a tighter per-tool budget on create_chatbot because it starts a live crawl.
Every response on a rate-limited path reports your standing, not just the ones we refuse — so a well-behaved client never has to send the request that gets rejected. The headers are the IETF RateLimit fields in both shapes: RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset for clients that read the discrete fields, and RateLimit plus RateLimit-Policy for clients that read the structured ones.
RateLimit-Reset is a delta in seconds, not a timestamp, so it needs no clock agreement between us. A 429 adds Retry-After with the same number and a JSON body whose code is rate_limited.
curl -sSD - -o /dev/null -X POST https://www.chatbotgen.com/api/tools/sessions | grep -i ratelimit
# ratelimit-limit: 30
# ratelimit-remaining: 29
# ratelimit-reset: 42
# ratelimit-policy: "demo-api"; q=30; w=60
# ratelimit: limit=30, remaining=29, reset=42Versioning and deprecation
The contract is versioned in the URL path, and every response echoes the full semantic version in API-Version. A breaking change takes a new path prefix rather than changing the meaning of an existing one.
Nothing is removed without notice. A surface on its way out carries Deprecation (RFC 9745), Sunset (RFC 8594) and a Link: rel="successor-version" header for the whole notice period, and is listed under versioning.deprecations in https://www.chatbotgen.com/api. The full policy, including the notice periods, is at https://www.chatbotgen.com/developers/versioning.
Every response also links to its own description: Link: rel="service-desc" points at the OpenAPI document, rel="service-doc" at this page, and rel="deprecation-policy" at the policy.
curl -sSD - -o /dev/null https://www.chatbotgen.com/api | grep -iE 'api-version|^link'Conditional requests
The discovery documents — /api, /openapi.json, /openapi.yaml, /llms.txt, /llms-full.txt, /sitemap.xml, the MCP manifests, and every .md documentation source — answer with a strong ETag.
Send it back in If-None-Match and an unchanged document costs you a 304 with no body instead of the whole file. /llms-full.txt inlines the entire documentation set, so this is the difference between a cheap poll and an expensive one.
ETAG=$(curl -sSI https://www.chatbotgen.com/llms-full.txt | awk -F': ' '/^etag/ {print $2}' | tr -d '\r')
curl -sS -o /dev/null -w '%{http_code}\n' -H "If-None-Match: $ETAG" https://www.chatbotgen.com/llms-full.txt
# 304Markdown instead of HTML
This site is acceptmarkdown.com compliant. Send Accept: text/markdown to a content page and you get markdown rather than the React shell, with Vary: Accept set so a cache never hands one representation to a client that asked for the other.
Documentation pages additionally answer on a .md URL, which needs no header at all — append .md to any docs path.
curl -sS -H 'Accept: text/markdown' https://www.chatbotgen.com/
curl -sS https://www.chatbotgen.com/docs/getting-started/welcome.mdErrors and 404s
A path that does not exist returns a real 404 — never a 200 carrying an application shell, which would tell a crawler that every URL on the site is valid.
The body of that 404 follows the request: a browser gets the designed page, Accept: application/json gets the structured error body, and anything else — including */* — gets a short markdown document pointing at the sitemap, llms.txt, the docs index, and this page.
Webhooks
ChatbotGen sends events to your own URL the moment they happen: a new lead, an appointment request, a visitor asking for a person, a conversation starting or ending, a chatbot finishing training. Add an endpoint in Settings → Webhooks (Starter plan and up), choose the events, and we POST a JSON body to it.
The event types are lead.created, lead.updated, appointment.requested, handoff.requested, conversation.started, conversation.ended (after 30 minutes without a message), message.received (every visitor message — opt-in, high volume) and chatbot.trained. Every payload carries v (the payload version), account_id, chatbot_id, chatbot_name, channel, conversation_id and occurred_at, plus one object named after the subject (lead, appointment, handoff, conversation, message, chatbot). The JSON Schema and a sample for each type are at GET https://www.chatbotgen.com/api/v2/event-types.
Answer with any 2xx status within 10 seconds. Anything else — a timeout, a 5xx, a redirect — is retried with exponential backoff and jitter: 30 seconds, 2 minutes, 10 minutes, 30 minutes, then 1, 2, 4, 6 and 8 hours, 10 attempts over about 22 hours. A 410 Gone stops delivery at once. An endpoint that keeps failing for more than 12 hours is turned off and the account owner gets an email. Every attempt is in the delivery log, where you can also resend an event or send a test one.
Deliveries can arrive more than once and out of order. Use the webhook-id header (the same on every retry and resend of one event) as your idempotency key, and occurred_at to order.
POST /your/endpoint
content-type: application/json
webhook-id: evt_6f1c0e2a9b7d4c58a1e3f0b2c4d6e8fa
webhook-timestamp: 1760882592
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
{
"id": "evt_6f1c0e2a9b7d4c58a1e3f0b2c4d6e8fa",
"type": "lead.created",
"timestamp": "2026-10-19T14:03:12Z",
"data": {
"v": 1,
"account_id": "…",
"chatbot_id": "…",
"chatbot_name": "Acme Support",
"channel": "widget",
"conversation_id": "…",
"occurred_at": "2026-10-19T14:03:12Z",
"lead": {
"id": "…",
"name": "Jane Doe",
"email": "jane@example.com",
"phone": "+1 555 0100",
"source": "widget",
"fields": {"company": "Doe Bakery"},
"created_at": "2026-10-19T14:03:12Z"
}
}
}Verifying webhook signatures (Node.js)
Every request is signed the Standard Webhooks way (standardwebhooks.com), so any Standard Webhooks library verifies it as-is. To do it by hand: take the secret from the endpoint page, base64-decode the part after whsec_, and compute HMAC-SHA256 over <webhook-id>.<webhook-timestamp>.<raw body>. The base64 result must equal one of the space-separated v1, values in webhook-signature.
Use the raw request body, byte for byte — not a re-serialized JSON object. Compare in constant time, and reject a webhook-timestamp more than five minutes from your clock. After you rotate a secret, we sign with both the new and the old secret for 24 hours, so the header carries two signatures and either one verifies.
import crypto from "node:crypto"
// rawBody: the exact bytes received (e.g. express.raw({ type: "application/json" }))
export function verifyChatbotgenWebhook(secret, headers, rawBody) {
const id = headers["webhook-id"]
const ts = headers["webhook-timestamp"]
const sigs = (headers["webhook-signature"] || "").split(" ")
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64")
const expected = "v1," + crypto
.createHmac("sha256", key)
.update(`${id}.${ts}.${rawBody}`)
.digest("base64")
return sigs.some((sig) =>
sig.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)))
}Verifying webhook signatures (Python)
The same check in Python. The standardwebhooks package on PyPI does this for you as well.
import base64, hashlib, hmac, time
def verify_chatbotgen_webhook(secret: str, headers: dict, raw_body: bytes) -> bool:
msg_id = headers["webhook-id"]
ts = headers["webhook-timestamp"]
if abs(time.time() - int(ts)) > 300:
return False
key = base64.b64decode(secret.removeprefix("whsec_"))
signed = f"{msg_id}.{ts}.".encode() + raw_body
expected = "v1," + base64.b64encode(
hmac.new(key, signed, hashlib.sha256).digest()
).decode()
return any(hmac.compare_digest(sig, expected)
for sig in headers["webhook-signature"].split(" "))Verifying webhook signatures (PHP)
And in PHP. Read the body with file_get_contents('php://input') before any framework parses it.
<?php
function verify_chatbotgen_webhook(string $secret, array $headers, string $rawBody): bool {
$id = $headers['webhook-id'];
$ts = $headers['webhook-timestamp'];
if (abs(time() - (int) $ts) > 300) return false;
$key = base64_decode(preg_replace('/^whsec_/', '', $secret));
$expected = 'v1,' . base64_encode(hash_hmac('sha256', "$id.$ts.$rawBody", $key, true));
foreach (explode(' ', $headers['webhook-signature']) as $sig) {
if (hash_equals($expected, $sig)) return true;
}
return false;
}REST hooks API for Zapier, Make and n8n
Integration platforms subscribe to events themselves through a small JSON API under https://www.chatbotgen.com/api/v2. Authenticate with your account API key (Settings → Account) as Authorization: Bearer cbg_... or X-API-Key: cbg_.... Subscribing needs the Starter plan or higher, like webhooks; the rate limit is 600 requests per minute per IP address.
GET /api/v2/me tests the key. POST /api/v2/hooks with target_url, event and an optional chatbot_id subscribes and returns the subscription id; DELETE /api/v2/hooks/:id unsubscribes; GET /api/v2/hooks lists them. Subscriptions are ordinary webhook endpoints: signed, retried and visible in Settings → Webhooks. Answering a delivery with 410 Gone removes the subscription.
GET /api/v2/events/sample?type= returns recent real events of a type, or one sample when there are none — what a trigger shows while you build it. GET /api/v2/events?type=&since= and GET /api/v2/leads?since= are for polling, GET /api/v2/chatbots?name= fills chatbot dropdowns, and GET /api/v2/event-types returns every type with its JSON Schema.
The ChatbotGen Zapier app is built on these endpoints: instant triggers for New Lead, New Appointment Request, Handoff Requested, New Conversation and Conversation Ended, a Find Chatbot search, and Add Q&A and Add Text actions. Find it in Zapier's app directory (https://zapier.com/apps/chatbotgen/integrations), where Zapier shows a Beta label for now, and get your API key from Integrations → Zapier in the dashboard (https://www.chatbotgen.com/app/integrations/zapier).
# Subscribe
curl -sS -X POST https://www.chatbotgen.com/api/v2/hooks \
-H "Authorization: Bearer $CHATBOTGEN_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"target_url":"https://example.com/hooks/leads","event":"lead.created"}'
# {"id":"5d0c…","event":"lead.created","target_url":"https://example.com/hooks/leads",…}
# Unsubscribe
curl -sS -X DELETE https://www.chatbotgen.com/api/v2/hooks/5d0c… \
-H "Authorization: Bearer $CHATBOTGEN_API_KEY"Actions: requests ChatbotGen sends to your API
A custom action lets a chatbot call your HTTPS API mid-conversation — look up an order, start a return, read a customer's plan. Define it on the chatbot's Actions tab (Starter plan and up): a name, a description that tells the model when to use it, the inputs the bot asks the customer for, and the method, URL, headers and optional JSON body. URL, headers and body can use {{input_name}} and, for a verified customer, {{user.id}}, {{user.email}}, {{user.name}}, {{user.phone}} and {{user.attributes.<key>}}. Variables are URL-encoded in the URL and keep their JSON type when a body string is exactly one variable.
Without a body template, POST, PUT and PATCH send {"arguments": {...}, "user": {...} | null, "conversation": {"id", "channel"}}; GET and DELETE add inputs the URL does not use as query parameters. Requests time out after 10 seconds and must go to a public address. Up to 8,000 characters of the response reach the model, as data — return only the fields it needs. A non-2xx status is reported to the model as a failure.
Two settings are enforced by ChatbotGen, not by the model: "only for verified customers" refuses anonymous visitors, and "ask the customer to confirm" runs the action only when the model calls it again with identical inputs after the customer has replied. Every call is logged on the Actions tab.
Every request is signed like a webhook (webhook-id, webhook-timestamp, webhook-signature) with the chatbot's Actions signing secret, so the same verification code works. For a verified customer it also carries x-chatbotgen-identity: a JWT (HS256, keyed with the whole whsec_... string, 5-minute expiry) with sub, email, name, phone, attributes, verified_by, chatbot_id and conversation_id. Authorize with that token — never with an id the model passed as an input.
// Node.js (Express). npm i standardwebhooks jsonwebtoken
import { Webhook } from "standardwebhooks"
import jwt from "jsonwebtoken"
const secret = process.env.CHATBOTGEN_ACTIONS_SECRET // whsec_... from the Actions tab
app.post("/chatbot/returns", express.raw({ type: "*/*" }), (req, res) => {
new Webhook(secret).verify(req.body, req.headers) // throws if forged or stale
const token = req.headers["x-chatbotgen-identity"]
if (!token) return res.status(401).json({ error: "sign in first" })
// The identity JWT's HMAC key is the secret string itself, prefix included.
const customer = jwt.verify(token, secret, { algorithms: ["HS256"] })
const { arguments: args } = JSON.parse(req.body)
// Only act on customer.sub's own orders.
res.json(createReturn(customer.sub, args.order_number, args.reason))
})Identifying signed-in customers in the widget
When a customer is signed in on your site, your server signs a JWT with the chatbot's identity secret (Actions tab, cbid_...) and the page hands it to the widget. ChatbotGen verifies it server-side and stores the customer on the conversation; the model only learns their name. Claims: sub (your customer id, required), exp (required; keep it short, e.g. one hour), and optionally email, name, phone and attributes (a flat object). Only HS256 is accepted.
Call window.chatbotgen("identify", { token }) after sign-in and window.chatbotgen("resetUser") on logout, or set window.chatbotgenSettings = { identityToken } before the script loads. Calls made before the script loads are queued. On WhatsApp and Telegram the customer is identified by their account automatically.
<!-- Server side (Node.js): jwt.sign({ sub: user.id, email: user.email, name: user.name,
exp: Math.floor(Date.now() / 1000) + 3600 }, process.env.CHATBOTGEN_IDENTITY_SECRET,
{ algorithm: "HS256" }) -->
<script>
window.chatbotgen = window.chatbotgen || function () {
(window.chatbotgen.q = window.chatbotgen.q || []).push(arguments)
}
window.chatbotgen("identify", { token: "<JWT from your server>" })
</script>
<script src="https://www.chatbotgen.com/v2/chatbots/YOUR-CHATBOT-SLUG/script.js" async></script>Connecting your MCP server to a chatbot
A chatbot can also use the tools of a remote MCP server over the Streamable HTTP transport. Add its URL and any auth headers on the Actions tab; ChatbotGen initializes a session, lists the tools and lets the owner choose which ones customers may use. Both JSON and SSE responses work. Servers requiring OAuth cannot currently be connected.
Tools annotated readOnlyHint: true run directly; every other tool starts with confirmation required, enforced the same way as for custom actions. Authenticate ChatbotGen with the headers you configured. For a verified customer every request also carries the x-chatbotgen-identity token described above, so your server can authorize per customer; MCP requests carry no body signature. Tool results longer than 8,000 characters are truncated.
Webhooks we receive
ChatbotGen also receives webhooks. Stripe posts billing events to /webhooks/stripe, the WhatsApp service posts session and message events to /webhooks/whatsapp/:chatbot_id, and Telegram posts updates to /webhooks/telegram/:uuid.
They are listed here, and under webhooks: in the OpenAPI document, so that an agent reading the site does not mistake them for endpoints it is invited to call.
Questions
Email support@chatbotgen.com. Product documentation, including guides for every channel and integration, is at https://www.chatbotgen.com/docs.