EMQXエージェントをTelegramに接続する
Telegramコネクターを使用すると、EMQXエージェントはTelegramボットを利用して、メッセージ、ファイル、位置情報、投票、チャット、メンバー、招待リンク、ボットコマンドの送信および管理が可能になります。アラート通知、ボットベースのワークフロー、運用通知に活用できます。
よくあるユースケース
- デバイスのアラートをTelegramのグループまたはチャンネルに送信する。
- ワークフローで生成された画像、ファイル、位置情報を送信する。
- 最近のボットの更新やチャット履歴を取得する。
- 投票を作成したり、運用ワークフロー用のボットコマンドを設定する。
チャットでの例示的なプロンプト：
text
operations-telegramコネクターを使用して、設定された運用チャットに重要なデバイスアラートを送信してください。デバイスID、タイムスタンプ、および推奨される対応を含めてください。前提条件
コネクターを追加する前に以下を準備してください：
- Telegramボットとそのボットトークン。
- ボットが対象のチャット、グループ、またはチャンネルにアクセスできること。
- 招待リンクの作成やメッセージ管理などの操作に必要な管理者権限。
Telegramコネクターの追加手順
- 左側のナビゲーションメニューで Connectors をクリックします。
- Available タブで Telegram を見つけて Add をクリックします。
- 説明的なコネクター名を入力します。
- Confirm をクリックすると、Telegram認証フローがダイアログで開きます。
- Bot Token に接続したいTelegramボットのトークンを入力します。
- ボットを作成する場合はTelegramで
@BotFatherにメッセージを送り、/newbotを送信してください。既存のボットの場合は/tokenを送信してトークンを取得します。 - Connect Account をクリックします。
- 成功メッセージを待ち、EMQXエージェントに戻ります。
- Added タブでコネクターのステータスが Authorized になっていることを確認します。
対応ツール
メッセージ送信
| ツール | アクセス | 説明 |
|---|---|---|
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 | 書き込み | ボットのコマンドリストを設定します。 |
重要なお知らせ
メッセージの送信、編集、削除、転送、招待リンク作成、ボットコマンドのツールはTelegramチャットを変更したりユーザーと通信します。書き込み操作の前にチャットIDと内容を必ず確認してください。
チャットでのコネクター利用方法
- チャットの入力欄でコネクターアイコンをクリックします。
- 認可済みの Telegram コネクターを選択します。
- プロンプトでエージェントが使用すべき外部リソースと操作を指定します。
- 生成されたエージェント定義を確認し、必要なツールのみが含まれていることを確認します。
権限とデータアクセス
コネクターは提供されたボットトークンで識別されるTelegramボットを通じて動作します。ボットのメンバーシップ、チャット管理者権限、Telegramのプライバシー設定、チャットタイプによりアクセス可能なメッセージや操作が決まります。
チャットプロンプトやエージェント指示に外部サービスの認証情報やアクセストークンを含めないでください。
制限事項
- Telegram Bot APIのレート制限およびファイルサイズ制限が適用されます。
- ボットは参加しているチャットのみアクセス可能で、Telegramボットのプライバシー設定で許可された更新のみ取得できます。
- 一部のメッセージ管理や招待リンク操作には管理者権限が必要です。
トラブルシューティング
| 症状 | 対処方法 |
|---|---|
| コネクターが Unauthorized のまま変わらない。 | 認証を再試行し、Bot Token が対象のTelegramボットのものであることを確認してください。 |
| ツールが権限エラーを返す。 | 認可されたアカウントが対象リソースと操作にアクセスできるか確認してください。 |
| 必要なツールが利用できない。 | ツールがこのコネクターでサポートされているか、承認されているか確認し、チャットで再度コネクターを選択してください。 |
| リクエストが断続的に拒否される。 | 外部サービスのステータス、APIクォータ、レート制限、アカウントプランを確認してください。 |