Choosing an API

Four surfaces — Platform API, APIchat, Widgets SDK, Core SDK. Pick the right one for the job before you write code.

Landbot exposes four developer surfaces. Most integrations only use one. Picking the right one first will save you re-architecting later.

At a glance

Surface	Runs in	Talks to	Auth	Token type
Platform API	Your server	Workspace control plane (customers, channels, hooks, messages out)	`api.landbot.io/v1/`	Agent token
APIchat	Your middleware (server)	A specific APIchat channel (push messages in from external platforms)	`chat.landbot.io/v1/`	Channel token
Widgets SDK	The end user's browser	A bot — drops a chat into a website	Public `configUrl`	None
Core SDK	The end user's browser	A bot — same engine the Widgets SDK uses, but you build the UI	Public `configUrl`	None

The first two are server-to-server APIs. The second two are browser SDKs that ride directly on a public bot config — no token, no proxy, runs entirely on the client.

Decide in one question each

Platform API — "Do I need to do something about customers from a server?"

Use it when your server needs to:

Send a message into an existing conversation (send_text, send_image, send_template, etc.)
List, search, or paginate customers
Read or write custom Fields on a customer
Assign or unassign a customer to/from an agent or bot
Archive, block, opt-out
Register webhooks to be notified about incoming messages

Don't use it when you want to show the bot to a user — that's the SDKs' job.

→ Platform API reference

APIchat — "Am I bridging Landbot to a messaging platform Landbot doesn't natively support?"

Use it when you're building a middleware that:

Receives messages from an external platform (Telegram, Slack, SMS, custom mobile app, IVR, …)
Pushes those messages into Landbot via POST /v1/send/{customer_token}/
Listens to Landbot's webhook for bot replies
Forwards bot replies back out to the external platform

APIchat is what lets you ship a Landbot-powered bot on a surface Landbot's UI doesn't natively render on. It's not a general-purpose admin API — for that, use the Platform API.

→ APIchat reference

Widgets SDK — "Do I want to embed Landbot in a website with minimal code?"

Use it when you want one of these six embed formats:

Fullpage — full-screen takeover
Popup — launcher bubble + popup chat
Container — embedded into a <div> of your choice
Livechat — launcher + expandable chat panel
Native — renders directly into the parent DOM (no iframe)
ContainerPopup — embed-into-container that opens as a popup

The SDK gives you a constructor (new Landbot.Popup({ configUrl: '...' })), parent-page communication via customData and window.fn() bridges, and lifecycle methods (open, close, setCustomData, destroy). You don't write UI code.

→ Widgets SDK overview

Core SDK — "Do I want to build my own UI on top of the bot?"

Use it when none of the Widgets formats fits — you're rendering chat into a Three.js scene, a terminal, a voice-only interface, a non-rectangular layout, a mobile-app webview with native gestures, anything custom.

You get:

A Core instance constructed from a configUrl
Subscriptions to three pipelines ($sequence, $readableSequence, $typingSequence) for delivering messages with different pacing
sendMessage for the user's side
An events bus for custom signals
Pagination methods for backlog scroll

You write the UI — every pixel.

→ Core SDK overview

Common combinations

Real integrations often blend two surfaces. The common pairings:

Widgets SDK + Platform API

The most common combination. Embed a widget in your marketing site, and on the server side use the Platform API to:

Send proactive messages to customers (re-engagement, follow-ups)
Sync collected Fields into your CRM
Listen for new-message webhooks and trigger workflows

Each side has its own auth: the widget uses a public configUrl (no token, ships in client code), the Platform API uses your agent token (server-only, never expose it).

Core SDK + Platform API

Same as above but with a custom-UI front end. The split is identical — public config URL on the client, agent token on the server.

APIchat + Platform API

Building a bridge to a non-native platform but you also want server-side automation? Both APIs work on the same workspace. APIchat handles the message flow on the bridged channel; the Platform API handles workspace-wide operations (customers across all channels, hooks, agent assignment). Different tokens, different hosts — see Authentication.

Widgets SDK alone

You're embedding a bot on a marketing site and don't need server-side workflows. Just the SDK, the bot's config URL, and a <script> tag.

Core SDK alone

You're building a one-off experimental UI — like the cinematic / departures / composer demos. Just the SDK, a config URL, and your own DOM.

What it looks like in the wrong tool

If you find yourself doing any of these, you're using the wrong surface:

Calling Platform API endpoints from a browser — the agent token gives full workspace access; never put it in client code. Either move the logic to a server, or rethink whether the operation belongs in the bot itself.
Building a chat UI on top of Platform API webhooks — webhooks are eventing, not chat. For a live two-way UI you need the Widgets or Core SDK on a configured bot/channel.
Using APIchat from a browser — APIchat assumes a server you control sits between the external platform and Landbot. The channel token can't be safely embedded in client code, same as the agent token.
Replicating Widgets SDK behaviour with Core just to embed a chat bubble — the Widgets SDK exists exactly for that. Reach for Core only when none of the six formats fit.