TelegramBots 入门指南

本文档详细介绍了如何使用 TelegramBots 库实现长轮询模式，进而接收和处理 Telegram Bot 发送的各种类型消息。内容涵盖了长轮询模式的工作原理、环境配置、核心代码实现示例以及 Telegram Bot API 返回的多种消息格式解析说明。在示例中的所有关键数据（如用户 ID、频道 ID、消息 ID、时间戳等）均已使用占位符进行脱敏处理，确保数据安全。

1. 长轮询模式简介

Telegram 提供了多种与 Bot 进行交互的机制，其中最常用的一种是 长轮询（Long Polling）。在该模式下，Bot 客户端会周期性地调用 getUpdates 接口，与 Telegram 服务器进行连接：

客户端请求：Bot 通过 getUpdates 向服务器发起 HTTP 请求。
服务器等待响应：服务器会在请求中阻塞一定时间（由 timeout 参数决定），等待是否有新的消息产生。
返回新消息：若在等待期间有更新，则服务器立即返回包含更新数据的 JSON；若无更新，则返回空结果。
超时重试：收到空结果后，客户端会立即重新发起请求，实现持续的长轮询过程，从而达到“即时响应新消息”的效果，并减少无效请求与资源浪费。

在使用 TelegramBots 库时，这一底层交互逻辑由框架自动处理，开发者只需关注 Update 对象的业务处理逻辑。

2. 入门示例

以下示例展示了一个基本的长轮询 Bot 结构，包括环境准备、依赖添加、核心类的实现以及运行说明。

2.1 环境准备

在开始之前，请确保满足以下条件：

已通过 BotFather 创建 Telegram Bot 并获取对应的 Token。
本地已安装并配置好 Java 开发环境。
工程中已导入 telegrambots 相关依赖，包括 telegrambots-meta、telegrambots 以及 telegrambots-longpolling 等。

2.2 添加依赖

以下为 Maven 配置示例，添加所需依赖：

xml

<dependency>
  <groupId>ch.qos.logback</groupId>
  <artifactId>logback-classic</artifactId>
  <version>1.4.12</version>
</dependency>

<!-- Jackson Core 库，用于 JSON 处理 -->
<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-core</artifactId>
  <version>2.17.2</version>
</dependency>

<dependency>
  <groupId>org.telegram</groupId>
  <artifactId>telegrambots-client</artifactId>
  <version>8.0.0</version>
</dependency>

<dependency>
  <groupId>org.telegram</groupId>
  <artifactId>telegrambots-longpolling</artifactId>
  <version>8.0.0</version>
</dependency>

2.3 核心代码说明

本示例主要由三个类组成：

MyAmazingBot 类：实现了 LongPollingSingleThreadUpdateConsumer 接口，用于处理每个接收到的 Update。
TelegramClientCan 类：封装了 TelegramClient 的消息发送操作。
TelegramBotConfig 类：用于注册 Bot 及初始化相关配置。

2.3.1 MyAmazingBot 类

该类重写了 consume(Update update) 方法，对接收到的 Update 进行处理。示例代码中先将 Update 转换为 JSON 便于日志调试，再检测是否包含文本消息；若包含，则将收到的文本内容原样回传给用户。

java

import org.telegram.telegrambots.longpolling.util.LongPollingSingleThreadUpdateConsumer;
import org.telegram.telegrambots.meta.api.methods.send.SendMessage;
import org.telegram.telegrambots.meta.api.objects.Update;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.example.telegram.utils.TelegramClientCan;

import lombok.extern.slf4j.Slf4j;

@Slf4j
public class MyAmazingBot implements LongPollingSingleThreadUpdateConsumer {

