Guides

For AI agents

Machine-readable orientation for AI agents and code assistants ingesting these docs.

This page exists primarily for AI agents (Claude, ChatGPT, Cursor, custom RAG pipelines) that ingest the Landbot docs. If you're a human, you probably don't need to read it — but here's a quick orientation to what an agent reading this site has available:

  • llms.txt at the site root — index of every page in this docs site.
  • llms-full.txt at the site root — the entire docs corpus concatenated as Markdown for one-shot ingestion.
  • .md suffix on any content page URL — fetches the page as Markdown instead of rendered HTML. (OpenAPI-driven endpoint pages have no .md view — consume the openapi.json specs below for those.)
  • MCP server — a docs MCP at https://dev.landbot.io/mcp (HTTP / streamable transport, public — no token). Its tools let an agent search and read these docs directly.

On this deployment, <site> in the URLs throughout this page resolves to https://dev.landbot.io.

Connect the docs MCP 

claude mcp add --transport http landbot-docs https://dev.landbot.io/mcp

Or in an mcp.json / client config:

{ "mcpServers": { "landbot-docs": { "type": "http", "url": "https://dev.landbot.io/mcp" } } }

This site is a single-page app: unknown paths return 200 with an HTML shell, not a real 404. Before trusting a .json/.md response, confirm it starts with { or # rather than <!doctype html>.

The block below contains the same orientation, written for agents. It's hidden from the rendered HTML view of this page but is included in the .md view (/guides/for-ai-agents.md) and in llms-full.txt.

Landbot developer docs — agent orientation

Two HTTP APIs

API Base URL Auth header
Platform API https://api.landbot.io/v1/ Authorization: Token <agent_token>
APIchat https://chat.landbot.io/v1/ Authorization: Token <channel_token>

Both require Content-Type: application/json. There is no Bearer prefix. The literal word Token then a space then the token string.

Tokens are obtained from the dashboard:

The two tokens are not interchangeable. Use the agent token for api.landbot.io paths; use the channel token for chat.landbot.io paths.

Data model

Three resources, one implicit relationship.

  • Channel — a connection to a messaging surface (webchat, WhatsApp, Facebook, APIchat, …). Path prefix: /channels/. Each customer belongs to exactly one channel.
  • Customer — a person who has spoken to the bot through a channel. Path prefix: /customers/. Each customer has a channel_id.
  • Bot — a conversation flow built in the Landbot builder. A customer can be assigned to a bot via PUT /v1/customers/{customer_id}/assign_bot/{bot_id}/, or to an agent via assign/{agent_id}/.

A conversation is the implicit message stream between a customer and whoever is currently assigned. It is not addressable as a resource — all message endpoints address the customer.

Common operations (Platform API)

  • List channels: GET /v1/channels/
  • List customers (paginated): GET /v1/customers/ — query params offset (default 0), limit (default 20, max 100), plus optional filters channel_id, agent_id, archived, opt_in, search_by (name|email|phone), search.
  • Send text to customer: POST /v1/customers/{customer_id}/send_text/ body {"message": "..."}.
  • Get conversation transcript: GET /v1/customers/{customer_id}/messages/ → {"success": true, "messages": [...]}. The full chat history (no pagination, no guaranteed order — sort by message_datetime for chronological). Each message's fields depend on its type (text, button, dialog, image, event, multi_question, structured_data, … — open-ended). sender is a display name (no role/type field); message_datetime is a "YYYY-MM-DD HH:MM:SS" string.
  • Send WhatsApp template: POST /v1/customers/{customer_id}/send_template/ body {"template_id": int, "template_language": "en", "template_params": {...}}.
  • Set custom field on customer: POST /v1/customers/{customer_id}/fields/{field_name}/ body {"type": "string|integer|float|boolean|date|datetime", "value": ..., "extra": {}}.
  • Register webhook: POST /v1/channels/{channel_id}/message_hooks/ body {"url": "...", "token": "optional shared secret", "name": "..."}.

Common operations (APIchat)

  • Push inbound message: POST /v1/send/{customer_token}/ body {"customer": {"name": "..."}, "message": {"type": "text|image|video|audio|document|location|multiple_images", ...}}.
  • Create customer: POST /v1/customers/ body has all-optional fields name, phone, email, postal_code, country, token.
  • Update customer: PUT /v1/customers/{customer_token}/.
  • Mark customer as read: POST /v1/customers/{customer_token}/read/.
  • Get agent: GET /v1/agents/{agent_id}/.

Pagination convention (Platform API only)

All listing endpoints use the same pattern:

  • Request: ?offset=<n>&limit=<n>, max limit=100.
  • Response: {"success": true, "total": <int>, "<resource_key>": [...]}.
  • Stop when offset + items_returned >= total, or when the returned list is empty.

Rate limiting

10 requests per second per token, both APIs. Exceeded → HTTP 429. No Retry-After header. Use exponential backoff with jitter. Throttling on the client side (8 rps target with 2 rps headroom) avoids hitting the cap.

Error shapes

  • Platform API errors: {"errors": {"<field>": ["message", ...]}} — per-field map.
  • APIchat errors: {"success": false, "error": "string"} — single message.

Retry-safe codes: 429, 5xx. Don't retry: 400, 401, 402, 403, 404, 405, 409, 413, 422. Conditional retry (state-dependent): 412.

There is no idempotency-key header. POST retries can duplicate; prefer PUT for state changes (most Platform API state endpoints are PUT).

SDKs

Two JavaScript SDKs run in the browser. They are not server-side libraries.

  • Widgets SDK — embed a Landbot widget in a website. Six formats: Landbot.Fullpage, Landbot.Popup, Landbot.Container, Landbot.Livechat, Landbot.Native, Landbot.ContainerPopup. Load via ES module:

    https://cdn.landbot.io/landbot-3/landbot-3.0.0.mjs

  • Core SDK — lower-level client (@landbot/core) for building fully custom chat UIs. See Core SDK overview, install, the message types reference, and a worked example.

The Widgets SDK communicates with the host page via customData (parent → bot, declarative or imperative) and window.<function>(...) calls (bot → parent). Hidden Fields (declared in the builder) capture URL query params on the bot URL into named bot Fields.

Resources for agents reading this site

  • https://<site>/llms.txt — page index.
  • https://<site>/llms-full.txt — full corpus as Markdown.
  • https://<site>/<content-page-path>.md — any content page as Markdown (OpenAPI endpoint pages excluded — use the specs below).
  • https://<site>/api-reference/platform/openapi.json — Platform API OpenAPI 3.1.0 spec.
  • https://<site>/api-reference/apichat-api/openapi.json — APIchat OpenAPI 3.1.0 spec.
  • https://<site>/mcp — Model Context Protocol endpoint (HTTP transport); tools include search-documentation.

Tasks an agent can perform with these docs alone

  • Authenticate against the right API given a host name.
  • Generate a working client (Platform or APIchat) from the OpenAPI specs.
  • Send a message, manage a customer, register a webhook, fill a custom field.
  • Embed a Landbot widget in an arbitrary HTML page and pass it context via customData or Hidden Fields.
  • Handle errors with appropriate retry classification.
Previous
Errors