Quick start
The Chatloom API lets you set up and run your agents from your own code: create one from your website, add knowledge, change its look, restrict where it loads, and send it messages. You authenticate with an API key that you generate in the dashboard and send on every request.
- Open Settings and go to the API tab.
- Click Generate API key and copy it. You can reveal and copy it again from the same tab later.
- Call any endpoint with your key in the
Authorizationheader.
curl https://chatloom.app/api/plugin/agents \
-H "Authorization: Bearer clf_your_api_key_here"A successful response returns JSON with the list of your agents:
{
"agents": [
{
"id": "cm9k2x7p40001ab12cd34ef56",
"name": "Sales Assistant",
"primaryColor": "#611F69",
"secondaryColor": "#764ba2",
"position": "bottom-right",
"template": "modern",
"status": "active",
"createdAt": "2026-01-15T09:00:00.000Z"
}
],
"count": 1
}Authentication
All requests must include a valid API key. You can send it as either a bearer token or a custom header. Both work identically; pick whichever fits your client best.
Option 1: Authorization header (recommended)
Authorization: Bearer clf_your_api_key_hereOption 2: X-API-Key header
X-API-Key: clf_your_api_key_hereKeys always start with the clf_ prefix. A workspace has one key, and it can do everything on this page for every agent in the workspace. Treat it like a password: keep it server-side (an environment variable such as CHATLOOM_API_KEY), never commit it to a repository or paste it into a public page, and regenerate it if you suspect it has been exposed. Regenerating in Settings revokes the old key immediately.
Base URL
https://chatloom.appAll endpoints below are relative to this base. The API serves only over HTTPS; plain http:// requests are redirected.
Endpoints
In the order you would use them: create an agent, give it knowledge, test it, style it, restrict where it loads, and put it on your site. Every path below takes the API key and only reaches agents in that key's workspace; any other agent id returns 404.
POST/api/plugin/agents
Create an agent. With a url, Chatloom crawls up to 5 pages of that site, creates the agent, names it and writes a greeting from the site, and trains it on those pages in the same call (allow up to a few minutes on slow sites). Products found on the site are imported too. Without a url you get an empty agent to train with the endpoints below. The new agent has no domain restriction, so its widget loads on any site until you add an allowed domain.
Request body
| Field | Type | Description |
|---|---|---|
url | string | Optional. A public page of the business's site to crawl and train on. |
name | string | Optional. The agent's name (1–80 characters). Taken from the site when omitted. |
Response fields
| Field | Type | Description |
|---|---|---|
agentId | string | The new agent's id. |
name | string | The name the agent was given. |
pagesIndexed | integer | Pages trained on (0 without a url). |
productsImported | integer | Products found on the site and imported (url only). |
trained | boolean | Whether any knowledge was added. |
nameNeedsReview | boolean | true when the site gave no usable name (a login wall, a parked domain). Ask the owner for one and create the agent again with name. |
curl -X POST https://chatloom.app/api/plugin/agents \
-H "Authorization: Bearer clf_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"url": "https://www.example-bakery.com"}'{
"agentId": "cm9k2x7p40001ab12cd34ef56",
"name": "Example Bakery",
"domain": "example-bakery.com",
"pagesIndexed": 5,
"productsImported": 0,
"trained": true,
"nameNeedsReview": false
}A workspace at its plan's agent limit gets 403 with agent_limit_reached. A site that cannot be crawled or has no readable text gets 422 with crawl_failed or no_content, and no agent is created.
GET/api/plugin/agents
Returns every agent in the workspace, newest first.
Response fields
| Field | Type | Description |
|---|---|---|
agents[].id | string | The agent's id. Use it as agentId in the other endpoints and in the embed snippet. |
agents[].name | string | Display name shown in the widget header. |
agents[].primaryColor | string | Hex color of the launcher and primary accents. |
agents[].secondaryColor | string | Hex color of gradients and secondary accents. |
agents[].position | string | bottom-right, bottom-left, top-right or top-left. |
agents[].template | string | Widget template name. |
agents[].status | string | Usually active. Deleted agents are left out. |
agents[].createdAt | string (ISO 8601) | Creation timestamp. |
count | integer | Number of agents returned. |
const response = await fetch("https://chatloom.app/api/plugin/agents", {
headers: {
Authorization: `Bearer ${process.env.CHATLOOM_API_KEY}`,
},
})
if (!response.ok) {
throw new Error(`Chatloom API ${response.status}`)
}
const { agents, count } = await response.json()
console.log(`You have ${count} agents`)POST/api/plugin/agents/{agentId}/training
Add knowledge to an agent: crawl a URL, push raw text, or add question and answer pairs. Send one of the three per request. This is how you keep a bot in sync with your own CMS, catalog or docs without opening the dashboard. Crawled pages are re-crawled weekly afterwards, so the agent follows changes on the site.
Request body (send one)
| Field | Type | Description |
|---|---|---|
url | string | A page to crawl (up to 5 pages from there) and ingest. |
text | string | Raw text to ingest as one document, with an optional title. |
qa | array | Up to 50 { question, answer } pairs, each stored as its own document. |
Response
{ success: true, ingested, failed } (a crawl also returns domain). A workspace over its plan's knowledge limit gets 403 with training_limit_reached and the limit, used and remaining figures.
curl -X POST https://chatloom.app/api/plugin/agents/cm9k2x7p40001ab12cd34ef56/training \
-H "Authorization: Bearer clf_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"qa": [{"question": "Do you ship to the EU?", "answer": "Yes, in 3–5 days."}]}'POST/api/plugin/agents/{agentId}/training/upload
Upload a PDF, DOCX or TXT file (up to 20 MB) as multipart/form-data with a file field. The text is extracted and added to the agent's knowledge. The response is { success: true, documentId, fileName, isDuplicate }; the same file uploaded twice is stored once.
curl -X POST https://chatloom.app/api/plugin/agents/cm9k2x7p40001ab12cd34ef56/training/upload \
-H "Authorization: Bearer clf_your_api_key_here" \
-F "file=@price-list.pdf"POST/api/plugin/agents/{agentId}/chat
Send a message to an agent and get its reply, from the same knowledge-grounded engine that powers the web widget and the messaging channels. Use it to test an agent after training, or to put the agent inside your own product. Pass the conversationId you get back to continue the same thread; the server keeps the history.
Request body
| Field | Type | Description |
|---|---|---|
message | string | The user's message (1–4000 characters). Required. |
conversationId | string | Optional. Omit to start a new conversation; pass a previously returned id to continue one. Ids that don't belong to this agent are ignored and a new conversation is started. |
Response fields
| Field | Type | Description |
|---|---|---|
reply | string | The agent's reply text. |
conversationId | string | Pass this back on the next call to continue the thread. |
usage.used / usage.limit / usage.remaining | number | Monthly message usage after this call. A question and its reply count as one message against your plan's limit, the same as on the widget (a limit of -1 means unlimited). A 402 is returned when the quota is used up. |
curl -X POST https://chatloom.app/api/plugin/agents/cm9k2x7p40001ab12cd34ef56/chat \
-H "Authorization: Bearer clf_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"message": "What are your opening hours?"}'const res = await fetch(
"https://chatloom.app/api/plugin/agents/cm9k2x7p40001ab12cd34ef56/chat",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CHATLOOM_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ message: "What are your opening hours?" }),
},
)
const { reply, conversationId, usage } = await res.json()PATCH/api/plugin/agents/{agentId}/config
Change how the widget looks. Only appearance fields are accepted; the agent's instructions, knowledge and channels cannot be changed here. Send any of: primaryColor, secondaryColor, fontFamily, position, primaryColorOpacity, secondaryColorOpacity, useGradient, gradientAngle, launcherIcon, customLauncherIcon. The response lists what was applied and what was rejected as invalid. Live widgets pick the change up on their next load.
curl -X PATCH https://chatloom.app/api/plugin/agents/cm9k2x7p40001ab12cd34ef56/config \
-H "Authorization: Bearer clf_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"primaryColor": "#0F766E", "position": "bottom-left"}'GETPOSTDELETE/api/plugin/agents/{agentId}/allowed-domains
Read or change the domains the agent's widget may load on. With no domains the widget loads anywhere; once you add one, it loads only on the listed domains and their subdomains. GET returns { domains: string[] }, oldest first. POST and DELETE take { "domain": "example.com" } and return the updated list plus the added or removed domain. Adding past your plan's domain limit returns 403.
curl -X POST https://chatloom.app/api/plugin/agents/cm9k2x7p40001ab12cd34ef56/allowed-domains \
-H "Authorization: Bearer clf_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"domain": "example-bakery.com"}'{
"domains": ["example-bakery.com"],
"added": "example-bakery.com"
}Install the widget
Put this tag on every page where the chat should appear, just before </body> or in your site builder's custom code setting. Appearance, greeting and language come from the agent's settings, so the tag never needs to change.
<script src="https://chatloom.app/widget.js" data-agent-id="cm9k2x7p40001ab12cd34ef56"></script>Shopify and Framer have their own installs (the Chatloom app and plugin), and the dashboard's install page has step-by-step guides for WordPress, Wix, Webflow and other builders.
Webhooks
Chatloom can POST an event to your own URL when something happens in a conversation. Add a webhook in the dashboard under Integrations → Webhooks, choose its events and save the signing secret it shows you (it is shown once). The Test button sends a signed webhook.test event so you can check your endpoint.
conversation.created: a new conversation starts on the website widget, a messaging channel or the chat endpoint.conversation.escalated: the conversation needs a human (the customer asked for one, or the agent handed over).lead.captured: a visitor left an email address or phone number in the chat.appointment.booked: an appointment was booked in the connected Google Calendar or Cal.com.rating.submitted: a visitor rated the conversation in the website widget.
{
"event": "lead.captured",
"agentId": "cm9k2x7p40001ab12cd34ef56",
"timestamp": "2026-10-20T09:30:00.000Z",
"data": {
"conversationId": "cm9k3a1b20002ab12cd34ef56",
"channel": "web",
"customerName": "Ana",
"customerEmail": "ana@example.com",
"customerPhone": null,
"customerMessage": "Can you call me about a wedding cake?",
"conversationUrl": "https://chatloom.app/en/dashboard/inbox?id=cm9k3a1b20002ab12cd34ef56",
"agentName": "Example Bakery"
}
}Each request carries X-Webhook-Event and X-Webhook-Signature, the hex HMAC-SHA256 of the raw request body with your signing secret. Compare it before trusting the payload, and answer with any 2xx within 30 seconds. Your URL must be public HTTPS; redirects are not followed. Each event is sent once, without retries, and the result of the last attempt shows on the webhook in the dashboard. Every payload's data includes agentName.
import crypto from "node:crypto"
function isFromChatloom(rawBody, signature, secret) {
const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex")
return (
typeof signature === "string" &&
signature.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
)
}Set up with an AI assistant
An AI assistant can do the whole setup for you: create the agent from the business's website, add what the site does not say, test it with real customer questions, adjust its tone and tell you, or do itself, how to put it on the site.
Claude and other MCP clients
Chatloom runs a remote MCP server. Add it to your assistant, sign in to Chatloom and approve access once; the assistant never sees your password or an API key.
https://chatloom.app/api/mcp- Claude (claude.ai or the desktop app): Settings → Connectors → Add custom connector, paste the URL, then Connect.
- Claude Code: run the command below, then
/mcpto sign in. - Cursor and other clients: add a remote MCP server with this URL; they open the Chatloom sign-in when you first connect.
claude mcp add --transport http chatloom https://chatloom.app/api/mcpThen ask, in your own words, for example:
Set up a Chatloom chatbot for https://www.example-bakery.com, test it with three
questions a customer would ask, and tell me how to add it to my Wix site.The assistant gets these tools:
| Tool | Type | Description |
|---|---|---|
list_agents | read | Your agents and how many your plan allows. |
get_agent | read | One agent's settings, knowledge size, channels and install status. |
list_knowledge | read | The pages, files and entries an agent answers from. |
review_conversations | read | What customers asked recently and what the agent could not answer. |
get_install_instructions | read | The embed tag and steps for your site platform. |
test_agent | test | Up to 3 test questions from your monthly test allowance; nothing is saved and no customer is contacted. |
create_agent | write | A new agent, trained from your website in one step. |
add_knowledge | write | A page, text or Q&A pairs added to an agent. |
update_agent_behavior | write | Tone, answer length and custom instructions (saved as a version). |
update_agent_profile | write | Name, greeting, colors and bubble position. |
manage_allowed_domains | write | Which domains the widget may load on. |
Your plan's limits apply exactly as in the dashboard, and each test answer counts toward your monthly test allowance. Write tools are marked as such, so your assistant can ask you before it runs them. Messaging channels (WhatsApp, Instagram, Telegram and the rest) are connected in the dashboard, where the assistant will point you.
Coding assistants with an API key
In a code project you can also give a coding assistant such as Claude Code, Cursor or Codex the API key and this page; it then calls the endpoints above directly. Put the key in the project's environment rather than in the chat.
# .env.local (never commit this file)
CHATLOOM_API_KEY=clf_your_api_key_hereRead https://chatloom.app/en/docs/api. Using CHATLOOM_API_KEY from .env.local:
1. Create a Chatloom agent from https://www.example-bakery.com.
2. Upload ./docs/menu.pdf to it.
3. Ask it three questions a customer would ask and show me the answers.
4. Restrict it to example-bakery.com.
5. Add the embed script to the root layout of this site.The key gives full access to the workspace, so use it only in a project you control and regenerate it when the work is done if you shared it anywhere else.
Errors
Errors are returned as JSON with an error field (a code such as agent_limit_reached or a sentence), often a message to show a person, and the HTTP status below. There is no envelope: a successful response returns the resource directly.
{
"error": "API key is required. Please provide it in Authorization or X-API-Key header."
}| Status | Meaning |
|---|---|
| 200 | The request succeeded. |
| 400 | The request body or parameters were malformed. The error message describes what to fix. |
| 401 | No API key was provided, or the key is invalid, expired, or malformed (wrong prefix). |
| 402 | The workspace has used its monthly messages (chat endpoint). |
| 403 | A plan limit was reached (agent_limit_reached, training_limit_reached, the domain limit), or the account is suspended. |
| 404 | The agent doesn't exist or isn't owned by the authenticated workspace. |
| 422 | The site could not be crawled or had no readable text (crawl_failed, no_content). |
| 429 | You've hit a rate limit. Wait the retryAfter seconds in the response, then retry. |
| 502 | The agent could not generate a reply this time (chat endpoint). The conversationId comes back so you can retry in the same thread. |
| 500 | Something went wrong on our side. Retry with backoff and contact support if it persists. |
Rate limits
The chat endpoint allows 120 requests a minute per agent. The other endpoints allow 300 requests a minute and 30 in any 10 seconds per workspace. A crawl or file upload can take minutes, so send those one at a time. The API is meant for setup, sync and your own integrations; website visitors should reach the agent through the widget, which has its own limits.
If you need higher throughput for a specific integration, email us at support@chatloom.app with your use case and we'll help you design it.
Roadmap
The public API surface will grow as customers ask for specific flows. Items we're actively considering, based on user demand:
- Conversation history export: read past conversations with filters for date range, channel, and satisfaction score.
- Knowledge management: list, update and delete the documents in an agent's knowledge base (adding them works today, see above).
- A webhook for every new message, in addition to the events above.
- Analytics export: pull the same metrics the Analytics dashboard shows, in JSON or CSV.
If any of these matter to you, replying to us with your use case genuinely helps us prioritise.
Support
Email support@chatloom.app with your workspace name and a description of what you're trying to build. For issues that block a release, mention that in the subject line and we'll prioritise.
Found a bug in the docs or an endpoint that doesn't behave the way this page describes? That's a bug. Please send us the request and response so we can fix it.