Chatloom API

Read your chatbots' leads and chats, and send messages to your chatbot from your own apps. Available on the Pro plan. To get events as they happen instead, use a webhook step in Automations.

Authentication

Create a key in your dashboard under Developers, and send it with every request in the Authorization header. Keys belong to a workspace. A key can be read-only (it can't send messages or change contacts) and can be limited to some of the workspace's chatbots. Keep them on your server, never in a website or app people download, and revoke any key you think has leaked.

Authorization: Bearer ck_live_…

All addresses start with https://chatloom.co/api/v1. Responses are JSON, and times are milliseconds since 1970 (UTC). Reading leads and chats through the API is recorded in the workspace's access log.

List chatbots

GET /bots

The workspace's chatbots. Use their ids in the other addresses.

curl https://chatloom.co/api/v1/bots \
  -H "Authorization: Bearer $CHATLOOM_KEY"

{
  "data": [
    { "id": "bot_8f2k1q", "name": "Website assistant", "created_at": 1790000000000 }
  ]
}

List leads

GET /bots/{botId}/leads

Contact details visitors left with the chatbot, oldest first. To get only new ones, pass the next_since from your last call as since.

since: Only leads created after this time: milliseconds since 1970, or an ISO date like 2026-10-01T00:00:00Z. Default: from the start.
limit: How many to return, 1 to 100. Default 50.

curl "https://chatloom.co/api/v1/bots/bot_8f2k1q/leads?since=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $CHATLOOM_KEY"

{
  "data": [
    {
      "id": "lead_3nd81c",
      "name": "Sara Khan",
      "email": "[email protected]",
      "phone": "+971 50 123 4567",
      "status": "new",
      "conversation_id": "conv_k2m9d1",
      "created_at": 1790003600000
    }
  ],
  "next_since": 1790003600000
}

List chats

GET /bots/{botId}/conversations

Website chats, oldest change first, without their messages. Use since with next_since to pick up chats that are new or have new messages.

since: Only chats updated after this time (milliseconds or an ISO date).
limit: How many to return, 1 to 100. Default 50.

curl "https://chatloom.co/api/v1/bots/bot_8f2k1q/conversations?limit=20" \
  -H "Authorization: Bearer $CHATLOOM_KEY"

{
  "data": [
    {
      "id": "conv_k2m9d1",
      "created_at": 1790003000000,
      "updated_at": 1790003700000,
      "page_url": "https://example.com/pricing",
      "topic": "Pricing",
      "mood": "positive",
      "rating": 1,
      "messages": 6
    }
  ],
  "next_since": 1790003700000
}

Get a chat

GET /conversations/{conversationId}

One chat with all its messages. role is visitor, chatbot, or team (a person replying from the dashboard).

curl https://chatloom.co/api/v1/conversations/conv_k2m9d1 \
  -H "Authorization: Bearer $CHATLOOM_KEY"

{
  "data": {
    "id": "conv_k2m9d1",
    "bot_id": "bot_8f2k1q",
    "page_url": "https://example.com/pricing",
    "topic": "Pricing",
    "messages": [
      { "role": "visitor", "content": "Do you deliver on Fridays?", "created_at": 1790003000000 },
      { "role": "chatbot", "content": "Yes, we deliver every day from 9am to 9pm.", "created_at": 1790003002000 }
    ]
  }
}

Send a message

POST /bots/{botId}/messages

Ask the chatbot something and get its answer, for example from your app or a WhatsApp integration. It answers from the same content as on your website and uses message credits the same way. Booking and form cards aren't returned; the reply text says what to do instead.

message: Required. What the person asked, up to 4,000 characters.
conversation_id: Optional. Continue a chat this API started, so the chatbot remembers what was said.
visitor_id: Optional. Your own id for the person (letters, numbers and _.:-), so different people's chats stay apart.

curl https://chatloom.co/api/v1/bots/bot_8f2k1q/messages \
  -H "Authorization: Bearer $CHATLOOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Do you deliver on Fridays?", "visitor_id": "customer_1042"}'

{
  "data": {
    "conversation_id": "conv_p0x7aa",
    "reply": "Yes, we deliver every day from 9am to 9pm.",
    "sources": [{ "title": "Delivery", "url": "https://example.com/delivery" }]
  }
}

List contacts

GET /bots/{botId}/contacts

Your known customers, most recently seen first, with the details the chatbot uses when they chat signed in.

q: Optional. Search names, emails and details.
limit: How many to return, 1 to 100. Default 50.
offset: How many to skip, for the next page.

curl "https://chatloom.co/api/v1/bots/bot_8f2k1q/contacts?limit=20" \
  -H "Authorization: Bearer $CHATLOOM_KEY"

{
  "data": [
    {
      "email": "[email protected]",
      "name": "Sara Khan",
      "details": { "Plan": "Pro", "Last order": "#1042 (shipped)" },
      "source": "api",
      "chats": 3,
      "last_seen_at": 1790003600000,
      "created_at": 1789000000000
    }
  ]
}

Add or update contacts

POST /bots/{botId}/contacts

Adds contacts, or updates the ones with these emails. Details are merged with what's stored; set a detail to an empty string to remove it. Send one contact, or up to 100 as { "contacts": [...] }. When a contact chats signed in on your website, the chatbot can use their details.

email: Required. The contact's email.
name: Optional.
details: Optional. Up to 20 name and value pairs, like plan or last order.

curl https://chatloom.co/api/v1/bots/bot_8f2k1q/contacts \
  -H "Authorization: Bearer $CHATLOOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "name": "Sara Khan", "details": {"Plan": "Pro"}}'

{
  "data": [
    { "email": "[email protected]", "name": "Sara Khan", "details": { "Plan": "Pro", "Last order": "#1042 (shipped)" } }
  ]
}

Errors and limits

Errors come back with a status code and a message: { "error": "…" }

400: Something in the request isn't right. The message says what.
401: The key is missing, wrong or revoked.
403: The workspace isn't on the Pro plan or has used this month's message credits, the key is read-only (for sending messages or adding contacts), or the key can't use this chatbot.
404: The chatbot or chat doesn't exist, belongs to another workspace, or (for conversation_id) was started for a different visitor_id.
429: Too many requests: up to 120 a minute per key.
503: The chatbot couldn't answer just now. Try again shortly.