API
Webhook / long polling
setWebhook conflicts with getUpdates; delete webhook before local polling.
Auth: Authorization: Bearer sbot_…
POST
Bot Token/api/v1/bots/setWebhooksetWebhookConfigure Webhook
Configure webhook with Bot Token (alternative to the developer JWT endpoint). Sets `Bot.delivery_mode` to `webhook`.
- Required:
url(must be HTTPS) - Strongly required for delivery:
secret_token(without it, webhook delivery fails—platform cannot sign) - Optional:
allowed_updates[],allowed_ips[],max_connections(1..100, default 40),drop_pending_updates(default false) - Returns:
webhook(redacted),migrated_update_count,dropped_update_count - Side effect:
Bot.delivery_mode = webhook
POST
Bot Token/api/v1/bots/deleteWebhookdeleteWebhookDelete Webhook
移除当前 Webhook 配置，停止主动 POST 投递；机器人投递模式自动切到 `polling`，可改用 `getUpdates` 拉取。
- Optional：
drop_pending_updates(default false; when false, pending Updates move to the getUpdates queue) - Returns：
bot_id/delivery_mode = "polling"/migrated_update_count/dropped_update_count
POST
Bot Token/api/v1/bots/getUpdatesgetUpdatesgetUpdates Long Polling
在 `polling` 模式下拉取等待中的 Update。无公网 IP 也能起 bot；与 webhook 模式互斥（webhook 模式下调用该端点会返回 409）。
- Optional：
offset（拉取update_seq >= offset的条目；推荐用「上一批最后一条 update_seq + 1」做下次 offset，等价 ack） - Optional：
limit（1..100，默认 100） - Optional：
timeout（long-poll 秒数，0 立即Returns，最大 50；默认 0） - Optional:
allowed_updates[](e.g.["message","callback_query"], default = all) - Returns：
{ updates: [{ update_id, type, message?, callback_query?, update_seq }] } - 冲突：webhook 模式下调用 → 409
Conflict: can't use getUpdates method while webhook is active
GET
Bot Token/api/v1/bots/getWebhookInfogetWebhookInfoGet Webhook Info
返回当前 Webhook 配置摘要 + 平台出站 IP，方便客户在防火墙做白名单。
- Returns:
{ url, has_custom_certificate, pending_update_count, allowed_updates, allowed_ips, last_error_date, last_error_message, last_delivery_at, max_connections, delivery_mode, platform_egress_ips[] } platform_egress_ipsare platform egress IPs;delivery_modeiswebhookorpolling