本页提供接入结构和实施原则，不写死可能变化的接口地址或字段。正式开发时请以 Potato 当前官方 Bot API 手册为准。
API 概述
Bot API 是面向机器人开发者的 HTTPS 接口。你的服务器接收用户交互，执行业务逻辑，再通过 API 向私聊、群组或频道返回内容。
- 适合通知、客服、查询和自动化工具
- 支持消息、命令、按钮和内联交互
- 机器人凭证应只保存在受控服务端
- 用户必须先发起会话或添加机器人
接入准备
1. 创建机器人
按 Potato 当前机器人创建流程设置名称、用户名和简介，并获取授权令牌。
2. 准备 HTTPS 服务
部署稳定的服务端，用于接收更新、校验参数、执行任务并发送响应。开发、测试和生产环境应隔离。
3. 管理配置
令牌、回调密钥和环境参数通过密钥管理或环境配置注入，禁止提交到代码仓库。
// 概念示例：实际字段和方法以官方文档为准 const update = verifyIncomingRequest(request) const command = parseCommand(update.message) const result = await runBusinessLogic(command) await potatoBot.sendMessage(update.chatId, result)
处理更新
将每个更新视为可能重复、延迟或乱序到达的事件。使用更新标识去重，为耗时任务设置队列，并在超时后安全重试。
- 先验证来源、格式和必要字段。
- 快速确认请求，把耗时操作交给后台任务。
- 记录事件标识、结果和错误，但避免记录敏感正文。
- 对同一用户、群组和接口设置合理限流。
常用能力
| 能力 | 典型用途 | 实施要点 |
|---|---|---|
发送消息 | 通知、回复、结果输出 | 处理格式、长度和发送失败 |
命令 | /start、/help 与业务指令 | 参数校验与权限检查 |
回调按钮 | 设置、翻页、确认操作 | 避免重复提交并及时响应 |
内联查询 | 跨会话搜索并发送内容 | 快速返回、缓存与结果分页 |
群组事件 | 成员、权限和服务消息 | 遵守群组隐私模式 |
错误与重试
区分参数错误、权限错误、限流、临时网络故障和服务端错误。只对可恢复问题采用带抖动的指数退避，并设置最大次数。
不要无限重试：无法送达、权限被撤销或参数无效时应停止任务并记录可诊断信息。
安全要求
- 令牌泄露后立即轮换，并排查异常调用。
- 对管理命令、付款或高风险动作进行二次鉴权。
- 仅保存完成服务所需的数据，并制定删除周期。
- 对用户输入、URL、文件和富文本进行验证与过滤。
- 为接口启用 HTTPS、限流、日志告警和可用性监控。