Potato Bot API 入門：チームとクリエイターのための自動化実践ガイド

コミュニティを運営したり、プロジェクトの進捗を管理したり、購読者に定期的にコンテンツを配信したりする場合、手作業は時間と労力がかかります。Potato が提供する Bot API を使えば、こうした繰り返し作業をボットに任せ、チームはより価値のある業務に集中できます。この記事では実際のシナリオを通して基本的な使い方を紹介します。

Bot API でできること：3つの典型的なシナリオ

ボットは自動返信だけではありません。以下はチームやクリエイターによく使われる方法です：

• 定時配信とリマインダー：例えば毎週月曜日の朝9時にプロジェクトグループへ ToDo リストを送信したり、コース開始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 で、2つのパラメータが必要です：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 の2つの方法があります。ポーリングはローカルテストに、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件までです。超過すると API は 429 エラーを返すので、retry_after 秒待ってから再試行する必要があります。一括配信時はユーザーを小グループに分け、各グループを1秒間隔で送信すると制限を回避できます。

また、ボットはグループ内の過去のメッセージを読むことはできず、Webhook 設定後の新規メッセージのみ受信できます。データを永続化する必要がある場合は、自分でデータベースを用意し、chat_id、ユーザー入力、タイムスタンプを保存してください。

クリエイターにとって非常に実用的な自動化の例：RSS フィードの新記事を Potato チャンネルへ自動転送する。定時スクリプトを書き、10分ごとにフィードをチェックし、新しいリンクを見つけたら sendMessage を呼び出します。コードは50行未満ですが、毎日手動でコピー＆ペーストする手間を省けます。

チームコラボレーションでは、簡単な当番ボットを作れます：メンバーが「/oncall」と送信してチェックインし、ボットが時刻を記録して応答時間を計算します。こうしたデータが蓄積されれば、シフト最適化に役立ちます。

まだ Potato のボット機能を試したことがないなら、最小限のニーズから始めてみましょう。例えば毎日定時に天気リマインダーを送るなど。インターフェースに慣れたら、徐々に拡張していきましょう。Potato の Bot API ドキュメントには公式サイトで詳細なパラメータ説明があり、問題があれば公式コミュニティで質問することもできます。