Key concepts

The vocabulary used across these docs — bots, channels, customers, fields, code blocks — defined once and cross-referenced from everywhere else.

Read this once if Landbot is new to you. The same handful of terms show up across the Platform API, APIchat, Widgets SDK, and Core SDK docs, and they always mean the same thing — but they're easy to confuse the first time around (especially "Field" vs "customData" vs "Hidden Field", which are three names for largely the same primitive).

How the pieces fit

              ┌──────────────────────────────────────────────┐
              │              YOUR WORKSPACE                  │
              │                                              │
              │   ┌────────┐    ┌──────────┐                 │
              │   │  Bot   │───▶│ Channel  │◀── Webhook ──▶ Your server
              │   │ (flow) │    │ (e.g.    │                 │
              │   └────────┘    │ webchat) │                 │
              │                 └──────────┘                 │
              │                      │                       │
              │                      ▼                       │
              │                 ┌────────────────┐           │
              │                 │   Customer     │           │
              │                 │  ── Fields ──  │           │
              │                 │  email: …      │           │
              │                 │  utm_source: … │           │
              │                 └────────────────┘           │
              │                      │                       │
              │           assigned to │                      │
              │                      ▼                       │
              │                 ┌────────┐                   │
              │                 │ Agent  │ (you, a human)    │
              │                 └────────┘                   │
              └──────────────────────────────────────────────┘

A bot runs in one or more channels. Each conversation is between a customer and either the bot or an agent. Every customer has a bag of Fields that the bot can read and write. A webhook lets your server be notified when messages move through the channel.

Terms

Agent

A human team member in your workspace. Each agent has an agent token (Authentication) that grants the same access via the Platform API as their dashboard login. A customer can be assigned to an agent (PUT /customers/{id}/assign/) so that human gets the conversation instead of the bot. The agent identifier shows up on customer records as agent_id.

Agent token

The credential the Platform API uses. One per agent. Sent as Authorization: Token <agent_token> against api.landbot.io. Find yours at app.landbot.io/gui/settings/account. Distinct from the channel token.

Bot

A conversation flow you built in the Landbot builder — the visual blocks, branches, and Code blocks that decide what to ask and how to respond. Bots have an ID of the form H-XXXXXX-YYYYYYYYYYYYYYYYYY. A single bot can be exposed through multiple channels (webchat + WhatsApp + APIchat, say) — same flow, different surfaces.

In the Platform API, a customer can be assigned to a bot via PUT /customers/{id}/assign_bot/{bot_id}/.

Bot ID

The H-XXXXXX-YYYYYYY… identifier you'll see in URLs like chats.landbot.io/u/H-3440710-YQ702MGG35NCYIND/index.html and landbot.pro/v3/H-3440710-YQ702MGG35NCYIND/index.json. The Widgets and Core SDKs need the JSON form (the configuration URL); the Platform API doesn't reference bot IDs directly — it uses customer IDs.

Channel

A connection between Landbot and a messaging surface — webchat, whatsapi (WhatsApp), facebook, apichat, etc. Channels have an integer ID and a type. Every customer belongs to exactly one channel; that's how Landbot knows which surface to deliver messages on. Channels are managed via the Channels endpoints. Setting up a channel itself is a dashboard task — see the Help Center for WhatsApp and API Chat.

Channel token

The credential APIchat uses (not the Platform API). Distinct per APIchat channel — if you have three APIchat channels, you have three independent tokens. Sent as Authorization: Token <channel_token> against chat.landbot.io. Find it in the APIchat channel's settings panel. See Authentication.

Code block

A flow block that runs JavaScript inline in the conversation. In web channels, the code executes in the bot's render context (the iframe, in most widget formats). Inside a Code block, this is the widget instance — you can call this.setCustomData(...), read @{field} interpolations, and reach the parent page via window.fn(). See JavaScript execution.

Not available in WhatsApp or Messenger flows — those run server-side without a JS runtime.

Configuration URL (`configUrl`)

The JSON representation of a bot, fetched at:

https://chats.landbot.io/u/H-XXXXXX-YYYYYYY/index.json

or (newer hosting)

https://landbot.pro/v3/H-XXXXXX-YYYYYYY/index.json

Replace index.json with index.html to get the rendered hosted page. The Widgets and Core SDKs both take this URL — either by passing it to the constructor (new Landbot.Popup({ configUrl: '...' })) or by fetching the JSON manually and handing the parsed object to new Core(config).

Conversation

The message stream between a customer and whoever is currently assigned (bot or agent). Not a first-class API resource — there's no /conversations/ endpoint. Every message-related API endpoint addresses the customer, not the conversation. A customer who's been reassigned between bots and agents has had multiple "logical" conversations, but the API surfaces them as a single message history per customer.

`customData`

An object passed at widget construction (or set later via setCustomData(...)) that populates Fields on the customer. Same primitive as a Field, just a different on-ramp. See Setting variables.

Customer

A person who has spoken with the bot through one channel. Customers have:

An integer id (unique in your workspace).
A channel_id — exactly one channel per customer.
Optionally an agent_id if assigned to a human.
A bag of Fields (custom_fields in API responses).
Meta state: archived, unread, last_message, etc.

Customers are managed via the Customers endpoints.

Field (Landbot Field)

A typed variable stored on a customer. Field types: string, integer, float, boolean, date (ISO string), datetime (Unix timestamp).

Five ways to set a Field:

Inside the flow, with a Set-Variable block.
From a Code block, with this.setCustomData({...}).
From the parent page (Widgets SDK), with myLandbot.setCustomData({...}) or passing customData at construction.
From a URL query parameter (Hidden Field).
From the Platform API, with POST/PUT/DELETE /customers/{id}/fields/{name}/.

Read from the flow with @{field_name} interpolation in Send Message blocks; read from a Code block with the same syntax (literal substitution before the JS runs).

Hidden Fields

A declarative way to capture URL query parameters into named Fields. Declared in the bot's Settings → Hidden Fields panel. When a user lands on the bot URL with ?name=Jane&utm_source=newsletter, those values populate Fields named name and utm_source before the first flow block runs. See Setting variables → From URL query params.

Iframe-embedded widgets don't inherit the parent page's query params — that's the most common gotcha.

Message hook (Webhook)

A URL Landbot POSTs to when messages move through a channel. Registered via POST /channels/{channel_id}/message_hooks/ on the Platform API. The payload shape is documented at Webhook payload. Optionally signed with a shared token Landbot echoes in the Authorization header so your endpoint can verify the request.

Distinct from APIchat's webhook, which delivers from-bot messages to your middleware in a slightly different shape — see the APIchat webhook payload.

Question block (Ask a Question)

A flow block that pauses and waits for user input. Comes in flavours: text input, buttons (with optional payloads), buttons-multiple, rating, date, file upload, etc. Each Question block can save the answer to a Field by name. The most common building block when you need data from the user.

`samurai` field

The discriminator that distinguishes bot messages from user messages on the receive side. Bot messages carry samurai (usually a small negative integer identifying the bot or persona); user messages don't. See Messages → bot vs user messages.

Send Message block

A flow block where the bot says something — pre-written text (with @{field} interpolation), an image, a card, a media block. No pause for user input — execution flows straight through. The other half of the most common pair: Send Message → Question → Send Message → Question.

Webhook

See Message hook.

Quickstart

Choosing an API