# EMQXエージェントをTelegramに接続する

Telegramコネクターを使用すると、EMQXエージェントはTelegramボットを利用して、メッセージ、ファイル、位置情報、投票、チャット、メンバー、招待リンク、ボットコマンドの送信および管理が可能になります。アラート通知、ボットベースのワークフロー、運用通知に活用できます。

## よくあるユースケース

- デバイスのアラートをTelegramのグループまたはチャンネルに送信する。
- ワークフローで生成された画像、ファイル、位置情報を送信する。
- 最近のボットの更新やチャット履歴を取得する。
- 投票を作成したり、運用ワークフロー用のボットコマンドを設定する。

チャットでの例示的なプロンプト：

```text
operations-telegramコネクターを使用して、設定された運用チャットに重要なデバイスアラートを送信してください。デバイスID、タイムスタンプ、および推奨される対応を含めてください。
```

## 前提条件

コネクターを追加する前に以下を準備してください：

- Telegramボットとそのボットトークン。
- ボットが対象のチャット、グループ、またはチャンネルにアクセスできること。
- 招待リンクの作成やメッセージ管理などの操作に必要な管理者権限。

## Telegramコネクターの追加手順

1. 左側のナビゲーションメニューで **Connectors** をクリックします。
2. **Available** タブで **Telegram** を見つけて **Add** をクリックします。
3. 説明的なコネクター名を入力します。
4. **Confirm** をクリックすると、Telegram認証フローがダイアログで開きます。
5. **Bot Token** に接続したいTelegramボットのトークンを入力します。
6. ボットを作成する場合はTelegramで `@BotFather` にメッセージを送り、`/newbot` を送信してください。既存のボットの場合は `/token` を送信してトークンを取得します。
7. **Connect Account** をクリックします。
8. 成功メッセージを待ち、EMQXエージェントに戻ります。
9. **Added** タブでコネクターのステータスが **Authorized** になっていることを確認します。

<!-- TODO: ボットトークンのローテーション動作および書き込み操作に対する個別承認の要否を確認すること。 -->

## 対応ツール

### メッセージ送信

| ツール | アクセス | 説明 |
|---|---|---|
| `TELEGRAM_ANSWER_CALLBACK_QUERY` | 書き込み | インラインキーボードのコールバッククエリに応答します。 |
| `TELEGRAM_SEND_DOCUMENT` | 書き込み | チャットにファイルを送信します。 |
| `TELEGRAM_SEND_LOCATION` | 書き込み | チャットに位置情報を送信します。 |
| `TELEGRAM_SEND_MESSAGE` | 書き込み | チャットにテキストメッセージを送信します。 |
| `TELEGRAM_SEND_PHOTO` | 書き込み | チャットに画像を送信します。 |
| `TELEGRAM_SEND_POLL` | 書き込み | チャットに投票を送信します。 |

### メッセージ管理

| ツール | アクセス | 説明 |
|---|---|---|
| `TELEGRAM_DELETE_MESSAGE` | 破壊的 | メッセージを削除します。 |
| `TELEGRAM_EDIT_MESSAGE` | 書き込み | メッセージを編集します。 |
| `TELEGRAM_FORWARD_MESSAGE` | 書き込み | メッセージを別のチャットに転送します。 |

### ボットおよびチャット情報

| ツール | アクセス | 説明 |
|---|---|---|
| `TELEGRAM_GET_CHAT` | 読み取り | チャット情報を取得します。 |
| `TELEGRAM_GET_CHAT_ADMINISTRATORS` | 読み取り | チャットの管理者一覧を取得します。 |
| `TELEGRAM_GET_CHAT_HISTORY` | 読み取り | チャット履歴を取得します。 |
| `TELEGRAM_GET_CHAT_MEMBER` | 読み取り | チャットメンバーの情報を取得します。 |
| `TELEGRAM_GET_CHAT_MEMBERS_COUNT` | 読み取り | チャットメンバー数を取得します。 |
| `TELEGRAM_GET_ME` | 読み取り | 認可されたボットの情報を取得します。 |
| `TELEGRAM_GET_UPDATES` | 読み取り | ボットに送信された最近の更新を取得します。 |

### チャットおよびボット設定

| ツール | アクセス | 説明 |
|---|---|---|
| `TELEGRAM_CREATE_CHAT_INVITE_LINK` | 書き込み | チャットの招待リンクを作成します。 |
| `TELEGRAM_SET_MY_COMMANDS` | 書き込み | ボットのコマンドリストを設定します。 |

::: warning 重要なお知らせ
メッセージの送信、編集、削除、転送、招待リンク作成、ボットコマンドのツールはTelegramチャットを変更したりユーザーと通信します。書き込み操作の前にチャットIDと内容を必ず確認してください。
:::

## チャットでのコネクター利用方法

1. チャットの入力欄でコネクターアイコンをクリックします。
2. 認可済みの **Telegram** コネクターを選択します。
3. プロンプトでエージェントが使用すべき外部リソースと操作を指定します。
4. 生成されたエージェント定義を確認し、必要なツールのみが含まれていることを確認します。

## 権限とデータアクセス

コネクターは提供されたボットトークンで識別されるTelegramボットを通じて動作します。ボットのメンバーシップ、チャット管理者権限、Telegramのプライバシー設定、チャットタイプによりアクセス可能なメッセージや操作が決まります。

チャットプロンプトやエージェント指示に外部サービスの認証情報やアクセストークンを含めないでください。

## 制限事項

- Telegram Bot APIのレート制限およびファイルサイズ制限が適用されます。
- ボットは参加しているチャットのみアクセス可能で、Telegramボットのプライバシー設定で許可された更新のみ取得できます。
- 一部のメッセージ管理や招待リンク操作には管理者権限が必要です。

<!-- TODO: サービス固有の結果サイズ制限、ファイル制限、APIレート制限、プラン制限、非対応リソースタイプを確認すること。 -->

## トラブルシューティング

| 症状 | 対処方法 |
|---|---|
| コネクターが **Unauthorized** のまま変わらない。 | 認証を再試行し、**Bot Token** が対象のTelegramボットのものであることを確認してください。 |
| ツールが権限エラーを返す。 | 認可されたアカウントが対象リソースと操作にアクセスできるか確認してください。 |
| 必要なツールが利用できない。 | ツールがこのコネクターでサポートされているか、承認されているか確認し、チャットで再度コネクターを選択してください。 |
| リクエストが断続的に拒否される。 | 外部サービスのステータス、APIクォータ、レート制限、アカウントプランを確認してください。 |

## 関連リンク

- [Connectors](../connectors.md)
- [Start a Chat](../chats.md)
- [Manage Agents](../agents.md)