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

# Telegram ツールキット

> Telegramボットをエージェントやワークフローに接続し、メッセージの送信、チャット管理、受信メッセージによるオートメーションのトリガーを行います。

Telegram ツールキットにより、エージェントやワークフローがTelegramボットと対話できるようになります。メッセージの送信と編集、メディア送信、チャットメンバーの管理、招待リンクの生成、受信メッセージによるワークフローのトリガーとなるWebhookの登録に対応しています。

Telegramボットとその認証情報は、**@BotFather**というTelegramボットを通じて管理されます。Web開発者コンソールはありません。

## 前提条件

| 要件            | 詳細                     |
| ------------- | ---------------------- |
| Telegramアカウント | @BotFatherと対話するために必要です |

## ステップ1 — Telegramボットの作成

<Steps>
  <Step title="@BotFatherを開く">
    Telegramを開き、[@BotFather](https://t.me/BotFather)との会話を開始します。
  </Step>

  <Step title="新しいボットを作成">
    コマンド`/newbot`を送信し、指示に従います。

    | プロンプト    | 詳細                                   |
    | -------- | ------------------------------------ |
    | Bot name | 人間が読める表示名（例：`My App`）                |
    | Username | ユニークで`bot`で終わる必要があります（例：`myapp_bot`） |
  </Step>

  <Step title="ボットトークンをコピー">
    BotFatherが成功メッセージを返信します。これにボットトークンが含まれています — `123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ`のような形式です。コピーして安全に保存してください。
  </Step>
</Steps>

<Tip>
  BotFatherの`/setuserpic`コマンドを使用して、アプリケーションのロゴに合ったプロフィール画像を設定してください。辨識可能な画像は、ボットをユーザーに対してプロフェッショナルで信頼できるものにします。
</Tip>

## ステップ2 — トークンをEKBに追加

<Tabs>
  <Tab title="Workflow Builder">
    1. ワークフローにTelegramツールキットステップを追加します。
    2. **Select a Connection** → **Create a Connection**をクリックします。
    3. **Connection Name**を入力し、ボットトークンを貼り付けます。
    4. **Save**をクリックします。
  </Tab>

  <Tab title="Agent Builder">
    1. **Agent Builder**でエージェントを開きます。
    2. 左サイドバーの**Toolkits**タブに移動します。
    3. **Telegram**を見つけて**Add to Agent**をクリックします。
    4. **Telegram Bot Token**にボットトークンを貼り付けます。
    5. **Save**をクリックします。
  </Tab>
</Tabs>

## トークンの管理

<Danger>
  ボットトークンはボットのマスターキーです。公開リポジトリにコミットしたり、クライアントサイドコードで公開したりせず、共有しないでください。
</Danger>

トークンが漏洩した場合は、即座に取り消してください：

1. @BotFatherにメッセージを送信
2. `/mybots`を送信
3. ボットを選択
4. **API Token** → **Revoke current token**をタップ

新しいトークンが生成されます。新しい値でEKBの接続を更新してください。

## 利用可能なツール

| ツール                    | 説明                                   |
| ---------------------- | ------------------------------------ |
| **New Message（トリガー）**  | ボットにメッセージが送信されたらワークフローを開始します         |
| **Send Text Message**  | ボットから任意のチャットにテキストメッセージを送信します         |
| **Send Media**         | 写真、動画、スタンプ、アニメーションGIFを送信します          |
| **Edit Message Text**  | 以前に送信されたメッセージのテキストを更新します             |
| **Delete Message**     | チャットからメッセージを削除します                    |
| **Get Chat Info**      | チャットのメタデータを取得します                     |
| **Get Chat Member**    | チャット内のユーザーのメンバーシップ状態を取得します           |
| **Create Invite Link** | グループまたはチャンネルの招待リンクを生成します             |
| **Register Webhook**   | Telegramにボットメッセージをワークフローに転送するよう指示します |
| **Deregister Webhook** | Webhookを削除し、メッセージの配信を停止します           |

## トリガー — New Message

誰かがTelegramボットにメッセージを送信するたびに、ワークフローを自動的に開始します。

**セットアップ：**

<Steps>
  <Step title="トリガーを追加">
    **New Message**トリガーをワークフローの最初のステップとして追加します。トリガー設定パネルから`/tool-webhook/{workflow-id}`URLをコピーします。
  </Step>

  <Step title="Webhookを登録">
    **Register Webhook**ステップを使用して、TelegramにそのURLにメッセージを配信するよう指示します。一度実行します — 以下の[Register Webhook](#register-webhook)を参照してください。
  </Step>

  <Step title="テスト">
    ボットにテストメッセージを送信します。ワークフローが発火し、すべてのメッセージデータが変数として利用可能になります。
  </Step>
</Steps>

**利用可能なトリガー変数：**

| 変数                                           | 説明                               |
| -------------------------------------------- | -------------------------------- |
| `{{ trigger.body.message.text }}`            | ユーザーが送信したメッセージテキスト               |
| `{{ trigger.body.message.chat.id }}`         | チャットID — すべての送信ステップでChat IDとして使用 |
| `{{ trigger.body.message.from.id }}`         | 送信者のTelegramユーザーID               |
| `{{ trigger.body.message.from.first_name }}` | 送信者の名前                           |
| `{{ trigger.body.message.from.username }}`   | 送信者のユーザー名（空の場合あり）                |
| `{{ trigger.body.message.message_id }}`      | 受信メッセージのID                       |
| `{{ trigger.body.update_id }}`               | Telegramからの一意の更新ID               |

## メッセージングアクション

### Send Text Message

ボットから任意のTelegramチャットにテキストメッセージを送信します。

**主要な入力：**

| 入力                       | 説明                                                                                                                   |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| Chat ID                  | 送信先のチャット。ワークフローをトリガーした人の場合は`{{ trigger.body.message.chat.id }}`を使用します。固定のグループまたはチャンネルの場合は、その数値IDを貼り付けます。             |
| Message                  | 送信するテキスト。静的テキストと変数を組み合わせます。例：`Hello {{ trigger.body.message.from.first_name }}, your request was received.`          |
| Format                   | プレーンテキストの場合は空白にします。`HTML`に設定すると`<b>太字</b>` / `<i>斜体</i>`が使用できます。`MarkdownV2`に設定するとMarkdownが使用できます（特殊文字は自動エスケープされます）。 |
| Disable Web Page Preview | リンクプレビューを抑制するには`true`に設定します                                                                                          |
| Message Thread ID        | オプション — Forumスーパーグループのみに該当します                                                                                        |
| Reply Markup             | オプション — インラインキーボードまたはカスタム返信キーボード用のJSONオブジェクト                                                                         |

**後続ステップでの出力参照:**

* メッセージID（後でEditやDeleteに必要）: `{{ step.output.message_id }}`
* チャットID: `{{ step.output.chat_id }}`

### Send Media

Telegramチャットに写真、動画、スタンプ、アニメーションGIFを送信します。

**主要な入力：**

| 入力                | 説明                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------ |
| Chat ID           | 送信先のチャット                                                                             |
| Media Type        | 以下のいずれかを正確に指定: `photo`、`video`、`sticker`、`animation`                                 |
| Media URL         | ファイルへの公開アクセス可能なHTTPS URL — Telegramが直接取得します                                          |
| Media ID          | または、以前にアップロードされたファイルのTelegram `file_id`。Media URLまたはMedia IDのいずれかを提供し、両方は指定しないでください。 |
| Caption           | メディアの下に表示されるオプションのテキスト。FormatでHTML/MarkdownV2に対応しています。                               |
| Format            | キャプションのパースモード                                                                        |
| Message Thread ID | オプション — フォームスーパーグループのトピック用                                                           |

<Note>
  Media URLもMedia IDも提供しない場合、ステップはエラーを返します。URLは公開アクセス可能でなければなりません。ローカルまたはプライベートURLは機能しません。
</Note>

### Edit Message Text

ボットが以前に送信したメッセージのテキストを更新します。

**主要な入力：**

| 入力         | 説明                                                                   |
| ---------- | -------------------------------------------------------------------- |
| Chat ID    | 元のメッセージがあるチャット                                                       |
| Message ID | Send Text Messageの出力からの`message_id` — `{{ step.output.message_id }}` |
| Text       | 新しいメッセージコンテンツ                                                        |
| Format     | 新しいテキストのパースモード（空白=プレーンテキスト、`HTML`、または`MarkdownV2`）                   |

**使用例:** まず「リクエストを処理中…」と送信します。ワークフローロジックを実行します。その後、最終結果でそのメッセージを編集します — ユーザーは2つのメッセージではなく1つのメッセージを見ます。

### Delete Message

チャットからメッセージを削除します。

**主要な入力：**

| 入力         | 説明                     |
| ---------- | ---------------------- |
| Chat ID    | メッセージを含むチャット           |
| Message ID | 削除するメッセージの`message_id` |

<Note>
  ボットはチャットの管理者でない限り、自分のメッセージのみを削除できます。Telegramは時間制限も設けています — 48時間以上経過したメッセージは通常、ボットでは削除できません。
</Note>

## チャットとメンバーのアクション

### Get Chat Info

チャットのメタデータを取得します。

**主要な入力：**

| 入力      | 説明       |
| ------- | -------- |
| Chat ID | 参照するチャット |

**後続ステップでの値参照:**

* チャットタイトル: `{{ step.output.title }}`
* 説明: `{{ step.output.description }}`
* 招待リンク: `{{ step.output.invite_link }}`

### Get Chat Member

チャット内の特定のユーザーを参照し、メンバーシップ状態とロールを返します。

**主要な入力：**

| 入力      | 説明                                                                               |
| ------- | -------------------------------------------------------------------------------- |
| Chat ID | 参照するチャット                                                                         |
| User ID | 参照するTelegramユーザーID。ワークフローをトリガーした人の場合は`{{ trigger.body.message.from.id }}`を使用します。 |

**後続ステップでの値参照:**

* Status: `{{ step.output.status }}`
* Username: `{{ step.output.username }}`

**可能なステータス値:** `creator`、`administrator`、`member`、`restricted`、`left`、`kicked`

**使用例:** `{{ step.output.status }}`を確認し、`left`または`kicked`の場合、メッセージの送信をスキップしてエラーを処理します。

### Create Invite Link

グループまたはチャンネルの新しい招待リンクを生成します。

<Note>
  ボットは対象チャットで「ユーザー招待」権限を持つ管理者である必要があります。
</Note>

**主要な入力：**

| 入力           | 説明                                                                         |
| ------------ | -------------------------------------------------------------------------- |
| Chat ID      | グループまたはチャンネル                                                               |
| Name         | オプションのラベル（最大32文字）。Telegram管理パネルに表示されます                                     |
| Expire Date  | オプション。リンクの有効期限のISO-8601文字列。例：`2026-12-31T23:59:59Z`。内部でunixタイムスタンプに変換されます。 |
| Member Limit | オプション。このリンク経由で参加できる最大人数（1〜99,999）                                          |

**後続ステップでのリンク参照:**

* 招待URL: `{{ step.output.invite_link }}`

<Note>
  出力の`expire_date`はunixタイムスタンプ（整数秒）であり、ISO形式ではありません。`creates_join_request`は、チャットが新しいメンバーに管理者の承認を要求する場合に`true`になります。
</Note>

## Webhook設定アクション

これらの2つのステップはNew Messageトリガーをボットに接続します。ワークフローごとに一度実行します。

### Register Webhook

TelegramにボットからのメッセージをワークフローURLに転送するよう指示します。

**主要な入力：**

| 入力                   | 説明                                                                                                        |
| -------------------- | --------------------------------------------------------------------------------------------------------- |
| URL                  | New Messageトリガーパネルからの`/tool-webhook/{workflow-id}`URL                                                     |
| Allowed Updates      | 通常のメッセージのみを受信するには`["message"]`に設定します（推奨）。空白の場合は同じデフォルトを使用します。                                             |
| Secret Token         | オプションですが推奨されます。任意のランダム文字列（例：`my-secret-abc123`）。TelegramがすべてのWebhookリクエストヘッダーにこれを含め、リクエストが本物であることを検証できます。 |
| Drop Pending Updates | Webhook登録前に到着したメッセージを無視するには`true`に設定します                                                                   |

<Steps>
  <Step title="トリガーURLをコピー">
    New Messageトリガー付きのワークフローを作成します。トリガーパネルから`/tool-webhook/{workflow-id}`URLをコピーします。
  </Step>

  <Step title="Register Webhookを追加">
    別の1回限りのワークフローまたは手動テスト実行で、**Register Webhook**ステップを追加し、上記の入力を記入します。
  </Step>

  <Step title="一度実行">
    ステップを実行します。次にボットにメッセージを送信します — メインのワークフローが発火するはずです。
  </Step>
</Steps>

または、curlで迅速な1回限りのセットアップとして登録できます：

```bash theme={null}
curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/tool-webhook/<YOUR_WORKFLOW_ID>",
    "allowed_updates": ["message"],
    "secret_token": "my-secret-abc123"
  }'
```

成功レスポンス：

```json theme={null}
{ "ok": true, "result": true, "description": "Webhook was set" }
```

<Note>
  Telegramボットは同時に1つのアクティブなWebhookしか持つことができません。新しいURLを登録すると、以前のURLは自動的に置き換えられます。
</Note>

### Deregister Webhook

Webhookを削除し、Telegramがワークフローにメッセージを配信するのを停止します。

**主要な入力：**

| 入力                   | 説明                                                |
| -------------------- | ------------------------------------------------- |
| Drop Pending Updates | Webhookがアクティブだった間にキューに入ったメッセージを破棄するには`true`に設定します |

<Note>
  ワークフローを退役またはアーカイブする場合はWebhookの登録を解除してください。Webhookを登録したままワークフローを非アクティブにすると、Telegramは応答のないリクエストを送信し続けます。
</Note>

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

| 症状                                 | 原因の可能性                         | 対処                                       |
| ---------------------------------- | ------------------------------ | ---------------------------------------- |
| 新しいメッセージでワークフローが発火しない              | Webhookが登録されていないか、誤ったURLを指している | 正しいトリガーURLで**Register Webhook**を実行       |
| `401 Unauthorized`                 | ボットトークンが無効または取り消されている          | トークンを確認するか、@BotFatherで新しいトークンを生成         |
| メディアが配信されない                        | URLが公開アクセス可能でない                | 公開HTTPS URLを使用 — ローカルまたはプライベートURLは機能しません |
| メッセージを削除できない                       | メッセージが48時間以上経過しているか、ボットが管理者でない | 管理者権限がない限り、ボットは最近のメッセージのみ削除できます          |
| 招待リンクで`creates_join_request: true` | チャットが新しいメンバーに管理者承認を要求          | これは正常な動作です — ユーザーは参加前に承認が必要です            |
| 古いメッセージがワークフローをトリガー                | Webhook登録時に保留中の更新がクリアされていない    | `Drop Pending Updates`を`true`に設定して再登録    |