Skip to content
Help centre / API

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": "your-business-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://yourbusiness.com/areas-we-cover" }]
}

When answered is false, the question was not fully resolved. The resolution field distinguishes a useful partial answer from an unanswered question. The reply may contain supported details, a fallback or a temporary verification error.

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://yourbusiness.com/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();

// Opens the chat and asks a question, as if the visitor typed it
window.CustomerChat.ask("When is the next home match?");

// Hides the chat button on pages where you don't want it, and brings it back
window.CustomerChat.hide();
window.CustomerChat.show();

Visitors can drag the chat button anywhere on the screen if it's covering something, and it stays there on later visits. window.CustomerChat.resetPosition() puts it back in its corner.