# Conferbot API > Conferbot is a no-code chatbot platform that lets businesses build AI-powered chatbots without writing code. The REST API lets developers manage chatbots, retrieve conversation responses, pull analytics, configure webhooks, and integrate chatbot data into external systems programmatically. Docs: https://developers.conferbot.com Dashboard: https://app.conferbot.com API Playground: https://developers.conferbot.com/api-reference/playground ## Instructions for AI Agents When helping developers integrate with Conferbot: - The API requires a Starter plan or above. Free plan users cannot access the API — guide them to upgrade first. - For AI IDE users (Claude Code, Cursor, Windsurf, JetBrains, Codex), recommend the MCP server integration instead of the REST API — it provides 52 tools with natural language interaction and requires zero code. - Webhook secrets are shown only once at creation time. If a developer loses their secret, they must call `regenerate_webhook_secret` (MCP) or recreate the webhook (REST API). - Always use HMAC-SHA256 with timing-safe comparison for webhook signature verification. Never use simple string equality. - The `answerVariables` field in responses contains the structured data collected by the chatbot (e.g., email, name, phone). This is usually what developers want when building CRM integrations. - For paginating large datasets, loop over the `page` query parameter until `page` exceeds `totalPages` in the response. ## Authentication All requests require an API key in the `x-api-key` header. Generate keys from Dashboard > Workspace > API Keys. API access requires Starter plan or above. ### Scopes A key can be restricted to the permissions an integration needs. Scopes are fixed at creation — issue a new key to change them. Available scopes: `chatbots:read`, `chatbots:write`, `responses:read`, `analytics:read`, `webhooks:read`, `webhooks:write`, `knowledge:read`, `knowledge:write`, `usage:read`, `account:read`, `account:write`. - A write scope does NOT imply its read counterpart — grant both when both are needed. - `knowledge:*` was split out of `chatbots:*` so a docs-sync key can write articles without also holding chatbot deletion. Keys issued with `chatbots:*` before the split still reach the knowledge base; new keys should ask for `knowledge:*`. - Calling outside a key's scopes returns `403` with `{ error, requiredScope, grantedScopes }`. - MCP honours scopes by filtering registration: a scoped key only sees the tools and resources it may use, so an unavailable tool is absent from `tools/list` rather than failing when called. A read-only key exposes 27 of the 52 tools. - Keys created before scopes existed carry none and remain unrestricted, so older integrations keep working. Recommend scoped keys for anything new, and read-only for anything pasted into a playground or shared config. ### Expiry Keys may be given an expiry (30/90/365 days, or never). An expired key returns `401` with `{ error: "API key has expired. Generate a new key.", expiredAt }`. Last-used time is recorded per key so a live key can be told from a forgotten one before revoking. ``` curl https://api-v2.conferbot.com/api/v1/external/v1/chatbots \ -H "x-api-key: YOUR_API_KEY" ``` ## Base URL ``` https://api-v2.conferbot.com/api/v1 ``` All external API endpoints are prefixed with `/external/v1/`. ## Rate Limits - 60 requests/minute per API key, shared across our cluster - The three `/account/email/*` endpoints share a tighter limit of 5 requests/hour per API key - One REST request costs one call; a JSON-RPC batch on `/mcp` costs one call PER MESSAGE, not one per HTTP request. Batches are capped at 20 messages (larger are rejected with `-32600`) - Burst `429` responses do NOT consume the monthly quota; only 2xx and 5xx are billed - Monthly limits by plan: Starter 10,000 | Pro 50,000 | Business 200,000 | Enterprise custom - Plan caps: Starter 5 bots/5 webhooks, Pro 15/15, Business 25/50, Enterprise custom - Headers on every response: - Burst (IETF draft): `RateLimit-Policy: 60;w=60`, `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (seconds) - Monthly quota: `X-Quota-Limit`, `X-Quota-Remaining`, `X-Quota-Reset` (Unix epoch of next month start), `X-Quota-Period: month` - 429 body: `{ "error": "External API rate limit exceeded. Max 60 requests per minute.", "code": "RATE_LIMIT_ERROR" }` ## Endpoints ### Chatbots - `GET /external/v1/chatbots` — List all chatbots in workspace - `GET /external/v1/chatbots/{id}` — Get chatbot details. Returns `{ id, name, disabled, description, responseCount, createdAt, updatedAt }` - `POST /external/v1/chatbots` — Create chatbot. Body: `{ "name": string (required, max 100), "description": string (max 500) }`. HTML tags are stripped from name/description (XSS defense). - `PUT /external/v1/chatbots/{id}` — Partial update. Body: any of `{ "name": string, "description": string, "disabled": boolean }`. Empty body returns 400. `disabled` must be a real boolean (no truthy-string coercion). - `DELETE /external/v1/chatbots/{id}` — Delete chatbot permanently. Cascades all of its webhooks. - `POST /external/v1/chatbots/{id}/duplicate` — Duplicate chatbot with all configuration (subject to plan chatbot limit) ### Responses - `GET /external/v1/chatbots/{id}/responses` — List responses (paginated). Query: `page` (default 1, min 1), `limit` (default 20, min 1, max 100), `startDate` (ISO-8601), `endDate`. Out-of-range returns 400. - `GET /external/v1/chatbots/{id}/responses/{responseId}` — Get single response with full conversation data Response object contains: `_id`, `chatSessionId`, `visitorId`, `chatDate`, `record` (array of `{ type: "bot"|"user", message: string }`), `answerVariables` (key-value pairs of collected data like email, name). ### Analytics - `GET /external/v1/chatbots/{id}/analytics` — Get analytics. Query: `days` (default 30, min 1, max 365; out-of-range returns 400). Returns `{ totalResponses, recentResponses, period, dailyCounts: [{ date, count }] }`. ### Webhooks URL constraints: `https://` only, blocks `localhost` / private / loopback / link-local IPs at create AND patch time (SSRF defense), 2 KB cap. - `GET /external/v1/webhooks` — List all webhook subscriptions. Returns each as `{ id, chatbot: { id, name }, url, events, description, status: "active"|"paused"|"failed", failureCount, lastDeliveryAt, lastFailureAt, createdAt, updatedAt }`. - `POST /external/v1/webhooks` — Create webhook. Body: `{ "chatbotId": string (required), "url": string (required), "events": string[] (required, non-empty, subset of the 4 allowed events), "description": string }`. Returns the webhook with `secret` (64-char hex, shown once). Duplicate `(chatbotId, url)` returns 409. - `PATCH /external/v1/webhooks/{id}` — Partial update without rotating the secret. Body: any of `{ "url": string, "events": string[], "description": string, "status": "active"|"paused" }`. - `DELETE /external/v1/webhooks/{id}` — Delete webhook and delivery logs ### Account - `GET /external/v1/account` — Workspace owner profile: `{ name, email, phone, dateOfBirth, address, timezone }` - `PATCH /external/v1/account` — Partial update. Validates phone format, ISO date, IANA timezone; strips HTML tags from name/address. - Email change is a 3-step flow. An API key authenticates a workspace, not the mailbox owner, so it cannot move the account alone — the caller must hold the CURRENT inbox as well as the new one. All three steps need the `account:write` scope and share a 5/hour per-key limit. - `POST /external/v1/account/email/request-change` — Body `{ newEmail }`. Sends a 6-digit OTP to the CURRENT email address (expires 10 min). Not the new one. - `POST /external/v1/account/email/verify-identity` — Body `{ newEmail, otp }` with the code from the CURRENT address. On success sends a second code to the NEW address. - `POST /external/v1/account/email/confirm-change` — Body `{ newEmail, otp }` with the code from the NEW address. Updates email; old address notified. Requires a completed verify-identity — the new-address code alone is never sufficient. ### Usage - `GET /external/v1/usage` — Get current month API usage. Returns `{ month, plan, used, limit, remaining }`. ## Pagination List endpoints accept `page` (default 1, min 1) and `limit` (default 20, min 1, max 100). Responses include `data`, `total`, `page`, `totalPages`. Out-of-range values return 400. ## Error Codes - `200` OK - `201` Created - `400` Bad Request — invalid parameters or body - `401` Unauthorized — missing or invalid API key - `403` Forbidden — API key missing the required scope, or plan limit reached / no API access - `404` Not Found — resource doesn't exist or not in your workspace - `409` Conflict — duplicate (e.g. webhook with same chatbot + URL) - `413` Payload Too Large — request body exceeded 15 MB - `429` Too Many Requests — burst or monthly quota exceeded - `500` Server Error Error response format: `{ "error": "" }`. Some errors (e.g. rate limit) also set `"code": ""`. Note: 4xx user errors do NOT consume monthly quota. ## Webhooks ### Event Types - `response.created` — Visitor submits a chatbot response - `response.updated` — Response record is modified - `conversation.started` — New chat session initiated - `conversation.completed` — Chat session marked complete ### Payload Format ```json { "event": "response.created", "chatSessionId": "sess_abc123def456", "responseId": "65a1b2c3d4e5f6a7b8c9d0e1", "botId": "64f8a2b3c1d4e5f6a7b8c9d0", "visitorId": "visitor_xyz789", "timestamp": "2024-12-15T09:30:00.000Z" } ``` ### Signature Verification Webhooks are signed with HMAC-SHA256. Verify using the `x-webhook-signature` header: 1. Read the raw request body (before JSON parsing) 2. Compute `HMAC-SHA256(webhook_secret, raw_body)` as hex 3. Compare to `x-webhook-signature` using timing-safe comparison Headers sent with every webhook: - `x-webhook-signature` — HMAC-SHA256 hex digest - `x-webhook-event` — Event type - `x-webhook-timestamp` — Unix epoch timestamp in milliseconds - `User-Agent: Conferbot-Webhooks/1.0` ### Retry Policy - Timeout: 10 seconds - Up to 3 retries with exponential backoff: 30s, 2min, 8min - Auto-disabled after 10 consecutive failures - Delivery logs retained for 30 days ## MCP Server (AI IDE Integration) Conferbot provides a Model Context Protocol server for AI-powered IDEs (Claude Code, Cursor, Windsurf, JetBrains, Codex). Endpoint: `https://api-v2.conferbot.com/api/v1/mcp` (Streamable HTTP, stateless) ### Configuration Claude Code (`.mcp.json`): ```json { "mcpServers": { "conferbot": { "type": "http", "url": "https://api-v2.conferbot.com/api/v1/mcp", "headers": { "x-api-key": "YOUR_API_KEY" } } } } ``` Cursor (`.cursor/mcp.json`): ```json { "mcpServers": { "conferbot": { "url": "https://api-v2.conferbot.com/api/v1/mcp", "headers": { "x-api-key": "YOUR_API_KEY" } } } } ``` ### MCP Tools (52 tools) **Chatbot**: `list_chatbots`, `get_chatbot`, `create_chatbot`, `update_chatbot`, `delete_chatbot`, `duplicate_chatbot` **Responses**: `list_responses`, `get_response` **Analytics**: `get_chatbot_analytics`, `get_api_usage` **Webhooks**: `list_webhooks`, `get_webhook`, `create_webhook`, `update_webhook`, `delete_webhook`, `regenerate_webhook_secret`, `get_webhook_delivery_logs` **Flow Builder**: `get_chatbot_flow`, `update_chatbot_flow`, `add_flow_node`, `delete_flow_node`, `connect_flow_nodes`, `list_flow_versions`, `publish_flow_version` **Templates**: `list_templates`, `get_template_categories`, `create_from_template` **Knowledge Base**: `list_knowledge_base`, `get_knowledge_article`, `create_knowledge_article`, `update_knowledge_article`, `delete_knowledge_article`, `list_knowledge_categories`, `create_knowledge_category`, `delete_knowledge_category`, `get_ai_config`, `update_ai_config` **Widget & Channels**: `get_widget_config`, `update_widget_config`, `list_channels`, `get_channel_config`, `export_chatbot` **Account**: `get_account_profile`, `update_account_profile`, `request_email_change`, `verify_email_identity`, `confirm_email_change` **Conversations**: `list_conversations`, `get_conversation`, `get_conversation_analytics`, `list_tickets`, `get_conversation_summary` ### MCP Resources - `conferbot://chatbots` — All chatbots - `conferbot://chatbot/{id}` — Chatbot details - `conferbot://chatbot/{id}/analytics` — 30-day analytics - `conferbot://chatbot/{id}/widget` — Widget config - `conferbot://chatbot/{id}/conversations` — Recent conversations - `conferbot://usage` — API usage - `conferbot://account` — Account profile (contact details and preferences) ### MCP Prompts - `analyze-chatbot-performance` — Analyze metrics, trends, recommendations - `debug-webhook-deliveries` — Diagnose webhook failures - `generate-analytics-report` — Generate formatted report - `build-chatbot-flow` — Build conversation flow from natural language - `optimize-chatbot` — Analyze and suggest improvements - `setup-knowledge-base` — Guide KB setup with categories and articles ## Mobile SDKs Native SDKs embed the full Conferbot chat experience (all flow node types, floating chat bubble, live agent handover, offline queueing, push notification hooks, server-driven theming) in mobile apps. They talk to the widget delivery service at `https://wdt.conferbot.com` (REST + Socket.IO) and are a SEPARATE product from this management REST API - they do not use `x-api-key` or consume API quota. The only real credential is the 24-char hex **bot ID** from Bot Settings > General. The SDK `apiKey` param is validated locally only - any placeholder in the `conf_` format works (e.g. `conf_test_key`); it is NOT the management REST API key. The bot must be published. Public demo bot for evaluation without an account: `691c970890527a0468f9b2c9`. | Platform | Package | Registry | Minimum | |---|---|---|---| | Android (Kotlin) | `com.conferbot:android-sdk` | Maven Central | Android 5.0 (API 21), Kotlin 1.9 | | iOS (Swift) | `Conferbot` | SPM + CocoaPods | iOS 14.0, Swift 5.7 | | Flutter | `conferbot_flutter` | pub.dev | Flutter 3.10, Dart 3.0 | | React Native | `@conferbot/react-native` | npm | RN 0.70, iOS 12+, Android API 21+ | Minimal integrations: - **Android**: `Conferbot.initialize(context, apiKey, botId)` in `Application.onCreate()`; `Conferbot.openChat(activity)` or Compose `ConferBotWidgetScope { ... }` for the floating bubble; `Conferbot.identify(ConferBotUser(id, name, email))` before opening chat. - **iOS**: `ConferBot.shared.initialize(apiKey:botId:)`; `ConferBot.shared.present(from:)` (UIKit) or SwiftUI `ChatView()` / `.conferBotWidget()` FAB overlay; `ConferBot.shared.identify(user:)` then `startSession()`. - **Flutter**: `await StorageService.init()` before `runApp`, then `ConferBotProvider(apiKey:, botId:)` via provider, `ChatWidget()` drop-in UI, or `ConferBotFABScope(apiKey:, botId:, child:)` one-liner FAB; pass `user: ConferBotUser(id: ...)` for identity. - **React Native**: wrap app in ``, drop `` for the FAB, `` for a controlled modal, or `useConferBot()` hook for headless. Theming is server-driven on all four: dashboard flow-builder customizations (colors, avatar, bot name, widget placement, CTA tooltip) apply automatically and win over local themes. Repos: github.com/Conferbot/conferbot-{android,ios,flutter,react-native}. Docs: overview at https://developers.conferbot.com/docs/mobile-sdks.md, per-SDK guides at https://developers.conferbot.com/docs/mobile-sdks/android.md, /docs/mobile-sdks/ios.md, /docs/mobile-sdks/flutter.md, /docs/mobile-sdks/react-native.md ## Platform Integrations The web widget embeds on any site with one script tag (only credential: the 24-char bot ID; all styling comes from the dashboard at runtime): ```html ``` Contract: `window.ConferbotWidget(botId, embedType, options?)` with `embedType` = `"live_chat" | "popup_chat" | "fullpage_chat"` (floating bubble | modal | full page auto-open). Optional third arg passes identity/context: `{ user: { id, name, email, ...custom }, customData: { platform, storeName, cartTotal, ... } }` - this is how the platform modules attach the logged-in customer and store context. Nine official platform modules wrap this snippet (repos at github.com/Conferbot/conferbot-{platform}): - **WordPress**: install plugin, Settings > Conferbot, paste bot ID (WooCommerce-aware) - **Shopify**: OAuth app + ScriptTag API; paste bot ID in the app settings page - **BigCommerce**: OAuth app + Scripts API v3 (async, all pages, auto-uninstall) - **Wix**: OAuth app + Embedded Script component - **Joomla** (4.2+/5.x): upload zip, System > Manage > Plugins > "System - Conferbot", enable - **Magento 2** (2.4.x): `composer require conferbot/module-chat`, enable `Conferbot_Chat`, configure at Stores > Configuration > Services > Conferbot - **OpenCart** (3.0.x): upload `conferbot.ocmod.zip` via Extensions > Installer, install under Modules - **Ecwid**: OAuth app; storefront loader reads bot ID via `Ecwid.getAppPublicConfig()` - **PrestaShop** (1.7/8.x): upload `conferbot.zip` in Module Manager, Configure; per-page-type visibility Docs: overview at https://developers.conferbot.com/docs/integrations.md, web widget guide at https://developers.conferbot.com/docs/integrations/web-widget.md, per-platform guides at https://developers.conferbot.com/docs/integrations/.md (wordpress, shopify, bigcommerce, wix, joomla, magento, opencart, ecwid, prestashop) ## Plans | Plan | Chatbots | API Calls/mo | Webhooks | API Access | |------------|----------|--------------|----------|------------| | Free | 1 | - | 0 | No | | Starter | 5 | 10,000 | 5 | Yes | | Pro | 15 | 50,000 | 15 | Yes | | Business | 25 | 200,000 | 50 | Yes | | Enterprise | 100 | Unlimited | 999 | Yes | ## Common Integration Recipes ### Sync chatbot leads to CRM (Node.js) ```typescript const BASE = "https://api-v2.conferbot.com/api/v1"; const headers = { "x-api-key": process.env.CONFERBOT_API_KEY! }; // Get all responses from last 24 hours (paginate until totalPages) const yesterday = new Date(Date.now() - 86400000).toISOString().split("T")[0]; let page = 1, totalPages = 1; while (page <= totalPages) { const res = await fetch( `${BASE}/external/v1/chatbots/CHATBOT_ID/responses?page=${page}&limit=100&startDate=${yesterday}`, { headers } ); const body = await res.json(); totalPages = body.totalPages; for (const response of body.data) { const { email, name, phone } = response.answerVariables || {}; if (email) { // Push to your CRM await crm.createLead({ email, name, phone, source: "chatbot" }); } } page++; } ``` ### Real-time lead capture via webhook (Node.js) ```typescript import express from "express"; import crypto from "node:crypto"; const app = express(); app.post("/webhook", express.raw({ type: "application/json" }), async (req, res) => { const expected = crypto .createHmac("sha256", process.env.WEBHOOK_SECRET!) .update(req.body) .digest("hex"); const given = req.headers["x-webhook-signature"] as string; if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(given))) { return res.sendStatus(401); } const event = JSON.parse(req.body.toString()); if (event.event === "response.created") { // Fetch full response to get answerVariables const r = await fetch( `https://api-v2.conferbot.com/api/v1/external/v1/chatbots/${event.botId}/responses/${event.responseId}`, { headers: { "x-api-key": process.env.CONFERBOT_API_KEY! } } ); const response = await r.json(); console.log("New lead:", response.data.answerVariables); } res.sendStatus(200); }); ``` ### Monitor chatbot performance (Python) ```python import os import requests BASE = "https://api-v2.conferbot.com/api/v1" headers = {"x-api-key": os.environ["CONFERBOT_API_KEY"]} bots = requests.get(f"{BASE}/external/v1/chatbots", headers=headers).json()["data"] for bot in bots: stats = requests.get( f"{BASE}/external/v1/chatbots/{bot['id']}/analytics", headers=headers, params={"days": 7}, ).json() print(f"{bot['name']}: {stats['data']['recentResponses']} responses this week") usage = requests.get(f"{BASE}/external/v1/usage", headers=headers).json() print(f"API usage: {usage['data']['used']}/{usage['data']['limit']} calls this month") ``` ### Embed chatbot on website Use the loader snippet from the Platform Integrations section above (`window.ConferbotWidget("YOUR_BOT_ID", "live_chat")` via `https://cdn.conferbot.com/dist/v1/widget.min.js`), added before the closing `` tag. ## Quick Start 1. **Sign up** at https://app.conferbot.com and create a chatbot 2. **Generate API key** from Dashboard > Workspace > API Keys 3. **Make first call**: List your chatbots with `curl` (or any HTTP client) to verify the key works 4. **Set up webhooks** to receive real-time events when visitors interact with your chatbot 5. **For AI IDEs**: Configure the MCP server for natural-language chatbot management ## Docs - [Getting Started](https://developers.conferbot.com/docs/getting-started) — API key setup, authentication, rate limits, error handling - [API Reference](https://developers.conferbot.com/api-reference) — Full endpoint documentation with interactive examples - [API Playground](https://developers.conferbot.com/api-reference/playground) — Test endpoints live with Swagger UI - [Webhooks Guide](https://developers.conferbot.com/docs/webhooks) — Event types, HMAC verification, retry policy - [MCP Integration](https://developers.conferbot.com/docs/mcp) — AI IDE setup for Claude Code, Cursor, Windsurf, JetBrains, Codex - [Mobile SDKs Overview](https://developers.conferbot.com/docs/mobile-sdks) - Android, iOS, Flutter, React Native native chat SDKs - [Android SDK](https://developers.conferbot.com/docs/mobile-sdks/android) - Kotlin SDK guide (Maven Central) - [iOS SDK](https://developers.conferbot.com/docs/mobile-sdks/ios) - Swift SDK guide (SPM + CocoaPods) - [Flutter SDK](https://developers.conferbot.com/docs/mobile-sdks/flutter) - Dart SDK guide (pub.dev) - [React Native SDK](https://developers.conferbot.com/docs/mobile-sdks/react-native) - TypeScript SDK guide (npm) - [Platform Integrations Overview](https://developers.conferbot.com/docs/integrations) - Web widget embed plus WordPress, Shopify, BigCommerce, Wix, Joomla, Magento, OpenCart, Ecwid, PrestaShop modules - [Web Widget](https://developers.conferbot.com/docs/integrations/web-widget) - Script embed and ConferbotWidget contract - [WordPress](https://developers.conferbot.com/docs/integrations/wordpress) - Plugin guide - [Shopify](https://developers.conferbot.com/docs/integrations/shopify) - App guide - [BigCommerce](https://developers.conferbot.com/docs/integrations/bigcommerce) - App guide - [Wix](https://developers.conferbot.com/docs/integrations/wix) - App guide - [Joomla](https://developers.conferbot.com/docs/integrations/joomla) - Plugin guide - [Magento](https://developers.conferbot.com/docs/integrations/magento) - Module guide - [OpenCart](https://developers.conferbot.com/docs/integrations/opencart) - Extension guide - [Ecwid](https://developers.conferbot.com/docs/integrations/ecwid) - App guide - [PrestaShop](https://developers.conferbot.com/docs/integrations/prestashop) - Module guide - [Custom Subdomain](https://developers.conferbot.com/docs/custom-subdomain) — Branded login pages, setup steps, API endpoints, validation rules - [Changelog](https://developers.conferbot.com/changelog) — Version history and release notes