  @Override
  public void consume(Update update) {
    // 将收到的 Update 对象转换为 JSON 字符串，便于调试输出
    try {
      String json = new ObjectMapper().writeValueAsString(update);
      log.info("Received Update JSON: {}", json);
    } catch (JsonProcessingException e) {
      e.printStackTrace();
    }

    // 判断是否为文本消息，并进行回音处理
    if (update.hasMessage() && update.getMessage().hasText()) {
      String receivedText = update.getMessage().getText();
      Long chatId = update.getMessage().getChatId();
      log.info("Received text message: {}", receivedText);

      // 构造回发消息，将接收到的文本原样返回
      SendMessage sendMessage = new SendMessage(chatId.toString(), receivedText);

      // 通过 TelegramClient 发送消息
      TelegramClientCan.execute(sendMessage);
    }
  }
}

2.3.2 TelegramClientCan 类

该类对 TelegramClient 的消息发送功能进行封装，并通过静态成员变量统一调用。异常处理部分也做了简单包装。

java

package com.example.telegram.bots.can;

import org.telegram.telegrambots.meta.api.methods.send.SendMessage;
import org.telegram.telegrambots.meta.api.objects.message.Message;
import org.telegram.telegrambots.meta.exceptions.TelegramApiException;
import org.telegram.telegrambots.meta.generics.TelegramClient;

public class TelegramClientCan {

  public static TelegramClient main;

  public static Message execute(SendMessage sendMessage) {
    try {
      // 调用 TelegramClient 执行发送消息请求
      Message message = main.execute(sendMessage);
      return message;
    } catch (TelegramApiException e) {
      throw new RuntimeException("Failed to send message:", e);
    }
  }
}

2.3.3 TelegramBotConfig 类

该类负责初始化 Bot，注册长轮询应用，并创建 TelegramClient 实例。注意，在实际项目中，请将 YOUR_BOT_TOKEN 替换为真实的 Bot Token。

java

package com.example.telegram.config;

import org.telegram.telegrambots.client.okhttp.OkHttpTelegramClient;
import org.telegram.telegrambots.longpolling.TelegramBotsLongPollingApplication;
import org.telegram.telegrambots.meta.exceptions.TelegramApiException;
import org.telegram.telegrambots.meta.generics.TelegramClient;

import com.example.annotation.AConfiguration;
import com.example.annotation.Initialization;
import com.example.telegram.bots.MyAmazingBot;
import com.example.telegram.utils.TelegramClientCan;
import com.example.server.TioBootServer;
import com.example.utils.environment.EnvUtils;

@AConfiguration
public class TelegramBotConfig {

  @Initialization
  public void config() {
    // 请在此处填写您的 Bot Token（建议使用环境变量管理）
    String botAuthToken = EnvUtils.getStr("telegram.bot.auth.token");

    // 创建 TelegramBotsLongPollingApplication 实例，管理长轮询 Bot 的注册与启动
    TelegramBotsLongPollingApplication botsApplication = new TelegramBotsLongPollingApplication();

    try {
      // 注册自定义 Bot
      botsApplication.registerBot(botAuthToken, new MyAmazingBot());
    } catch (TelegramApiException e) {
      e.printStackTrace();
    }

    // 创建 TelegramClient 实例（使用 OkHttp 实现）
    TelegramClient telegramClient = new OkHttpTelegramClient(botAuthToken);
    TelegramClientCan.main = telegramClient;

    // 注册应用关闭时的清理逻辑，确保资源正常释放
    TioBootServer.me().addDestroyMethod(() -> {
      try {
        botsApplication.close();
      } catch (Exception e) {
        e.printStackTrace();
      }
    });
  }
}

2.4 运行说明

将以上代码保存于项目中相应位置，并确保所有依赖已正确导入。
替换代码中的 YOUR_BOT_TOKEN（或通过环境变量传入）为从 BotFather 获得的真实 Bot Token。
启动 Java 应用。
在 Telegram 中向 Bot 发送消息，此时您将在日志中看到详细的更新（Update）信息，同时 Bot 会将接收到的文本原样回传。

2.5 总结

通过上述示例，您将了解如何：

