Junyan Chin
144bec371c
* docs(platform): add HTTP Bot adapter design (RFC)
Standalone server-to-server HTTP adapter for driving a pipeline from external
systems (LangBot Space ticketing et al). Inbound via the existing unified
webhook route; outbound via signed callback POSTs. Preserves pipeline-native
N->1 aggregation and 1->M multi-reply without a long-lived WebSocket.
No core changes required (router/aggregator/pipeline untouched).
* feat(platform): add standalone HTTP Bot adapter
A first-class, vendor-neutral message-platform adapter (http_bot) for
server-to-server integrations (LangBot Space ticketing et al). Drives a
pipeline over plain HTTP with no long-lived connection:
- Inbound: signed POST to the existing unified webhook route /bots/<uuid>,
carrying a caller-defined session_id mapped to the LangBot launcher id via
get_launcher_id -> per-session isolation. Preserves pipeline-native N->1
aggregation for free.
- Outbound: each reply_message / reply_message_chunk becomes one signed
callback POST to the config-only callback_url, delivered in per-session
sequence order with retry/backoff -> 1->M multi-reply.
- Sub-paths: /reset (drop a session) and /sync (block for the collapsed reply).
- Auth: symmetric HMAC-SHA256 both directions (timestamp + replay window),
no JWT/Turnstile, no socket.
Decisions: callback URL is config-only (SSRF closed); reset + sync shipped;
Python + TS reference clients shipped (signing verified byte-identical 3-way).
No core changes: the unified webhook router, aggregator, query pool and
pipeline are untouched. Adapter is auto-discovered from platform/sources/.
Adds:
src/langbot/pkg/platform/sources/http_bot.{py,yaml,svg}
src/langbot/pkg/platform/sources/http_bot_signing.py
docs/platforms/http-bot.md, docs/http-bot-openapi.json
examples/http-bot/{client.py,client.ts,README.md}
Updates docs/HTTP_BOT_ADAPTER_DESIGN.md (status: implemented).
* docs(examples): add interactive HTTP Bot playground (browser debug console)
A single-file aiohttp web app (examples/http-bot/playground.py) that lets you
chat with a RUNNING http_bot bot from the browser and watch the protocol live:
signed inbound POST -> 202 ack -> 1->M signed callbacks streamed back via SSE,
with a debug panel showing the signature, HTTP status, and per-callback
sequence/verification. Light LangBot-styled UI.
On startup it reads the API key + http_bot bot from data/langbot.db and points
the bot's callback_url + secrets back at itself via the LangBot API (live
reload, no restart). README updated with a playground section.
* docs(examples): add Chinese README for http-bot reference clients
* style(platform): use </> code icon for http_bot adapter logo
* docs(examples): point http-bot guide links to docs.langbot.app
* style(platform): make http_bot icon a transparent monochrome </> so WebUI tints it like other adapters
* Revert to colorful </> badge for http_bot icon (WebUI renders it as-is)
3.1 KiB
HTTP Bot Adapter — Reference Clients
English | 中文
Minimal, dependency-light clients for the LangBot HTTP Bot platform adapter. They show the whole loop: signing a request, pushing a message, and receiving multi-part replies on a callback endpoint.
Full guide: docs.langbot.app — HTTP Bot.
Machine-readable contract: docs/http-bot-openapi.json.
Files
| File | What it is |
|---|---|
playground.py |
Interactive browser debug console — a single-file web app you open in a browser to chat with a running http_bot bot and watch signing / 202 / callbacks live. Zero extra deps. |
client.py |
Python client + Flask callback receiver (pip install flask requests). |
client.ts |
TypeScript/Node 18+ client + callback receiver, zero deps (npx tsx client.ts). |
All three implement the identical HMAC-SHA256 scheme
(sha256=hex(HMAC(secret, "{timestamp}." + body))) — verified byte-for-byte
against the adapter.
Interactive playground (recommended first run)
A self-contained web console: type a message in your browser, it is signed and
POSTed to a running http_bot bot, and the bot's replies stream back into
the page — with a debug panel showing the signature, the 202 ack, and each
callback's sequence / signature-verification.
# From the LangBot repo root, with the backend already running:
PUBLIC_IP=<your-host-ip> ./.venv/bin/python examples/http-bot/playground.py
# then open http://<your-host-ip>:8920/
On startup it reads the LangBot API key + the http_bot bot from
data/langbot.db, and configures that bot (inbound/outbound secret +
callback_url) to point back at itself via the LangBot API — the bot reloads
live, no restart needed. Requirements: an enabled http_bot bot bound to a
working pipeline, and port 8920 reachable from your browser.
Env knobs: PUBLIC_IP (default 127.0.0.1), PLAYGROUND_PORT (default 8920).
Headless clients
# Python — Terminal 1: callback receiver (your callback_url target)
python client.py serve --port 8900 --secret SHARED_SECRET
# Python — Terminal 2: push a message
python client.py push --url https://your-langbot/bots/<BOT_UUID> \
--secret SHARED_SECRET --session ticket-1 --text "hello"
# blocking sync mode
python client.py sync --url https://your-langbot/bots/<BOT_UUID> \
--secret SHARED_SECRET --session ticket-1 --text "hello"
# reset a session
python client.py reset --url https://your-langbot/bots/<BOT_UUID> \
--secret SHARED_SECRET --session ticket-1
# TypeScript (Node 18+)
npx tsx client.ts serve 8900 SHARED_SECRET
npx tsx client.ts push https://your-langbot/bots/<BOT_UUID> SHARED_SECRET ticket-1 "hello"
When the bot replies, the receiver prints each part with its sequence and an
[FINAL] marker on the last one — that's the 1→M multi-reply model in action.
The bot's
callback_urlmust be reachable from LangBot. For local testing, expose your receiver with a tunnel (cloudflared / ngrok) and set that URL in the bot config.