快速开始

你需要准备什么

一台能登录 Fly App 的设备，用来和 BotFather 对话。
一台电脑，用于写代码和本地运行脚本。
任意一门后端语言；接口协议与请求格式保持语言无关。

步骤 1：创建 Bot

打开 Fly App，进入 BotFather 对话。
发送 /newbot。
按提示设置显示名和用户名。
保存返回的 bot_token。明文只展示一次。

安全提示

token 丢失后通常不能回查明文，只能轮换或重置。
不要把 token 放进群聊、截图、日志或代码仓库。

步骤 2：优先使用 Polling

如果你只是验证可行性，建议先用 Polling。它不需要公网 HTTPS，更适合本地开发。

推荐 API 基础地址：https://api.flycrytp.com

POST /api/v1/s/bot/updates
Authorization: Bearer <bot_token>
Content-Type: application/json

{
  "offset": 0,
  "limit": 50,
  "timeout": 30
}

offset 用来告诉服务端“我已经消费到哪里了”。
timeout 允许长轮询，减少空转请求。
如果你已经配置了 Webhook，这个接口可能返回空数组。

步骤 3：发送消息

POST /api/v1/s/bot/send
Authorization: Bearer <bot_token>
Content-Type: application/json

{
  "to_user_id": "au_xxx",
  "msg_type": "text",
  "data": {
    "content": "echo: hello"
  },
  "client_msg_id": "echo_10001"
}

client_msg_id 建议必填，用来做发送幂等。
私聊使用 to_user_id，群聊使用 group_id，二选一。
Update 里常见是 msgType，发送接口里常见是 msg_type，不要混淆大小写风格。
parse_mode=markdownv2 在设计上存在，但当前实现口径仍建议你直接提供 data.entities。

Python 示例

import os
import time
import requests

BASE_URL = os.getenv("FLY_BASE_URL", "https://api.flycrytp.com").rstrip("/")
TOKEN = os.getenv("FLY_BOT_TOKEN", "")
offset = 0

def bot_post(path, payload):
    return requests.post(
        BASE_URL + path,
        headers={"Authorization": f"Bearer {TOKEN}"},
        json=payload,
        timeout=35,
    )

while True:
    resp = bot_post("/api/v1/s/bot/updates", {"offset": offset, "limit": 50, "timeout": 30})
    updates = resp.json().get("data", {}).get("updates", [])

    for upd in updates:
        offset = max(offset, int(upd["update_id"]) + 1)
        if upd.get("type") != "message":
            continue

        message = upd["message"]
        text = ""
        if message.get("msgType") == "text":
            text = message.get("data", {}).get("content", "")

        bot_post("/api/v1/s/bot/send", {
            "to_user_id": message["from"]["openid"],
            "msg_type": "text",
            "data": {"content": f"echo: {text}"},
            "client_msg_id": f"echo_{upd['update_id']}"
        })

    time.sleep(0.2)

如果你准备把上面的示例单独保存运行，可以保存为 `hello_bot_polling.py` 后执行：

python hello_bot_polling.py

验证成功的标准

你能在 App 里给 Bot 发一条文本消息。
本地脚本能收到一条 message 类型的 Update。
Bot 能回复一条 echo: ... 的文本消息。
重复重启脚本后，不会因为错误的 offset 导致消息无限重放。
你知道下次请求应该优先使用 meta.polling.next_offset，而不是自己猜测。

切到 Webhook 前先确认

Webhook 需要公网 HTTPS 地址。
如果已启用 Webhook，Polling 通常会拿到空数组。
签名验证、重放和失败排查见协议页与排障页。

零代码路径

如果你的目标只是“给自己建一个 AI Bot”，并且当前环境已开通托管 AI，那么可以直接在 BotFather 按向导启用托管 AI，不必自己实现 Polling 或 Webhook。