利用 TelegramBots 库中的长轮询模式接收消息更新；
在回调方法 consume(Update update) 中处理消息内容，并通过 TelegramClient 回发消息；
通过简单的配置类完成 Bot 的注册与启动工作。

在实际应用中，您可进一步扩展逻辑，如指令解析、第三方服务调用或数据库接入，构建功能更丰富的 Telegram Bot 应用。

3. 消息格式说明

Telegram Bot API 返回的 Update 对象中包含各种类型的消息，以下将介绍常见的消息格式，并以脱敏处理后的示例进行说明。

说明：示例中的所有关键数据（如 update_id、message_id、用户/频道 ID、时间戳等）均已使用占位符替换，确保数据安全。

3.1 用户私聊消息

这是用户在私聊中与 Bot 交互时收到的消息示例。包含用户信息、聊天信息及命令消息：

json

{
  "update_id": "<UPDATE_ID>",
  "message": {
    "message_id": "<MSG_ID>",
    "from": {
      "id": "<USER_ID>",
      "first_name": "用户A",
      "is_bot": false,
      "username": "user_a",
      "language_code": "zh-hans"
    },
    "date": <UNIX_TIMESTAMP>,
    "chat": {
      "id": "<USER_ID>",
      "type": "private",
      "first_name": "用户A",
      "username": "user_a"
    },
    "text": "/start",
    "entities": [
      {
        "type": "bot_command",
        "offset": 0,
        "length": 6
      }
    ]
  }
}

3.2 频道命令消息

当消息来自频道时（例如发布命令），更新对象中会包含 channel_post 字段，示例如下：

json

{
  "update_id": "<UPDATE_ID>",
  "channel_post": {
    "message_id": "<MSG_ID>",
    "date": <UNIX_TIMESTAMP>,
    "chat": {
      "id": "<CHANNEL_ID>",
      "type": "channel",
      "title": "示例频道",
      "username": "example_channel"
    },
    "text": "/info",
    "entities": [
      {
        "type": "bot_command",
        "offset": 0,
        "length": 5
      }
    ],
    "sender_chat": {
      "id": "<CHANNEL_ID>",
      "type": "channel",
      "title": "示例频道",
      "username": "example_channel"
    }
  }
}

3.3 频道机器人消息（非用户发送）

在频道中，由机器人自动发送的消息示例如下，注意此类型消息不会携带 from 字段，而是通过 sender_chat 表示消息发送者（即频道本身）：

json

{
  "update_id": "<UPDATE_ID>",
  "channel_post": {
    "message_id": "<MSG_ID>",
    "date": <UNIX_TIMESTAMP>,
    "chat": {
      "id": "<CHANNEL_ID>",
      "type": "channel",
      "title": "示例频道",
      "username": "example_channel"
    },
    "text": "Chat ID: <CHANNEL_SHORT_ID>",
    "sender_chat": {
      "id": "<CHANNEL_ID>",
      "type": "channel",
      "title": "示例频道",
      "username": "example_channel"
    }
  }
}

3.4 频道消息的特殊之处

无 from 字段：频道消息中不包含具体发送者的用户信息，因为消息以频道身份发布。
sender_chat 字段：标识消息发布主体，通常与 chat 字段一致。
作者签名：若频道开启了“签名”功能，消息中可能会包含 author_signature 字段，但不会提供具体用户 ID 信息。

3.5 Callback 数据示例

当用户触发内联回调按钮时，Bot 会收到带有 callback_query 字段的更新：

json

{
  "update_id": "<UPDATE_ID>",
  "callback_query": {
    "id": "<CALLBACK_ID>",
    "from": {
      "id": "<USER_ID>",
      "first_name": "用户A",
      "is_bot": false,
      "username": "user_a",
      "language_code": "zh-hans"
    },
    "message": {
      "message_id": "<MSG_ID>",
      "chat": {
        "id": "<CHAT_ID>",
        "type": "private",
        "first_name": "用户A",
        "username": "user_a"
      },
      "text": "示例文本",
      "entities": [
        /* 相关实体 */
      ],
      "reply_markup": {
        "inline_keyboard": [
          [
            {
              "text": "按钮1",
              "url": "https://t.me/ExampleBot?startchannel=true"
            }
          ],
          [
            {
              "text": "按钮2",
              "callback_data": "action_data"
            }
          ]
        ]
      }
    },
    "data": "action_data",
    "chat_instance": "<CHAT_INSTANCE>"
  }
}

