Telegram Bot 連携
独自の Telegram Bot を Multica エージェントに接続し、DM、グループ、forum topic、/issue で利用します。
Multica は Telegram 公式の @BotFather で作成した Bot を使用します。1 つの Bot は 1 つの Multica エージェントに対応します。Telegram 上で別々の Bot として振る舞わせたいエージェントには、それぞれ Bot を作成してください。
Telegram 連携はコミュニティメンテナンスです。毎リリースに同梱されますが、公式のサポート SLA は付きません。問題があれば GitHub issues に報告してください。
準備
- 接続できるのはワークスペースの owner または admin です。
- API サーバーから
https://api.telegram.orgに接続できる必要があります。 - @BotFather が発行した Bot token が必要です。パスワードと同様に扱ってください。
Bot を接続する
Bot を作成する
- @BotFather を開き、
/newbotを送信します。 - 表示名と、
botで終わる username を設定します。 - HTTP API token をコピーします。
- 既定では Group Privacy を有効のままにします。これが可視範囲を最小にする構成で、Telegram はコマンド、明示的な @メンション、Bot への返信だけを Bot に配信します。無効にすると Bot は周囲のグループ会話をコンテキストとして扱えるようになりますが、その代わりグループの全メッセージを受信します。詳しくはGroup Privacy で Bot に届くメッセージが決まるを参照してください。
token をタスク、チャット、ログ、リポジトリに記録しないでください。漏えいした場合は @BotFather で失効させ、新しい token で再接続します。
エージェントに接続する
- Multica の エージェントで対象エージェントを開き、メッセージングを選びます。
- メッセージチャネルを追加をクリックし、Telegramを選びます。
- Bot token を貼り付け、接続をクリックします。
Multica は Telegram で Bot を検証し、long polling と競合する webhook がないことを確認して token を暗号化保存し、監視された getUpdates 接続を開始します。他のエージェントやワークスペースに接続済みの Bot は、先に元の接続を解除してください。
初回利用
メンバーが初めて Bot にメッセージを送ると、1 回だけ使える Multica アカウント連携リンクが届きます。同じワークスペースの Multica アカウントでサインインし、Telegram に戻ってメッセージを再送してください。リンクは 15 分で期限切れになります。期限が切れたら、もう一度 Bot に DM を送ると新しいリンクが届きます。
グループには認証情報にあたる連携リンクを公開しません。Bot は送信者に、先に DM を開始するよう案内します。
利用できるのは現在のワークスペースメンバーだけです。メンバー資格はメッセージごとに再確認されます。
Telegram から仕事を依頼する
DM
Bot を開き、そのままテキストを送信します。@メンションは不要です。
グループと forum topic
Bot をグループに追加し、@メンションするか Bot のメッセージに直接返信します。受理されたメッセージは継続中の Multica 会話に残ります。通常のグループはそれぞれ 1 つの会話を継続し、forum topic は topic ごとに分離されます。
コマンド
/newは空の新しい Multica Chat を作成し、その Telegram 会話の後続メッセージを新しい Chat にルーティングします。/new <メッセージ>では、そのメッセージが新しい Chat の最初のターンになります。他のメンバーへの返信で Bot を明示的に @メンションした場合、選択した引用内容も最初のターンに含まれます。/clearは現在の Multica Chat を維持したまま、次の空でないメッセージに新しいエージェント可視コンテキストを適用します。/clear <メッセージ>では、そのメッセージが境界後の最初のターンになり、明示的に選択した返信の引用も保持されます。/issue <タイトル>は Multica のタスクを作成します。2 行目以降は任意の説明です。タイトルがない場合は使い方を返します。- グループでは
/issue@your_botのような Telegram のコマンドサフィックスも利用できます。
返信と対応する内容
Bot は Telegram メッセージを送信・編集してテキストをストリーミング表示し、元メッセージを引用して forum topic を維持します。長い返信は Telegram の文字数制限に合わせて自動分割されます。エージェントの作業中は、同じメッセージに現在のステップ(コマンドの実行、ファイルの読み取りなど)と経過時間も表示されます。DM では各ステップの対象まで、グループでは作業の種類だけを表示します。MULTICA_TELEGRAM_TOOL_PROGRESS(off、summary、detail)で変更できます。
画像、ファイル、動画、ボイス、音声メッセージは、キャプションをメッセージ本文として、同じ会話の添付ファイルとしてエージェントに届きます。エージェントが生成したファイルは返信の後にチャットへ送り返されます。どちらの方向もサーバー側にオブジェクトストレージが必要です(後述のセルフホスト設定を参照)。
接続を管理する
設定 → メッセージングには、接続済みエージェントがプラットフォーム別に表示されます。エージェントを選ぶと、その詳細ページのメッセージングが開きます。 ワークスペースの owner/admin は、そこで Bot の管理メニューから接続を解除できます。 解除すると long polling とその後の返信は止まりますが、Multica の会話と監査履歴は保持されます。
セルフホスト設定
API サーバーを起動する前に、長期間変えない 32 バイトの暗号鍵を設定します。
MULTICA_TELEGRAM_SECRET_KEY=<base64-encoded 32-byte key>openssl rand -base64 32 で生成できます。この鍵を紛失またはローテーションすると既存の Bot token を復号できなくなり、Bot ごとに再接続が必要です。
連携リンクは MULTICA_APP_URL(未設定時は FRONTEND_ORIGIN)を使用します。生成されるアドレスはメンバーがアクセスできる必要があります。サーバーのネットワークまたは proxy は api.telegram.org への HTTPS 接続を許可している必要があり、Go は標準の HTTPS_PROXY / NO_PROXY 環境変数を読み取ります。
よくある問題
- Bot を検証できない: まずサーバーのネットワークと proxy を確認します。Telegram が token を明示的に拒否した場合だけ再発行します。
- webhook conflict: 接続前にこの Bot の既存 webhook を削除します。Telegram では webhook と
getUpdatesを同時に使えません。 - 409 polling conflict: 別の Multica インスタンスやプロセスが同じ Bot を polling しています。そちらを停止するか、環境ごとに Bot を分けます。
- グループで返信しない: Bot がグループに参加していて、メッセージが @メンションまたは Bot への返信になっていることを確認します。
- 連携リンクが期限切れ: Bot に新しい DM を送り、最新リンクを使用します。
- 実行されない: エージェントがアーカイブされていないか、使用しているランタイムがオンラインかを確認します。