How a bot works

Read this once and the Bots API reference will make sense.

A bot has two sides

The draft is what you are editing. Published versions are what your visitors talk to.

They are separate. Writing the draft changes nothing for a visitor. Publishing copies the draft over and files the result as a version, and the history of versions is append-only.

edit the draft  ──▶  PUT /bots/{id}/test   ──▶  try it yourself
                └─▶  POST /bots/{id}/versions ──▶  visitors get it

Publishing is creating a version. There is no separate publish call.

A diagram is yours

The draft holds a diagram: blocks and the connections between them. It travels through the API all but unchanged — keys we do not model, like notes, come back as you wrote them, and so do your bricks. The one thing we add is isTarget: true, on any node other than the start point, a note or a global_keywords block that does not already say whether a connection may end at it.

{
  "nodes": {
    "hidden": {"id": "hidden", "path": "hidden", "template": "hidden", "params": {}},
    "welcome": {"id": "welcome", "path": "welcome", "template": "var_text",
                "params": {"version": 3, "text": "Hi! What is your name?", "destination": "name"}}
  },
  "connections": {
    "hidden.success--welcome": {"id": "hidden.success--welcome", "type": "success",
                                "sourcePath": "hidden", "targetPath": "welcome"}
  }
}

A node names its block by template, the storage name. The semantic name GET /blocks lists — ask_question for the one above — is what the block-level operations address a block by.

Two ids matter. hidden is the start point, and welcome is the greeting slot — the first thing a visitor is answered with. On every channel family but landbot the greeting slot is called bot_start.

A connection's type is the output it leaves from. Outputs are not uniform: some carry a $ prefix and some do not. GET /blocks tells you which, per block.

A brick is a diagram inside a block

A brick block runs a diagram of its own, which the document keeps in bricks under the block's id. It starts at its block with the id brick_start, and its outputs node lists the ways out: a connection inside it that points at outputs.$0 leaves the brick by its output $0. A brick is also left by default, when the output it ends at has no connection of its own.

"bricks": {
  "B0": {
    "id": "B0", "path": "B0", "name": "Ask for the email",
    "nodes": {
      "brick_start": {"id": "brick_start", "path": "brick_start", "template": "var_email",
                      "params": {"text": "Your email?", "destination": "email"}},
      "outputs": {"id": "outputs", "path": "outputs", "type": "chain", "template": "brick_outputs",
                  "params": {"outputs": [{"id": "$0", "alias": "Done"}]}}
    },
    "connections": {
      "brick_start.$success--outputs.$0": {"id": "brick_start.$success--outputs.$0", "type": "$success",
                                           "sourcePath": "brick_start", "targetPath": "outputs.$0"}
    }
  }
}

The blocks inside a brick are held to the same rules as the rest, and one breaking them is named by its trail: B0->brick_start. The block-level operations write a brick whole, with what it holds under brick: its blocks, named as GET /blocks names them, the outputs it declares and the connections between them. They never address a block inside a brick on its own.

Saving never loses work

A write to the draft stores what you sent even when it breaks the rules. You get back save_state and a list of violations, and you can keep editing.

The rules are only enforced when the bot has to run: PUT /bots/{id}/test and POST /bots/{id}/versions both refuse while any violation stands.

A handful of problems are refused on the spot instead, because there would be nothing sensible to store — a block of a type we do not know, an id already taken. When a call fails lists which.

What answers look like

  • One thing comes back under data.
  • A list comes back under data, with meta carrying total, page and page_size.
  • A field with no value is left out rather than sent as null. Two answers are the exception and keep their nulls: the draft, and a single version — both carry a stored diagram, and dropping empty values would reach inside it.

Identifiers: a bot, a version and a channel are uuids. A workspace and a person are integers. A block is identified by its id inside the diagram, which is any string the diagram gave it.

Timestamps are UTC, written 2026-09-16T09:18:19. No offset and no fractions of a second — if you parse them as local time you will be out by your own offset.

Bots built by an older builder

Some bots were made by a builder that came before this API. You can read them, and you can move them in and out of the trash. Every other write answers 422. They have to be migrated first.

What this API does not do

It does not run conversations. There is no endpoint that accepts or returns what a visitor sees mid chat. You describe a bot here; the runtime is elsewhere.

Where a bot is reached — its web page, its design, its CSS — belongs to the Channels API.