3.6 回复消息示例

Bot 在处理消息回复时，更新对象包含 reply_to_message 字段，示例格式如下：

json

{
  "update_id": "<UPDATE_ID>",
  "message": {
    "message_id": "<NEW_MSG_ID>",
    "chat": {
      "id": "<CHAT_ID>",
      "type": "supergroup",
      "title": "示例群组"
    },
    "text": "不通过",
    "reply_to_message": {
      "message_id": "<ORIGINAL_MSG_ID>",
      "from": {
        "id": "<BOT_ID>",
        "first_name": "示例Bot",
        "is_bot": true,
        "username": "example_bot"
      },
      "text": "审核信息",
      "entities": [
        /* 实体信息 */
      ]
    }
  }
}

3.7 关于群组成员变更更新

通过 my_chat_member 对象，Bot 可获知自身在群组或频道的加入、被踢、权限变更等情况。以下给出两种常见情况的示例：

添加机器人到频道

json

{
  "update_id": "<UPDATE_ID>",
  "my_chat_member": {
    "chat": {
      "id": "<CHANNEL_ID>",
      "type": "channel",
      "title": "示例频道",
      "username": "example_channel"
    },
    "from": {
      "id": "<USER_ID>",
      "first_name": "用户A",
      "is_bot": false,
      "username": "user_a",
      "language_code": "zh-hans"
    },
    "date": <UNIX_TIMESTAMP>,
    "old_chat_member": {
      "status": "left",
      "user": {
        "id": "<BOT_ID>",
        "first_name": "示例Bot",
        "is_bot": true,
        "username": "example_bot"
      }
    },
    "new_chat_member": {
      "status": "administrator",
      "user": {
        "id": "<BOT_ID>",
        "first_name": "示例Bot",
        "is_bot": true,
        "username": "example_bot"
      }
    }
  }
}

从频道删除机器人

json

{
  "update_id": "<UPDATE_ID>",
  "my_chat_member": {
    "chat": {
      "id": "<CHANNEL_ID>",
      "type": "channel",
      "title": "示例频道",
      "username": "example_channel"
    },
    "from": {
      "id": "<BOT_REMOVER_ID>",
      "first_name": "系统",
      "is_bot": true,
      "username": "system_bot"
    },
    "date": <UNIX_TIMESTAMP>,
    "old_chat_member": {
      "status": "administrator",
      "user": {
        "id": "<BOT_ID>",
        "first_name": "示例Bot",
        "is_bot": true,
        "username": "example_bot"
      }
    },
    "new_chat_member": {
      "status": "left",
      "user": {
        "id": "<BOT_ID>",
        "first_name": "示例Bot",
        "is_bot": true,
        "username": "example_bot"
      }
    }
  }
}

判断加入或离开群组的逻辑

一般可以通过对比 old_chat_member.status 与 new_chat_member.status 得到 Bot 的状态变更，例如：

若旧状态为 left 或 kicked，新状态为 member/administrator/creator，则说明 Bot 刚加入群组；
若新状态为 left 或 kicked，则表示 Bot 已离开或被移除。

3.8 转发消息示例

转发文档消息

json

