> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cowagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram

> Telegram Bot API 経由で CowAgent を接続

> 公式の Telegram Bot API を通じて CowAgent を接続します。1 対 1 チャットおよびグループチャット（@メンションまたはボットへの返信で起動）に対応。Long Polling 方式のため公開 IP は不要で、すぐに利用できます。

## 1. 接続手順

### ステップ 1: BotFather で Bot を作成

1. Telegram で公式アカウント [@BotFather](https://t.me/BotFather) を開きます。
2. `/newbot` を送り、案内に従って入力します:
   * **Bot 名**（表示名、例: `My CowAgent Bot`）
   * **Bot ユーザー名**（`bot` で終わる必要があります、例: `my_cowagent_bot`）
3. 作成完了後、BotFather から **HTTP API Token**（例: `123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ`）が返されます。大切に保管してください。

<Tip>
  Token は Bot のパスワードに相当します。漏えいしないよう注意してください。万が一漏れた場合は `@BotFather` に `/revoke` を送って再発行できます。
</Tip>

### ステップ 2:（グループ利用時）Privacy Mode を無効化

1 対 1 チャットのみ利用する場合はスキップ可能です。Telegram Bot は既定で **Privacy Mode** が有効で、グループ内では `@bot` 接尾辞付きのコマンド（例: `/start@your_bot`）と、Bot メッセージへの返信のみ受信できます。**通常の `@bot こんにちは` のようなテキストメッセージは届きません**。そのままだとグループで反応しないので、必要に応じて以下を設定してください。

`@BotFather` に対して:

1. `/setprivacy` を送信
2. 作成した Bot を選択
3. `Disable` を選択

<Note>
  設定後もグループで反応しない場合は、Bot を一度グループから外して再度追加してみてください。
</Note>

### ステップ 3: CowAgent に接続

<Tabs>
  <Tab title="Web コンソール（推奨）">
    Web コンソール（既定 `http://127.0.0.1:9899`）を開き、**チャネル** メニュー → **チャネルを追加** → **Telegram** を選択し、Bot Token を貼り付けて接続をクリックします。
  </Tab>

  <Tab title="設定ファイル">
    `config.json` に以下を追加して Cow を起動します:

    ```json theme={null}
    {
      "channel_type": "telegram",
      "telegram_token": "123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ",
      "telegram_group_trigger": "mention_or_reply"
    }
    ```

    | パラメータ                        | 説明                                                                            | 既定値                |
    | ---------------------------- | ----------------------------------------------------------------------------- | ------------------ |
    | `telegram_token`             | BotFather から発行された HTTP API Token                                              | -                  |
    | `telegram_group_trigger`     | グループのトリガー方式: `mention_or_reply`（@ または返信）/ `mention_only`（@ のみ）/ `all`（全メッセージ） | `mention_or_reply` |
    | `telegram_register_commands` | 起動時に BotFather にコマンドメニューを登録するかどうか                                             | `true`             |
  </Tab>
</Tabs>

ログに以下のような出力が表示されれば接続成功です:

```
[Telegram] Bot logged in as @my_cowagent_bot (id=123456789)
[Telegram] Registered 10 bot commands
[Telegram] ✅ Telegram bot ready, polling for updates
```

## 2. 機能

| 機能                        | 対応状況                         |
| ------------------------- | ---------------------------- |
| 1 対 1 チャット                | ✅                            |
| グループチャット（@bot / Bot への返信） | ✅                            |
| テキストメッセージ                 | ✅ 送受信                        |
| 画像メッセージ                   | ✅ 送受信                        |
| 音声メッセージ                   | ✅ 送受信（OGG/Opus）              |
| 動画メッセージ                   | ✅ 送受信                        |
| ファイルメッセージ                 | ✅ 送受信（PDF / Word / Excel など） |
| コマンドメニュー                  | ✅ Web コンソールの slash コマンドと一致   |

### コマンドメニュー

起動時に BotFather へコマンドメニューを自動登録します。Telegram の入力欄で `/` を入力するとサジェストが表示されます:

| コマンド         | 説明                                          |
| ------------ | ------------------------------------------- |
| `/help`      | コマンドヘルプを表示                                  |
| `/status`    | 実行ステータスを確認                                  |
| `/context`   | 対話コンテキストを表示（`/context clear` でクリア）          |
| `/skill`     | スキル管理（`/skill list`、`/skill install` など）    |
| `/memory`    | 記憶管理（`/memory dream`）                       |
| `/knowledge` | ナレッジベース管理（`/knowledge list` / `on` / `off`） |
| `/config`    | 現在の設定を表示                                    |
| `/cancel`    | 実行中の Agent タスクを中断                           |
| `/logs`      | 最近のログを表示                                    |
| `/version`   | バージョンを表示                                    |

<Note>
  Telegram のコマンドメニューはトップレベルのコマンドのみ表示されます。サブコマンドはスペース区切りで入力します（例: `/skill list`、`/context clear`）。
</Note>

## 3. 使い方

接続が完了したら:

* **1 対 1 チャット**: Telegram で Bot のユーザー名（例: `@my_cowagent_bot`）を検索し、`Start` をタップして会話を開始します。
* **グループチャット**: Bot をグループに追加し、`@bot こんにちは` または **Bot のメッセージに返信** することで起動します。グループで反応しない場合は [ステップ 2](#ステップ-2-グループ利用時-privacy-mode-を無効化) の Privacy Mode 設定を確認してください。

画像やファイルを送るときは、添付欄の上の入力欄に **キャプション**（説明・質問）を直接書いて一緒に送信できます。Bot は添付ファイルとキャプションを合わせて回答します。先に添付を送り、その後に質問を送る形でも、2 つのメッセージは自動でまとめて処理されます。