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
401missing or revoked key402plan limit reached or API not on your plan404bot not found in your workspace429more 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.