{
  "update_id": "<UPDATE_ID>",
  "message": {
    "message_id": "<MSG_ID>",
    "from": {
      "id": "<USER_ID>",
      "first_name": "用户A",
      "is_bot": false,
      "username": "user_a",
      "language_code": "zh-hans"
    },
    "date": <UNIX_TIMESTAMP>,
    "chat": {
      "id": "<USER_ID>",
      "type": "private",
      "first_name": "用户A",
      "username": "user_a"
    },
    "forward_from": {
      "id": "<USER_ID>",
      "first_name": "用户A",
      "is_bot": false,
      "username": "user_a",
      "language_code": "zh-hans"
    },
    "forward_date": <UNIX_TIMESTAMP>,
    "document": {
      "file_id": "<FILE_ID>",
      "file_unique_id": "<UNIQUE_ID>",
      "file_name": "prompt.txt",
      "mime_type": "text/plain",
      "file_size": 300
    }
  }
}

转发视频消息

json

{
  "update_id": "<UPDATE_ID>",
  "message": {
    "message_id": "<MSG_ID>",
    "from": {
      "id": "<USER_ID>",
      "first_name": "用户A",
      "is_bot": false,
      "username": "user_a",
      "language_code": "zh-hans"
    },
    "date": <UNIX_TIMESTAMP>,
    "chat": {
      "id": "<USER_ID>",
      "type": "private",
      "first_name": "用户A",
      "username": "user_a"
    },
    "forward_from_chat": {
      "id": "<CHANNEL_ID>",
      "type": "channel",
      "title": "素材库"
    },
    "forward_date": <UNIX_TIMESTAMP>,
    "video": {
      "file_id": "<FILE_ID>",
      "file_unique_id": "<UNIQUE_ID>",
      "width": 1920,
      "height": 1080,
      "duration": 1525,
      "thumbnail": { /* 缩略图信息 */ },
      "mime_type": "video/mp4",
      "file_size": 654492317,
      "file_name": "example_video.mp4"
    },
    "caption": "视频说明"
  }
}

转发消息组

转发同一组消息时，多个 Update 会按照顺序分别返回，示例中各消息数据均脱敏：

json

[
  {
    "update_id": "<UPDATE_ID>",
    "message": {
      "message_id": "<MSG_ID1>",
      "from": {
        /* 省略重复信息 */
      },
      "forward_from_chat": {
        "id": "<CHANNEL_ID>",
        "type": "channel",
        "title": "素材频道",
        "username": "channel_username"
      },
      "photo": [
        /* 照片列表信息 */
      ],
      "media_group_id": "<GROUP_ID>"
    }
  },
  {
    "update_id": "<UPDATE_ID>",
    "message": {
      "message_id": "<MSG_ID2>",
      "from": {
        /* 省略重复信息 */
      },
      "forward_from_chat": {
        "id": "<CHANNEL_ID>",
        "type": "channel",
        "title": "素材频道",
        "username": "channel_username"
      },
      "video": {
        /* 视频信息 */
      },
      "media_group_id": "<GROUP_ID>"
    }
  }
]

发送媒体组

发送媒体组时，消息体为数组格式，每个媒体项指定媒体 ID、类型以及可选的说明文字：

json

[
  {
    "media": "<MEDIA_ID_1>",
    "caption": "视频说明",
    "type": "video"
  },
  {
    "media": "<MEDIA_ID_2>",
    "type": "photo"
  },
  {
    "media": "<MEDIA_ID_3>",
    "type": "photo"
  }
]

3.9 关联群组与编辑消息

关联群组的回复消息

当频道与某个讨论群组关联时，频道消息会自动转发到群组，用户在群组中的回复消息示例如下：

json

{
  "update_id": "<UPDATE_ID>",
  "message": {
    "message_id": "<MSG_ID>",
    "chat": {
      "id": "<GROUP_ID>",
      "type": "supergroup",
      "title": "示例群组"
    },
    "text": "回复内容",
    "reply_to_message": {
      "message_id": "<ORIGINAL_MSG_ID>",
      "from": {
        "id": "<BOT_ID>",
        "first_name": "示例Bot",
        "is_bot": true,
        "username": "example_bot"
      }
      /* 省略其他字段 */
    },
    "sender_chat": {
      "id": "<GROUP_ID>",
      "type": "supergroup",
      "title": "示例群组"
    }
  }
}

