Bot API

Who this is for: developers with a Forge token (bzbot_…) who want to receive updates and reply as their bot.

Console: developers.buzzio.dev · Product: Bots · Workers: Worker bots

This API copies Telegram’s developer experience (token, methods, { ok, result }), not Telegram’s whole product. There is no Buzzio file CDN, no sealed-chat access, and no acting as a person.

Quick start

1. In the app: @forge_bot → /newbot → Service → copy bzbot_… once.
2. On desktop: paste the token on developers.buzzio.dev.
3. Terminal: getMe → leave getUpdates running → click Test /start on the site → sendMessage a welcome.
4. Submit when Test passes. Approved + active plan → real users can Start.

Seed / 12-word phrase never goes on the website. The token is the bot login.

What you can do

You cannot: read sealed 1:1 chats, Whisper private chat, Whisper Questions, or E2E groups; upload bytes for Buzzio to host; or use a service token as a worker (and the reverse).

Base URL and auth

Host: https://developers.buzzio.dev

Telegram-style (primary):

https://developers.buzzio.dev/bot<token>/<method>

Example: https://developers.buzzio.dev/botbzbot_…/getMe

Also accepted (Bearer):

POST https://developers.buzzio.dev/v1/sendMessage
Authorization: Bearer <token>
Content-Type: application/json

Same pattern for /v1/getMe, /v1/getUpdates, and other methods.

Do not put the token in a ?token= query string (access logs). Path or Bearer only.

How to call

HTTPS. UTF-8. GET or POST.

Parameters from, in order (later wins):

1. URL query string
2. application/x-www-form-urlencoded
3. application/json

Reject multipart/form-data file uploads. Outgoing media is an HTTPS URL you host, or a bzstk_… file_id from a set this bot registered. Incoming user media is a 7-day bzfile_…. Buzzio never GETs your URL (SSRF lock).

Success / error envelope

Success:

{ "ok": true, "result": { } }

Failure:

{ "ok": false, "error_code": 401, "description": "Unauthorized" }

Older /v1/sendMessage responses may also include "error": "…" alongside description for compatibility.

Two ways to receive updates

One at a time (same rule as Telegram):

                    ┌─ webhook URL set  → Buzzio POSTs Update to you
User taps Start  ───┤
                    └─ no webhook       → you poll getUpdates

If a webhook is set, getUpdates returns 409 (Conflict: can't use getUpdates while webhook is active).
deleteWebhook restores polling.

Pending polling updates: keep about 24 hours, then drop. Cap about 1000 per bot; drop oldest.

Website Test /start and a real user Start use the same Update shape. A terminal bot that answers Test will answer a real user.

Platform `/start`

Buzzio owns the Start button and the start event. You own the welcome text.

Do not invent a custom “type hi to begin” as the only entry — users learn one Start for every bot.

Available methods

The Bot API publishes 150 HTTP methods. Each one is documented individually — heading, “Use this method to…”, then a Parameter / Type / Required / Description table — on Bot API methods. That is the same layout as Telegram Bot API.

Console copy (searchable, one page): developers.buzzio.dev/docs/api/.

chat_id is always a string. Outgoing media is an HTTPS URL you host; Buzzio never GETs it. Incoming user media is a 7-day bzfile_…. Forum topic methods create and manage community channels (message_thread_id is the channel id).

Worker grants: Worker bots.

JSON types

Update

{
  "update_id": 17,
  "message": { }
}

update_id is a positive integer, sequential per bot (needed for offset).

Wave A also delivers callback_query when a user taps an inline button, and start_parameter on /start <payload> (also in message.text).

Wave F delivers chat_join_request when someone asks to join a room that requires approval:

{
  "chat_join_request": {
    "chat": { "id": "ohg:…", "type": "group", "title": "Mods" },
    "from": { "id": "ghost_…", "is_bot": false, "first_name": "User" },
    "date": 1710000000,
    "invite_link": { "invite_link": "https://links.buzzio.dev/join?g=…&t=…" }
  }
}

User

{
  "id": "ghost_a1b2c3",
  "is_bot": false,
  "first_name": "User"
}

You do not receive the person’s Buzzio username or avatar. id is enough to talk in this chat. first_name may be generic "User". Forge analytics stay counts-only.

Chat

{
  "id": "botdm_<botId>_<ghostId>",
  "type": "private"
}

Service-bot v1: type is always "private".

Message

{
  "message_id": "msg_…",
  "from": { "id": "ghost_…", "is_bot": false, "first_name": "User" },
  "chat": { "id": "botdm_…", "type": "private" },
  "date": 1710000000,
  "text": "/start",
  "chat_id": "botdm_…",
  "command": "start"
}

Unix date is seconds.

Webhook POST (Buzzio → you)

When a webhook is set, Buzzio POSTs one Update (same JSON as getUpdates items):

POST https://your-server/webhook
Content-Type: application/json
X-Buzzio-Timestamp: …
X-Buzzio-Bot-Id: …
X-Buzzio-Signature: sha256=…

Verify the signature before trusting the body. Return HTTP 2xx quickly, then call sendMessage asynchronously if needed.

Probe payloads from the console may include "probe": true — ignore for real chats.

Terminal walkthrough

# 1. Token from Forge /newbot (vanishes after 5 minutes)

# 2. Who am I?
curl.exe -sS https://developers.buzzio.dev/botbzbot_TOKEN/getMe

# 3. Wait for messages (leave running)
curl.exe -sS "https://developers.buzzio.dev/botbzbot_TOKEN/getUpdates?timeout=20"

# 4. After an Update arrives:
curl.exe -sS -X POST https://developers.buzzio.dev/botbzbot_TOKEN/sendMessage `
  -H "Content-Type: application/json" `
  -d "{\"chat_id\":\"botdm_…\",\"text\":\"Hi, I am Weather Bot.\"}"

Loop in a script: offset = last update_id + 1 so you do not see the same Update twice.

Test without a public server: start the poll loop first, then click Test on the website. Buzzio queues /start; your script sendMessages the welcome; Test passes; you can Submit.

Always-on later: setWebhook with your HTTPS URL, stop polling.

What stays on the website / Forge

setWebhook on the API is allowed. Console save-webhook is the same field.

Limits

Shadow-ban / suspend: webhook paused; sendMessage 403; getUpdates empty or 403.

Abuse and quotas are keyed by owner Buzzio ID and by bot. Ban the person → their bots go offline.

Telegram mapping

Intentionally not here

Worker room grants: Worker bots. Full method tables: Bot API methods.

Related

• Developer overview
• Bot API methods (all 150, individually)
• Worker bots
• Bots (product)
• Legal and policies