Telegramプラットフォーム特性ドキュメント
TelegramAdapter は Telegram Bot API をベースに構築されたアダプターで、複数のメッセージタイプとイベント処理をサポートしています。
ドキュメント情報
- 対応モジュールバージョン: 4.3.3
- メンテナー: ErisPulse
- 最終更新: 2026-11-10
基本情報
- プラットフォーム概要:Telegram はクロスプラットフォームのインスタントメッセージングソフトウェアです
- アダプター名:TelegramAdapter
- サポートするプロトコル/APIバージョン:Telegram Bot API
- 会話タイプのマッピング:
private→ 送信時はuser、group/supergroup→group、channel→channel
標準化対応(4.3.3)
本章では、4.3.3 バージョンで完了した標準化対応の内容を説明します:イベントの変更、マルチアカウントの規約、エラーコード規範と Send 規範。
イベントの変更
- グループ参加申請イベントの標準化:
detail_typeがtelegram_chat_join_requestから標準の"group"に変更され、sub_type="join"となります@request.on_group_request()がこのイベントを直接キャッチできるようになりましたrequest_idの合成ルールは変更なし:tjr_{chat_id}_{user_id}_{date}- イベントは
event.approve()/event.reject()で承認可能です(approveChatJoinRequest/declineChatJoinRequestに対応)
- イベントへの
self.account_id注入:すべてのイベントはそれを生成したアカウント名を保持し、マルチアカウント環境下ではevent.reply()が自動的にそのアカウントで送信を処理します - unknown イベント:
self.user_idには bot_id が設定されます(メッセージイベントの動作と一致)
リクエストイベントインターフェースの規約は SDK 標準に従います:リクエストと承認アクション規範。
アカウントとマルチアカウント
call_api は双方向互換のアカウントフィールドをサポートします:標準フィールド account_id(ApiDSL.Using ではこの名前を使用)/ 旧エイリアス _account_id;フレームワークの ApiDSL は新旧アダプターを自動的に適応させます。
from ErisPulse import sdk
telegram = sdk.adapter.get("telegram")
await telegram.Api.Using("main").get_self_info() # 標準的な方法でアカウントを指定
await telegram.Api.get_self_info(account_id="main") # 標準フィールド account_id を明示的に渡す
エラーコード規範
| retcode | 説明 |
|---|---|
| 0 | 成功 |
| 33001 | ネットワークエラー(接続失敗、タイムアウトなど) |
| 34100 | プラットフォーム拒否(元のレスポンスは telegram_raw フィールドに保持) |
| 10002 | サポートされていないアクション(get_friend_list / get_group_list など、Telegram Bot API に対応するインターフェースが存在しない) |
Send 規範
- HTML メソッド名は
HTMLで、Htmlは予約済みエイリアスです Locationのシグネチャにtitle/contentのオプションパラメータを補完AnswerCallback/Raw_jsonは send_context アカウントを使用:イベント処理チェーン内で送信 DSL を呼び出す際、自動的に現在のイベントが属するアカウントで送信します
標準Apiアクション(Api DSL)
アダプターは OB12 標準アクションを Telegram Bot API にマッピングし、data フィールドを標準化します:
| OB12 標準アクション | Telegram API | data フィールド |
|---|---|---|
| get_self_info | getMe | user_id / user_name / user_displayname |
| get_user_info(user_id) | getChat | user_id / user_name / user_displayname |
| get_group_info(group_id) | getChat | group_id / group_name |
| get_group_member_info(group_id, user_id) | getChatMember | user_id / user_name / telegram_role |
| delete_message(message_id) | deleteMessage | メッセージ登録テーブルに基づいて chat_id を自動補完 |
| leave_group(group_id) | leaveChat | - |
拡張アクション:get_group_admin_list(group_id)(管理者リスト)、get_chat_member_count(chat_id)(メンバー数)。
from ErisPulse import sdk
telegram = sdk.adapter.get("telegram")
result = await telegram.Api.get_self_info()
result = await telegram.Api.get_group_info(group_id=-100123)
result = await telegram.Api.get_group_admin_list(-100123)
await telegram.Api.delete_message(message_id=55) # chat_id を自動補完
result = await telegram.Api.Using("main").get_self_info()
Telegram Bot API にはフレンドリスト/グループリストを取得するインターフェースが存在せず、get_friend_list/get_group_list は明示的に retcode=10002(サポートされていないアクション)を返します。
リクエスト操作(Request DSL)
グループ参加申請の処理は、approveChatJoinRequest / declineChatJoinRequest に基づきます。4.3.3 以降、chat_join_request は標準の group リクエストイベント(sub_type="join")にマッピングされ、@request.on_group_request() が直接キャッチできるようになりました:
from ErisPulse.Core.Event import request
@request.on_group_request()
async def handle_join_request(event):
if event.get("platform") != "telegram":
return
# event["request_id"] は合成識別子(tjr_{chat_id}_{user_id}_{date}、ルールは変更なし)
if event.get("sub_type") == "join":
await event.approve() # 承認(approveChatJoinRequest)
# await event.reject() # 拒否(declineChatJoinRequest)
# 手動呼び出し(対応するリクエストイベントを先に受信してコンテキストを登録しておく必要あり)
await telegram.Request(event["request_id"]).accept()
await telegram.Request(event["request_id"]).reject()
await telegram.Request(event["request_id"]).Using("main").accept()
サポートされるメッセージ送信タイプ
すべての送信メソッドはチェーン構文で実装されています。例:
from ErisPulse.Core import adapter
telegram = adapter.get("telegram")
await telegram.Send.To("user", user_id).Text("Hello World!")
基本送信メソッド
| メソッド | 説明 | パラメータ |
|---|---|---|
.Text(text) |
プレーンテキストメッセージを送信 | text: str |
.Face(emoji) |
絵文字ダイスを送信 | emoji: str(例:🎲 🎯 🏀) |
.Markdown(text, content_type) |
Markdown 形式のメッセージを送信 | content_type のデフォルトは "MarkdownV2" |
.HTML(text) |
HTML 形式のメッセージを送信(Html は予約済みエイリアス) |
text: str |
.MergeForward(nodes, title) |
結合転送メッセージを送信(タイトル + 各 blockquote 引用ブロック、4096 で切り詰め) | nodes: List[Dict], title: str |
.Sticker(file) |
ステッカーを送信 | file: str (file_id/URL) | bytes |
.Location(lat, lng, title="", content="") |
位置情報を送信(タイトルと内容はオプション) | latitude: float, longitude: float, title: str, content: str |
.Venue(lat, lng, title, addr) |
場所(会場)情報を送信 | タイトルと住所を含む |
.Contact(phone, first, last) |
連絡先を送信 | 電話番号と氏名を含む |
メディア送信メソッド
すべてのメディアメソッドは bytes(アップロード)と str(file_id / URL)の2種類の入力をサポートします:
| メソッド | 説明 |
|---|---|
.Image(file, caption, content_type) |
画像を送信 |
.Video(file, caption, content_type) |
動画を送信 |
.Voice(file, caption) |
ボイスメッセージを送信 |
.Audio(file, caption, content_type) |
音声を送信 |
.File(file, caption) |
ファイルを送信 |
.Document(file, caption, content_type) |
File のエイリアス |
メッセージ管理メソッド
| メソッド | 説明 |
|---|---|
.Edit(message_id, text, content_type) |
既存のメッセージを編集 |
.Recall(message_id) |
指定したメッセージを削除 |
.Forward(from_chat_id, message_id) |
メッセージを転送(転送元を保持) |
.CopyMessage(from_chat_id, message_id) |
メッセージをコピー(転送元なし) |
.AnswerCallback(callback_query_id, text, show_alert) |
コールバッククエリに応答(send_context アカウントを使用) |
生メッセージ送信
.Raw_ob12(message: List[Dict]):OneBot12 標準形式のメッセージを送信.Raw_json(json_str: str):生の JSON 形式メッセージを送信(send_context アカウントを使用)
チェーン修飾メソッド
| メソッド | 説明 |
|---|---|
.At(user_id) |
指定ユーザーを@(Telegram entities で実装、複数回呼び出し可能) |
.AtAll() |
全メンバーに@(@All テキストを送信) |
.Reply(message_id) |
指定メッセージに返信 |
.Keyboard(inline_keyboard) |
インラインキーボードを設定(list[list[dict]]) |
.ProtectContent(protect) |
コンテンツを保護(転送と保存を防止) |
.Silent(silent) |
サイレント送信(ユーザーに通知しない) |
送信例
# 基本的なテキスト送信
await telegram.Send.To("user", user_id).Text("Hello World!")
# インラインキーボード付きのメッセージ
from ErisPulse import sdk
telegram = sdk.adapter.get("telegram")
keyboard = [
[{"text": "ボタン1", "callback_data": "btn1"}, {"text": "ボタン2", "callback_data": "btn2"}],
[{"text": "公式サイトへ", "url": "https://example.com"}],
]
await telegram.Send.To("group", group_id).Keyboard(keyboard).Text("選択してください:")
# メディア送信(URL 方式)
await telegram.Send.To("group", group_id).Image("https://example.com/image.jpg", caption="画像")
# @ユーザー
await telegram.Send.To("group", group_id).At("6117725680").Text("こんにちは!")
# 返信 + コンテンツ保護
await telegram.Send.To("group", group_id).Reply("12345").ProtectContent().Text("機密メッセージ")
# サイレント送信
await telegram.Send.To("group", group_id).Silent().Text("サイレント通知")
# HTML 形式メッセージ(Html は旧名のエイリアス)
await telegram.Send.To("user", user_id).HTML("<b>太字</b> <i>斜体</i>")
# 位置情報の送信(タイトル付き)
await telegram.Send.To("user", user_id).Location(39.9042, 116.4074, title="天安門", content="北京中心部")
# コールバッククエリへの応答
await telegram.Send.AnswerCallback(callback_query_id, text="処理済み", show_alert=False)
# OneBot12 組み合わせメッセージ
ob12_message = [
{"type": "text", "data": {"text": "複雑なメッセージ:"}},
{"type": "mention", "data": {"user_id": "6117725680", "user_name": "ユーザー名"}},
{"type": "reply", "data": {"message_id": "12345"}},
{"type": "image", "data": {"file": "https://http.cat/200"}}
]
await telegram.Send.To("group", group_id).Raw_ob12(ob12_message)
# ステッカーの送信
await telegram.Send.To("user", user_id).Sticker("CAACAgIAAxkBAA...") # file_id
固有イベントタイプ
Telegram イベントの変換は OneBot12 標準に従い、同時に telegram_ プレフィックスでプラットフォーム拡張を提供します。
メッセージイベントの detail_type マッピング
| Telegram chat.type | OneBot12 detail_type | 送信ターゲットタイプ |
|---|---|---|
private |
private |
user |
group |
group |
group |
supergroup |
group |
group |
channel |
channel |
channel |
固有イベントタイプ
| detail_type | 説明 |
|---|---|
telegram_callback_query |
コールバッククエリ(インラインキーボードボタンのクリック) |
telegram_inline_query |
インラインクエリ |
telegram_chosen_inline_result |
選択されたインライン結果 |
telegram_poll |
投票イベント |
telegram_poll_answer |
投票回答 |
telegram_my_chat_member |
Bot 自身のメンバーステータス変更 |
telegram_chat_member |
チャットメンバー変更 |
telegram_shipping_query |
配送先クエリ |
telegram_pre_checkout_query |
決済前クエリ |
チャット参加リクエスト(chat_join_request)は標準の
groupリクエストイベント(sub_type="join")に標準化され、 detail_type としてtelegram_chat_join_requestは使用されなくなりました;関連するプラットフォームフィールド (telegram_chat_join_request_id、telegram_chatなど)は引き続き保持されます。
標準メッセージセグメントタイプ
変換後のメッセージセグメントは OneBot12 標準形式を使用します:
| メッセージセグメントタイプ | 説明 | data フィールド |
|---|---|---|
text |
プレーンテキスト(@ユーザー名を含まない) | text |
mention |
@ユーザー(標準 OB12) | user_id, user_name |
reply |
返信引用 | message_id, user_id |
image |
画像 | file_id, url |
video |
動画 | file_id, url, duration, width, height |
voice |
ボイス | file_id, url, duration |
audio |
音声 | file_id, url, duration, title, performer |
file |
ファイル | file_id, url, file_name, file_size, mime_type |
location |
位置情報 | latitude, longitude, オプションの title, address |
プラットフォーム拡張メッセージセグメント
telegram_ プレフィックスで識別される拡張メッセージセグメント:
| メッセージセグメントタイプ | 説明 | data フィールド |
|---|---|---|
telegram_sticker |
ステッカー | file_id, emoji, sticker_type, url |
telegram_animation |
GIF アニメーション | file_id, url, duration, caption |
telegram_contact |
連絡先 | phone_number, first_name, last_name, user_id |
telegram_inline_keyboard |
インラインキーボード | inline_keyboard |
イベント例
グループチャットメッセージ(@メンションを含む)
{
"type": "message",
"detail_type": "group",
"platform": "telegram",
"user_id": "6117725680",
"user_nickname": "WSu2059",
"group_id": "-1002850921906",
"message_id": "172",
"message": [
{"type": "text", "data": {"text": "/it.echo "}},
{"type": "mention", "data": {"user_id": "", "user_name": "@nm123_91178"}}
],
"alt_message": "/it.echo @nm123_91178",
"self": {
"platform": "telegram",
"user_id": "6117725680",
"account_id": "default"
},
"telegram_chat": {
"id": -1002850921906,
"title": "ErisPulse",
"username": "erispulse",
"type": "supergroup"
}
}
グループ参加申請イベント(標準化後)
{
"type": "request",
"detail_type": "group",
"sub_type": "join",
"platform": "telegram",
"user_id": "6117725680",
"user_nickname": "申請者のニックネーム",
"request_id": "tjr_-1002850921906_6117725680_1731212345",
"group_id": "-1002850921906",
"comment": "招待リンクの名前",
"self": {
"platform": "telegram",
"user_id": "6117725680",
"account_id": "default"
},
"telegram_chat_join_request_id": "",
"telegram_chat": {
"id": -1002850921906,
"title": "ErisPulse",
"type": "supergroup"
}
}
コールバッククエリイベント
{
"type": "notice",
"detail_type": "telegram_callback_query",
"user_id": "123456",
"user_nickname": "YingXinche",
"telegram_callback_id": "cb_123",
"telegram_callback_data": "callback_data",
"message_id": "msg_456"
}
インラインクエリイベント
{
"type": "request",
"detail_type": "telegram_inline_query",
"user_id": "789012",
"user_nickname": "YingXinche",
"telegram_query_id": "iq_789",
"telegram_query_text": "search_text",
"telegram_query_offset": "0"
}
インラインキーボード付きのメッセージ
{
"type": "message",
"detail_type": "group",
"message": [
{"type": "text", "data": {"text": "選択してください:"}},
{
"type": "telegram_inline_keyboard",
"data": {
"inline_keyboard": [
[{"text": "ボタン1", "callback_data": "btn1"}],
[{"text": "アクセス", "url": "https://example.com"}]
]
}
}
]
}
Event Mixin 拡張メソッド
アダプターは以下のプラットフォーム専用メソッドを登録しており、platform == "telegram" の場合にのみ使用できます:
メッセージ関連
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
is_bot_message() |
bool |
メッセージがボットからのものかどうかを判定 |
is_edited_message() |
bool |
編集されたメッセージかどうかを判定 |
is_topic_message() |
bool |
トピック(Topic)メッセージかどうかを判定 |
get_update_id() |
int |
Telegram update ID を取得 |
get_chat_title() |
str |
チャットタイトルを取得 |
get_chat_username() |
str |
チャットのユーザー名を取得 |
get_forward_from() |
dict |
転送元情報を取得 |
get_topic_id() |
str |
トピック ID を取得 |
コールバッククエリ関連
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
get_callback_data() |
str |
コールバッククエリの callback_data を取得 |
get_callback_id() |
str |
コールバッククエリ ID を取得(応答に使用) |
メッセージセグメントデータの抽出
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
get_inline_keyboard() |
list |
メッセージ内のインラインキーボードを取得 |
get_sticker_info() |
dict |
ステッカー情報を取得 |
get_contact_info() |
dict |
連絡先情報を取得 |
get_location() |
dict |
位置情報を取得 |
使用例
from ErisPulse.Core.Event import message, notice
@message.on_message()
async def handle_message(event):
if event.get("platform") != "telegram":
return
# メッセージの属性
if event.is_bot_message():
return # ボットのメッセージを無視
if event.is_edited_message():
print("これは編集されたメッセージです")
# チャット情報
title = event.get_chat_title()
username = event.get_chat_username()
# 転送元
forward = event.get_forward_from()
# メッセージセグメントデータ
sticker = event.get_sticker_info()
contact = event.get_contact_info()
location = event.get_location()
keyboard = event.get_inline_keyboard()
# トピック
if event.is_topic_message():
topic_id = event.get_topic_id()
@notice.on_notice()
async def handle_notice(event):
if event.get("platform") != "telegram":
return
if event.get("detail_type") == "telegram_callback_query":
callback_data = event.get_callback_data()
callback_id = event.get_callback_id()
# コールバッククエリへの応答
telegram = sdk.adapter.get("telegram")
await telegram.Send.AnswerCallback(callback_id, text="クリックされました")
# メッセージへの返信(マルチアカウント環境下では自動的にイベントが属するアカウントで処理)
await event.reply(f"あなたがクリックした内容:{callback_data}")
拡張フィールドの説明
- すべての固有フィールドは
telegram_プレフィックスで識別されます - 元のデータは
telegram_rawフィールドに保持されます - 元のイベントタイプは
telegram_raw_typeフィールドに保持されます - イベントの
self.account_idはイベントを生成したアカウント名です(マルチアカウント環境下ではevent.reply()が自動的にそのアカウントで処理します) - チャンネルメッセージは
detail_type="channel"を使用します - 個人チャットメッセージは
detail_type="private"を使用します(送信時はuserに変換する必要があります) - トピックメッセージには
thread_idフィールドが含まれます @メンションは標準のmentionメッセージセグメントタイプ(type: "mention")を使用し、テキストには @ユーザー名が含まれません
設定オプション
Telegram アダプターはマルチアカウント設定をサポートします:
設定例
[Telegram_Adapter.accounts.default]
token = "YOUR_BOT_TOKEN"
enabled = true
[Telegram_Adapter.accounts.bot2]
token = "ANOTHER_BOT_TOKEN"
enabled = true
実行モード
Telegram アダプターは Polling(ポーリング) モードのみをサポートし、Webhook モードは削除されました。
プロキシ設定
プロキシ経由で Telegram API に接続する必要がある場合は、システムレベルのプロキシ(環境変数 ALL_PROXY / HTTPS_PROXY)を使用してください。
旧バージョン設定の移行
旧バージョンの単一 token 設定は自動的に互換性を保ちます:
# 旧形式(引き続き使用可能ですが、移行を推奨)
[Telegram_Adapter]
token = "YOUR_BOT_TOKEN"
新しい形式への移行を推奨します:
[Telegram_Adapter.accounts.default]
token = "YOUR_BOT_TOKEN"
enabled = true