Telegram ツールキット

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

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

前提条件

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

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

@BotFatherを開く
Telegramを開き、@BotFatherとの会話を開始します。
新しいボットを作成
コマンド/newbotを送信し、指示に従います。
プロンプト詳細
Bot name 人間が読める表示名（例：My App）
Username ユニークでbotで終わる必要があります（例：myapp_bot）
ボットトークンをコピー
BotFatherが成功メッセージを返信します。これにボットトークンが含まれています — 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZのような形式です。コピーして安全に保存してください。

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

ヒント

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

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

Workflow Builder
Agent Builder

ワークフローにTelegramツールキットステップを追加します。
Select a Connection → Create a Connectionをクリックします。
Connection Nameを入力し、ボットトークンを貼り付けます。
Saveをクリックします。

トークンの管理

危険

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

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

@BotFatherにメッセージを送信
/mybotsを送信
ボットを選択
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ボットにメッセージを送信するたびに、ワークフローを自動的に開始します。

セットアップ：

トリガーを追加
New Messageトリガーをワークフローの最初のステップとして追加します。トリガー設定パネルから/tool-webhook/{workflow-id}URLをコピーします。
Webhookを登録
Register Webhookステップを使用して、TelegramにそのURLにメッセージを配信するよう指示します。一度実行します — 以下のRegister Webhookを参照してください。
テスト
ボットにテストメッセージを送信します。ワークフローが発火し、すべてのメッセージデータが変数として利用可能になります。

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

変数	説明
`{{ 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	オプション — フォームスーパーグループのトピック用

注意

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

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`

注意

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

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

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

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

注意

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

主要な入力：

入力	説明
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 }}

注意

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

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`に設定します

トリガーURLをコピー
New Messageトリガー付きのワークフローを作成します。トリガーパネルから/tool-webhook/{workflow-id}URLをコピーします。
Register Webhookを追加
別の1回限りのワークフローまたは手動テスト実行で、Register Webhookステップを追加し、上記の入力を記入します。
一度実行
ステップを実行します。次にボットにメッセージを送信します — メインのワークフローが発火するはずです。

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

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"
  }'

成功レスポンス：

{ "ok": true, "result": true, "description": "Webhook was set" }

注意

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

Deregister Webhook

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

主要な入力：

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

注意

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

トラブルシューティング

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

前提条件​

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

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

トークンの管理​

利用可能なツール​

トリガー — New Message​

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

Send Text Message​

Send Media​

Edit Message Text​

Delete Message​

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

Get Chat Info​

Get Chat Member​

Create Invite Link​

Webhook設定アクション​

Register Webhook​

Deregister Webhook​

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

前提条件

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

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

トークンの管理

利用可能なツール

トリガー — New Message

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

Send Text Message

Send Media

Edit Message Text

Delete Message

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

Get Chat Info

Get Chat Member

Create Invite Link

Webhook設定アクション

Register Webhook

Deregister Webhook

トラブルシューティング