API reference

The REST API lets you send messages to a trained assistant and get answers back, so you can build your own chat interface, connect a phone system or answer emails. Available on the Pro plan.

Authentication

Create a key in Settings › API and send it as a bearer token. Keys are shown once; keep them on your server, never in browser code.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxx

Send a message

POST /api/v1/chat with the bot ID from your embed snippet (data-bot). Pass the returned conversationId to continue the same conversation.

curl https://customerchat.ai/api/v1/chat \
  -H "Authorization: Bearer $CUSTOMERCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bot": "acme-plumbing-7f3k",
    "message": "Do you cover Salford?",
    "conversationId": null
  }'

Response

{
  "conversationId": "cm1x...",
  "messageId": "cm1y...",
  "answer": "Yes, Salford is in our core area, so there's no call-out charge.",
  "answered": true,
  "confidence": 0.91,
  "sources": [{ "title": "Areas we cover", "url": "https://acmeplumbing.co.uk/areas-we-cover" }]
}

When answered is false, the assistant couldn't find a reliable answer and returned your fallback message.

Webhooks

Connect a webhook in Integrations to receive events as JSON POST requests.

{
  "event": "lead.created",
  "bot": { "id": "cm1a...", "name": "Acme Plumbing Assistant" },
  "lead": { "id": "cm1b...", "name": "Priya Shah", "email": "priya.shah@example.com", "phone": "07700 900123", "message": "Boiler service", "pageUrl": "https://acmeplumbing.co.uk/pricing" },
  "createdAt": "2026-10-01T09:14:00.000Z"
}

Events: lead.created, handoff.requested.

Errors and limits

401 missing or revoked key
402 plan limit reached or API not on your plan
404 bot not found in your workspace
429 more than 120 requests a minute per key

JavaScript widget API

Once the snippet is on your page you can control the widget from your own buttons:

window.CustomerChat.open();
window.CustomerChat.close();
window.CustomerChat.toggle();