MINARA
Minaraを使用するクライアントとインターフェースメッセージングプラットフォーム

Telegram

おすすめの出発点。3分でセットアップでき、ストリーミング対応のゲートウェイで、最も実績あるプロバイダーです。

🟢 ランタイム対応済み このゲートウェイはストリーミング編集機能を備えています（本番の呼び出し元はまだ未接続。詳細は下記を参照）。Minara オペレーターの多くが最初に使うプロバイダーです。外部バイナリ不要、ビジネスアカウント審査も不要。bot トークンとチャット ID があればすぐ始められます。

提供される機能

  • ストリーミング編集（ゲートウェイ対応済み） TelegramGateway がプレースホルダーを投稿し、テキストが届くたびに編集します。750 ms スロットリング済みです。apps/agent/src/messaging/stream-helpers.ts の createStreamSink 経由で駆動します。send_message ツール自体はワンショット送信です。
  • リッチテキスト（デフォルトで有効） Markdown の返信が Telegram の書式（太字、見出し、表、タスクリスト、コードブロック）でレンダリングされます。プレーンテキストにするには TELEGRAM_RICH_TEXT=false を設定します。
  • 添付ファイル 画像（sendPhoto）、ファイル（sendDocument）、ボイスメモ（sendVoice、OGG/Opus 必須）、音声（sendAudio）に対応しています。ソースはサンドボックス内で Agent が生成したファイルである必要があります（詳細は概要ページを参照）。
  • グループおよび 1:1 チャット どちらも同じフローで動作します。グループのチャット ID は負の数値です。
  • 1 メッセージあたり 4,096 文字制限 send_message はツール境界で長すぎるテキストを拒否します。ストリームシンクはストリーミング中に … (truncated) マーカーを付けて切り捨てます。

セットアップ

1. bot を作成する

  1. Telegram を開き、@BotFather を検索します。
  2. /newbot を送信し、プロンプトに従って名前とユーザー名を設定します。
  3. BotFather から受け取ったトークンを保存します（例: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11）。

2. チャット ID を取得する

  1. 新しい bot とチャットを開始し、任意のメッセージを送信します。チャット側から先に連絡しないと、bot からのメッセージが届きません。
  2. ブラウザで https://api.telegram.org/bot<TOKEN>/getUpdates にアクセスし、レスポンス内の "chat":{"id":...} を確認します。

グループの場合は、bot をグループに追加してメッセージを送信したあと、getUpdates を確認してください。グループ ID は負の値です（例: -1001234567890）。

3. Minara を設定する

簡単な方法 チャットで Agent に依頼します:

"set up Telegram notifications"

Minara がトークンとチャット ID を尋ね、~/.minara/credentials.json（messaging スロット）に書き込んでテスト ping を実行します。

手動の方法:

minara auth messaging add telegram

またはプロジェクトルートの .env ファイルに環境変数を直接設定します:

TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
TELEGRAM_CHAT_ID=-1001234567890

4. テストする

minara auth messaging test telegram

1〜2 秒以内に ping メッセージが届くことを確認してください。

ストリーミングの動作

Telegram の editMessageText エンドポイントは、レート制限に達することなく 1 メッセージあたり約 30 回の編集を受け付けます。TelegramGateway は startStream() セッションを公開し、プレースホルダーを投稿しながら新しいテキストが届くたびに編集します。createStreamSink はその編集を 750 ms スロットリングします。ライブ感を保ちつつ、チャットあたりの制限内に収まる設定です。累積テキストが 4,096 文字を超えると、ストリーミング途中で … (truncated) マーカーを付けて切り捨てられます。

スロットリングと文字数の上書きは createStreamSink(gw, msg, { intervalMs, maxLength }) の呼び出し元オプションであり、send_message の引数ではありません。ツールパス自体はワンショットです。LLM が完全に組み立てたメッセージを送信し、ストリーミングはワークフロー / Autopilot コードに存在します（本番ではまだ未接続）。

リッチテキスト