编辑消息

编辑消息时可能会收到两种更新：

频道原始消息编辑：包含 edited_channel_post 字段，对应频道内的原始消息。
关联群组转发消息编辑：包含 edited_message 字段，对应关联群组中的消息副本。

例如，在群组中编辑后的消息更新示例如下：

群组编辑消息（edited_message）：

json

{
  "update_id": "<UPDATE_ID>",
  "edited_message": {
    "message_id": "<MSG_ID>",
    "chat": {
      "id": "<GROUP_ID>",
      "type": "supergroup",
      "title": "示例群组"
    },
    "text": "编辑后的文本",
    "edit_date": <UNIX_TIMESTAMP>
  }
}

频道编辑消息（edited_channel_post）：

json

{
  "update_id": "<UPDATE_ID>",
  "edited_channel_post": {
    "message_id": "<MSG_ID>",
    "chat": {
      "id": "<CHANNEL_ID>",
      "type": "channel",
      "title": "示例频道"
    },
    "text": "编辑后的文本",
    "edit_date": <UNIX_TIMESTAMP>
  }
}

处理提示
若仅需处理频道原始编辑事件，请监听 edited_channel_post；若需同时处理讨论群中的转发编辑事件，则也可监听 edited_message，并区分消息来源避免重复处理。

4. 总结

本文档从长轮询模式的原理讲解，到 Java 环境下基于 TelegramBots 库的具体实现，再到各类消息更新格式的详细示例，力求为开发者提供一个全面、便捷的参考手册。所有示例中涉及的关键数据均已脱敏，便于安全调试与实际应用。您可以在此基础上根据实际业务需求扩展更多功能，如指令解析、多媒体消息处理以及与第三方系统的集成等。

通过正确配置、注册和处理 Update，您将能构建出响应迅速且功能丰富的 Telegram Bot 应用。希望本指南能助您快速上手并进一步拓展项目。

TelegramBots 入门指南 ​

1. 长轮询模式简介 ​

2. 入门示例 ​

2.1 环境准备 ​

2.2 添加依赖 ​

2.3 核心代码说明 ​

2.3.1 MyAmazingBot 类 ​

2.3.2 TelegramClientCan 类 ​

2.3.3 TelegramBotConfig 类 ​

2.4 运行说明 ​

2.5 总结 ​

3. 消息格式说明 ​

3.1 用户私聊消息 ​

3.2 频道命令消息 ​

3.3 频道机器人消息（非用户发送） ​

3.4 频道消息的特殊之处 ​

3.5 Callback 数据示例 ​

3.6 回复消息示例 ​

3.7 关于群组成员变更更新 ​

添加机器人到频道 ​

从频道删除机器人 ​

判断加入或离开群组的逻辑 ​

3.8 转发消息示例 ​

转发文档消息 ​

转发视频消息 ​

转发消息组 ​

发送媒体组 ​

3.9 关联群组与编辑消息 ​

关联群组的回复消息 ​

编辑消息 ​

4. 总结 ​

TelegramBots 入门指南

1. 长轮询模式简介

2. 入门示例

2.1 环境准备

2.2 添加依赖

2.3 核心代码说明

2.3.1 MyAmazingBot 类

2.3.2 TelegramClientCan 类

2.3.3 TelegramBotConfig 类

2.4 运行说明

2.5 总结

3. 消息格式说明

3.1 用户私聊消息

3.2 频道命令消息

3.3 频道机器人消息（非用户发送）

3.4 频道消息的特殊之处

3.5 Callback 数据示例

3.6 回复消息示例

3.7 关于群组成员变更更新

添加机器人到频道

从频道删除机器人

判断加入或离开群组的逻辑

3.8 转发消息示例

转发文档消息

转发视频消息

转发消息组

发送媒体组

3.9 关联群组与编辑消息

关联群组的回复消息

编辑消息

4. 总结