Bot Gateway (live plane)

Who this is for: developers with a Forge token who want live OHG / community / botdm events.

Canonical docs (copy-paste): developers.buzzio.dev/docs/gateway/ · Console: developers.buzzio.dev · Plan: BOT_GATEWAY_LONG_TERM_ARCHITECTURE_PLAN.md

Live vs REST

Buzzio does not clone Discord opcodes. Frames are JSON ops: hello, identify, heartbeat, resume, event.

Connect (copy-paste)

curl.exe -sS https://developers.buzzio.dev/v1/gateway
curl.exe -sS -H "Authorization: Bearer bzbot_…" https://developers.buzzio.dev/v1/gateway
curl.exe -sS https://developers.buzzio.dev/botbzbot_TOKEN/getGateway

1. Open the returned url as WebSocket; wait for hello.
2. Send identify with token + intents (privacy and/or privileged).
3. Heartbeat every heartbeat_interval_ms (default 41250).
4. On disconnect, resume with session_id + last_bot_seq when possible.

Quickstarts on the bot site repo: examples/gateway.mjs, examples/gateway.py.

Intents / privacy (honest)

Command / @ / menu events still include that action’s text. Do not claim “zero text.”

Privileged (premium)

1. Gateway Premium plan active
2. Per-bot privileged toggle on
3. OHG Read (or community view ACL)

Identify with privileged without entitlement → disconnect auth. Pricing: Base $0 / Premium $12 — BOT_GATEWAY_PRICING.md.

History

getChatHistory only (7d / max 100; 1/2s per chat; 30/min; 500/chat/day; 2000/bot/day). Overages → 429 / crawl_suspect. Not a live fallback. Privacy workers without premium → 403 for full room bodies.

Forbidden surfaces

Sealed 1:1 / Whisper / E2E / Encrypted Community — no Gateway.

Migration

Per-message Chat→HTTP tipKick fan-out is removed. Warm path is Gateway-only. Humans unaffected if Gateway is down; bots miss live until Resume/reconnect.