返信はデフォルトで Telegram のリッチテキストとしてレンダリングされます。Agent が Markdown を生成し、ゲートウェイが送信前に Telegram 対応の HTML サブセットへ変換します。

  • 見出しは太字になり、リストは箇条書きを保ち、タスクリストは ☐ / ☑ で表示され、表は等幅で整列され、コードブロックは言語ラベルを保持します。
  • Telegram が HTML を拒否した場合（まれ）、ゲートウェイは同じ内容を MarkdownV2 で再試行し、さらにプレーンテキストへフォールバックします。書式エラーでメッセージが失われることはありません。
  • ストリーミング中は各編集が閉じた書式のみを表示するため、確定前に途中の **bold が一瞬表示されることはありません。

オフにすると Agent のテキストをそのまま送信します。

TELEGRAM_RICH_TEXT=false

「オフ」として受け付ける値は 0、false、no、off です。未設定はオンを意味します。この設定は起動時に一度だけ読み込まれるため、変更後はゲートウェイを再起動してください。Web UI の 設定 → メッセージングの挙動 → Telegram のリッチテキスト でも切り替えられます。

添付ファイル

添付ファイルは、Agent がサンドボックス内で生成済みのファイル（image_generate、audio_generate、write_file、コード実行など）を参照します。LLM はサンドボックス相対パスを渡します:

send_message({
  provider: "telegram",
  text: "BTC/USD daily: key levels marked",
  attachments: [
    { kind: "image", sandbox_path: "images/btc-2026-04-19.png" },
  ],
})

kind のルーティング:

kindTelegram エンドポイント備考
imagesendPhotoキャプション対応
filesendDocument任意のファイル形式
voicesendVoiceOGG/Opus 必須。それ以外は拒否されます
audiosendAudiomp3 / m4a / flac。音楽スタイルのプレーヤー UI

複数の添付ファイルは連続したメッセージとして送信されます。最初のメッセージは、msg.text が十分に短い場合（1,024 文字以下）そのキャプションとして使用されます。それを超える場合は、テキストが先行メッセージとして送信され、添付ファイルがその後に続きます。詳細は apps/agent/src/messaging/telegram.ts を参照してください。

チャンネルの上書き

緊急アラートを別のチャットに送りつつ、通常の通知はデフォルトのまま維持できます:

send_message({
  provider: "telegram",
  channel: "-1009876543210",
  text: "Critical: position liquidation imminent",
})

トラブルシューティング

「テストメッセージが届かない」

  • bot に先にメッセージを送りましたか。チャット側から先に連絡しないと、Telegram はメッセージを届けません。
  • TELEGRAM_CHAT_ID の符号を確認してください。グループチャットは負の値です。
  • bot がまだグループにいるか確認してください。BotFather でお使いの bot を選び、Bot Settings → Group Privacy を確認します。

「ストリーミングが遅い / ちらつく」

  • TelegramGateway 内部の 750 ms ベースラインスロットリングは仕様です。呼び出し元コードで createStreamSink(gw, msg, { intervalMs: 500 }) を使って上書きできます。これは呼び出し元のオプションであり、send_message ツールの引数ではありません。
  • 非常に長いレスポンスは 4,096 文字で切り捨てられます。ワークフローを複数のメッセージに分割することを検討してください。

「Chat not found (400)」

  • bot がグループから削除されたか、チャット ID が間違っています。
  • 対象チャットで新しいメッセージを送信したあと、getUpdates の手順を再実行してください。

リファレンス

メッセージと通知

19種類のメッセージングプロバイダーの概要、選び方、設定方法、およびAgentからの使い方。

Discord

ボットトークンを使った単一チャンネル設定。ストリーミング対応ゲートウェイで、2,000 文字制限あり。コミュニティサーバーに適しています。

目次

提供される機能セットアップ1. bot を作成する2. チャット ID を取得する3. Minara を設定する4. テストするストリーミングの動作リッチテキスト添付ファイルチャンネルの上書きトラブルシューティングリファレンス