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 文檔在官網有詳細參數說明，遇到問題也可以到官方社群提問。