Telegramプラットフォームの特徴ドキュメント

TelegramAdapter は、Telegram Bot API を基に構築されたアダプタであり、さまざまなメッセージタイプとイベント処理に対応しています。

ドキュメント情報

• 対応モジュールバージョン: 4.2.0
• メンテナー: ErisPulse

基本情報

• プラットフォームの概要：Telegram はクロスプラットフォームのリアルタイム通信ソフトウェアです。
• アダプタ名：TelegramAdapter
• 対応するプロトコル/APIバージョン：Telegram Bot API
• セッションタイプのマッピング：private → 送信時に user を使用、group/supergroup → group、channel → channel

標準Apiアクション（Api DSL）

アダプターは OB12 標準アクションを Telegram Bot API にマッピングし、data フィールドを標準化します：

拡張アクション：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 は errorcode=10002 を返します。

要求操作（Request DSL）

加群申請（chat_join_request イベント）を処理し、approveChatJoinRequest / declineChatJoinRequest を使用します。

from ErisPulse.Core.Event import request

@request.on_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("user_nickname"):
        await event.approve()          # 同意
    # await event.reject()             # 拒絶

# 手動呼び出し（対応する要求イベントを事前に受信してコンテキストを登録しておく必要があります）
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!")

基本送信メソッド

メディア送信メソッド

すべてのメディアメソッドは、bytes（アップロード）と str（file_id / URL）の2種類の入力をサポートします：

メッセージ管理メソッド

原始メッセージ送信

• .Raw_ob12(message: List[Dict])：OneBot12標準形式のメッセージを送信
• .Raw_json(json_str: str)：原始JSON形式のメッセージを送信

チェーン式修飾メソッド

送信例

# 基本文本送信
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("静かに通知")

# コールバッククエリに応答
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

# 位置情報を送信
await telegram.Send.To("user", user_id).Location(39.9042, 116.4074)

特有イベントタイプ

Telegram イベントの変換は OneBot12 標準に従い、telegram_ プレフィックスによるプラットフォーム拡張を提供します。

メッセージイベント detail_type マッピング

特有イベントタイプ

標準メッセージセグメントタイプ

変換後のメッセージセグメントは OneBot12 標準形式を使用します：

プラットフォーム拡張メッセージセグメント

telegram_ プレフィックスで識別される拡張メッセージセグメント：

イベントの例

グループチャットメッセージ（@ユーザーのメンション付き）

{
  "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",
  "telegram_chat": {
    "id": -1002850921906,
    "title": "ErisPulse",
    "username": "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" の場合にのみ利用可能な以下のプラットフォーム固有メソッドを登録しています。

メッセージ関連

コールバッククエリ関連

メッセージセグメントデータの抽出

使用例

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 フィールドに保持されます
• チャンネルメッセージは 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）を使用してください。

旧版設定の移行

旧版の単一トークンの設定は自動的に互換性があります：

# 旧版の形式（引き続き使用可能ですが、移行することを推奨します）
[Telegram_Adapter]
token = "YOUR_BOT_TOKEN"

新しい形式への移行を推奨します：

[Telegram_Adapter.accounts.default]
token = "YOUR_BOT_TOKEN"
enabled = true