Potato Bot API 入门：团队与创作者的自动化实践指南

如果你在运营一个社群、管理项目进度，或者需要定期向订阅者发送内容，手动操作往往费时费力。Potato 提供的 Bot API 能把这类重复工作交给机器人，让团队专注在更有价值的事情上。这篇文章用实际场景带你了解基础用法。

Bot API 能做什么：三个典型场景

机器人不是只能自动回复。下面这些用法在团队和创作者中很常见：

• 定时推送与提醒：比如每周一早上 9 点向项目群发送待办清单，或者课程开始前 30 分钟私信提醒学员。
• 数据查询与反馈：成员在群里输入“/status”，机器人返回当前任务完成率；创作者用“/stats”查看昨日新增订阅数。
• 内容分发与收集：机器人把新文章自动转发到多个频道，或者收集用户提交的链接、图片并整理成表格。

这些操作背后都是同一个逻辑：监听消息事件，调用 API 执行动作。Potato 的 Bot API 基于 HTTPS 请求，返回 JSON 数据，用任何语言都能对接。

从零开始：获取 Token 并发送第一条消息

首先在 Potato 内搜索 @BotFather，创建一个机器人，你会拿到一串 Token，比如 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11。这个 Token 相当于机器人的密码，不要泄露。

发送消息的接口是 https://api.potato.im/bot{token}/sendMessage，需要两个参数：chat_id（目标会话 ID）和 text（消息内容）。用 curl 测试一下：

curl -X POST https://api.potato.im/bot/sendMessage -d "chat_id=123456789&text=Hello"

如果返回 {"ok":true}，说明机器人已经成功发出消息。注意，机器人只能给主动与其对话过的用户或所在群组发消息，不能随意骚扰陌生人。

处理用户输入：用 Webhook 接收更新

要让机器人响应用户消息，有两种方式：轮询（getUpdates）或 Webhook。轮询适合本地测试，Webhook 适合线上服务。设置 Webhook 只需调用一次：

curl -X POST https://api.potato.im/bot/setWebhook -d "url=https://yourdomain.com/potato-webhook"

之后用户发给机器人的每条消息都会以 POST 请求推送到你的服务器。解析 JSON 里的 message.text 和 message.chat.id，就能决定回复什么。一个常见坑是：Webhook 必须使用 HTTPS，且证书有效，否则 Potato 会拒绝推送。

频率限制与实用建议

Potato 对机器人发消息有速率限制：单个机器人向同一会话每秒最多 1 条消息，全局每秒不超过 30 条。如果超出，接口会返回 429 错误，需要等待 retry_after 秒后重试。批量推送时建议把用户分成小组，每组间隔 1 秒，避免触发限制。

另外，机器人无法读取群里的历史消息，只能接收设置 Webhook 之后的新消息。如果需要持久化数据，自己准备数据库，把 chat_id、用户输入和时间戳存下来。

对于创作者，一个很实用的自动化是：把 RSS feed 的新文章自动转发到 Potato 频道。写一个定时脚本，每 10 分钟检查一次 feed，发现新链接就调用 sendMessage。整个过程不到 50 行代码，却能省去每天手动复制粘贴的麻烦。

团队协作方面，可以做一个简单的值班机器人：成员发送“/oncall”签到，机器人记录时间并计算响应时长。这些数据积累起来，能帮助优化排班。

如果你还没试过 Potato 的机器人功能，可以从一个最小需求开始，比如每天定时发送一条天气提醒。熟悉接口后，再逐步扩展。Potato 的 Bot API 文档在官网有详细参数说明，遇到问题也可以到官方社群提问。