Skip to content
v1 · Public API

Chatloom API Reference

Create, train, configure and talk to the agents on your Chatloom workspace from your own code. Available on every plan; your plan's limits on agents, knowledge and monthly messages apply exactly as they do in the dashboard.

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.

  1. Open Settings and go to the API tab.
  2. Click Generate API key and copy it. You can reveal and copy it again from the same tab later.
  3. Call any endpoint with your key in the Authorization header.
bash
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:

json
{
  "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)

http
Authorization: Bearer clf_your_api_key_here

Option 2: X-API-Key header

http
X-API-Key: clf_your_api_key_here

Keys 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

http
https://chatloom.app

All 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

FieldTypeDescription
url
stringOptional. A public page of the business's site to crawl and train on.
name
stringOptional. The agent's name (1–80 characters). Taken from the site when omitted.

Response fields

FieldTypeDescription
agentId
stringThe new agent's id.
name
stringThe name the agent was given.
pagesIndexed
integerPages trained on (0 without a url).
productsImported
integerProducts found on the site and imported (url only).
trained
booleanWhether any knowledge was added.
nameNeedsReview
booleantrue 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.
bash
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"}'
json
{
  "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

FieldTypeDescription
agents[].id
stringThe agent's id. Use it as agentId in the other endpoints and in the embed snippet.
agents[].name
stringDisplay name shown in the widget header.
agents[].primaryColor
stringHex color of the launcher and primary accents.
agents[].secondaryColor
stringHex color of gradients and secondary accents.
agents[].position
stringbottom-right, bottom-left, top-right or top-left.
agents[].template
stringWidget template name.
agents[].status
stringUsually active. Deleted agents are left out.
agents[].createdAt
string (ISO 8601)Creation timestamp.
count
integerNumber of agents returned.
javascript
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)

FieldTypeDescription
url
stringA page to crawl (up to 5 pages from there) and ingest.
text
stringRaw text to ingest as one document, with an optional title.
qa
arrayUp 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.

bash
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.

bash
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

FieldTypeDescription
message
stringThe user's message (1–4000 characters). Required.
conversationId
stringOptional. 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

FieldTypeDescription
reply
stringThe agent's reply text.
conversationId
stringPass this back on the next call to continue the thread.
usage.used / usage.limit / usage.remaining
numberMonthly 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.
bash
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?"}'
javascript
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.

bash
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.

bash
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"}'
json
{
  "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.

html
<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.
json
{
  "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.

javascript
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.

text
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 /mcp to sign in.
  • Cursor and other clients: add a remote MCP server with this URL; they open the Chatloom sign-in when you first connect.
bash
claude mcp add --transport http chatloom https://chatloom.app/api/mcp

Then ask, in your own words, for example:

text
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:

ToolTypeDescription
list_agents
readYour agents and how many your plan allows.
get_agent
readOne agent's settings, knowledge size, channels and install status.
list_knowledge
readThe pages, files and entries an agent answers from.
review_conversations
readWhat customers asked recently and what the agent could not answer.
get_install_instructions
readThe embed tag and steps for your site platform.
test_agent
testUp to 3 test questions from your monthly test allowance; nothing is saved and no customer is contacted.
create_agent
writeA new agent, trained from your website in one step.
add_knowledge
writeA page, text or Q&A pairs added to an agent.
update_agent_behavior
writeTone, answer length and custom instructions (saved as a version).
update_agent_profile
writeName, greeting, colors and bubble position.
manage_allowed_domains
writeWhich 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.

bash
# .env.local (never commit this file)
CHATLOOM_API_KEY=clf_your_api_key_here
text
Read 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.

json
{
  "error": "API key is required. Please provide it in Authorization or X-API-Key header."
}
StatusMeaning
200The request succeeded.
400The request body or parameters were malformed. The error message describes what to fix.
401No API key was provided, or the key is invalid, expired, or malformed (wrong prefix).
402The workspace has used its monthly messages (chat endpoint).
403A plan limit was reached (agent_limit_reached, training_limit_reached, the domain limit), or the account is suspended.
404The agent doesn't exist or isn't owned by the authenticated workspace.
422The site could not be crawled or had no readable text (crawl_failed, no_content).
429You've hit a rate limit. Wait the retryAfter seconds in the response, then retry.
502The agent could not generate a reply this time (chat endpoint). The conversationId comes back so you can retry in the same thread.
500Something 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.