Telegram Bot 連携

独自の Telegram Bot を Multica エージェントに接続し、DM、グループ、forum topic、/issue で利用します。

Multica は Telegram 公式の @BotFather で作成した Bot を使用します。1 つの Bot は 1 つの Multica エージェントに対応します。

Telegram 連携はコミュニティメンテナンスです。毎リリースに同梱されますが、公式のサポート SLA は付きません。問題があれば GitHub issues に報告してください。

準備

接続できるのはワークスペースの owner または admin です。
API サーバーから https://api.telegram.org に接続できる必要があります。
@BotFather が発行した Bot token が必要です。パスワードと同様に扱ってください。

1. Bot を作成する

@BotFather を開き、/newbot を送信します。
表示名と、bot で終わる username を設定します。
HTTP API token をコピーします。
既定では Group Privacy を有効のままにします。これが可視範囲を最小にする構成で、Telegram はコマンド、明示的な @mention、Bot への返信だけを Bot に配信します。無効化は任意です。無効にすると Bot は周囲のグループ会話をコンテキストとして扱えるようになりますが、その代わりグループの全メッセージを受信します。詳細は「グループ」の項を参照してください。

token を issue、チャット、ログ、リポジトリに記録しないでください。漏えいした場合は @BotFather で失効させ、新しい token で再接続します。

2. エージェントに接続する

Multica の Agents で対象エージェントを開き、Integrations を選びます。
Connect Telegram をクリックします。
Bot token を貼り付け、Connect をクリックします。

Multica は Telegram で Bot を検証し、long polling と競合する webhook がないことを確認して token を暗号化保存し、監視された getUpdates 接続を開始します。他のエージェントやワークスペースに接続済みの Bot は、先に元の接続を解除してください。

初回利用とアカウント連携

メンバーが初めて Bot にメッセージを送ると、1 回だけ使える Multica アカウント連携リンクが届きます。同じワークスペースの Multica アカウントでサインインし、Telegram に戻ってメッセージを再送してください。リンクは 15 分で期限切れになります。

グループには bearer link を公開しません。Bot は送信者に、先に DM を開始するよう案内します。利用できるのは現在のワークスペースメンバーだけです。

Bot を使う

DM: @mention なしでテキストを送信します。
グループ: Bot を追加し、@mention するか Bot のメッセージに直接返信します。受理されたメッセージは継続中の Multica 会話に残ります。Bot 宛てでないグループメッセージは、それ自体で会話やターンを開始することはありません。ただし小さなメモリ上のバッファに保持されます。グループ（または forum topic）ごとに Bot が受信した直近 10 件で、サーバーの再起動で消えます。その後メンバーが @mention または Bot のメッセージへの返信で Bot に指示すると、バッファ内のメッセージが読み取り専用のコンテキストとしてそのターンの前に添えられ、ターンと一緒に会話として保存されます。バッファ内の画像やファイルは、コンテキストでは [Image] のようなマーカーと caption だけで示され、ファイル自体は取得されません。/new で始めた新しい会話にはこのコンテキストは付きません。バッファに入る内容は Telegram が何を配信するかで決まります。Group Privacy が有効ならコマンド、明示的な @mention、Bot への返信だけなので、コンテキストには以前 Bot 宛てだったメッセージだけが入ります。通常の会話も含めたい場合は @BotFather で Group Privacy を無効にし、Bot をグループから外して再追加してください。以後 Bot はグループの全メッセージを受信します。グループ管理者になっている Bot はプライバシー設定に関係なく全メッセージを受信するため、@BotFather を変更しなくても通常の会話がコンテキストに含まれます。他のメンバーのメッセージへ返信する場合は Bot も明示的に @mention してください。その場合に限り、引用元の送信者とテキスト（または caption）が新しい指示の文脈に含まれます。Bot 宛ての返信が引用するメッセージに画像やファイルが含まれていれば、送信者が誰であれそのファイルも一緒に添付されます。@mention なしの人への返信は Bot を起動しません。forum topic は topic ごとにセッションが分離されます。
/new / /new <message>: 空の新しい Multica Chat を作成し、その Telegram 会話の後続メッセージを新しい Chat にルーティングします。メッセージを付けた場合は新しい Chat の最初のターンになります。他のメンバーへの返信で Bot を明示的に @mention した場合、選択した引用内容も最初のターンに含まれます。
/clear / /clear <message>: 現在の Multica Chat を維持したまま、次の空でないメッセージに新しいエージェント可視コンテキストを適用します。メッセージを付けた場合は境界後の最初のターンになり、明示的に選択した返信の引用も保持されます。
/issue <title>: Multica issue を作成します。2 行目以降は任意の説明です。/issue@your_bot 形式も利用できます。

Bot は Telegram メッセージを送信・編集してテキストをストリーミング表示し、元メッセージを引用して forum topic を維持します。長い返信は自動分割されます。最終返信はプロセス内で非同期に配信されます。通常、あるチャットのバックオフ待機は worker を占有しません。キャッシュが上限に達してバックオフ状態が圧縮されると、同じ Bot installation の他のチャットも安全側に遅延する場合があります。終端キューの容量は固定で、上限超過は明示的に拒否されてエラーとして記録されます。キューはサービス再起動後に復元されません。

画像、ファイル、動画、音声メッセージは、キャプションをメッセージ本文として、同じ会話の添付ファイルとしてエージェントに届きます。これらを含むメッセージに返信すると（DM でも、グループで Bot に指示する場合でも、送信者が誰でも）、そのメッセージが引用として指示の前に添えられ、ファイルもエージェントに渡されます。以前の画像や動画を指し示したいときに使えます。Telegram の Bot がダウンロードできるのは 20 MB までで、取得できなかった場合（大きすぎる、またはダウンロード失敗）は Bot がその旨を伝え、エージェントにはプレースホルダーだけが見えます。エージェントが生成したファイルは返信の後に別メッセージとして送り返されます。10 MB までの画像はインライン表示、それ以外は 50 MB までファイルとして届きます。送達を確認できなかった場合は Bot がその旨を伝え、ファイルは Multica の返信に添付されたまま残ります。どちらの方向もサーバー側にオブジェクトストレージが必要です。未設定の場合、Bot はメディアに非対応通知を返し、エージェントにはファイルを送れない旨が伝えられます。sticker、位置情報、投票などファイル以外のメッセージは、DM または Bot 宛てのグループメッセージで同じ通知を返します。

管理とセルフホスティング

設定 → メッセージング → Telegram で接続済み Bot を確認できます。owner と admin は接続を解除できます。会話と監査履歴は保持されます。

セルフホスト環境では、API 起動前に固定の 32-byte 暗号鍵を設定します。

MULTICA_TELEGRAM_SECRET_KEY=<base64-encoded 32-byte key>

openssl rand -base64 32 で生成できます。連携リンクは MULTICA_APP_URL（未設定時は FRONTEND_ORIGIN）を使用します。サーバーから api.telegram.org への HTTPS 接続も必要で、標準の HTTPS_PROXY / NO_PROXY を利用できます。

トラブルシューティング

Bot を検証できない: まずサーバーのネットワークと proxy を確認します。Telegram が token を拒否した場合だけ再発行します。
webhook conflict: 接続前に既存 webhook を削除します。
409 polling conflict: 同じ Bot を polling している別プロセスを停止するか、環境ごとに Bot を分けます。
グループで返信しない: Bot が参加していて、@mention または Bot への返信になっていることを確認します。
連携リンクが期限切れ: Bot に新しい DM を送り、最新リンクを使用します。
実行されない: エージェントの archive 状態とランタイムを確認します。

準備