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 配置示例，添加所需依赖：
<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 便于日志调试，再检测是否包含文本消息；若包含，则将收到的文本内容原样回传给用户。
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 的消息发送功能进行封装，并通过静态成员变量统一调用。异常处理部分也做了简单包装。
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。
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 交互时收到的消息示例。包含用户信息、聊天信息及命令消息：
{
"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 字段，示例如下：
{
"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 表示消息发送者（即频道本身）：
{
"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 字段的更新：
{
"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 字段，示例格式如下：
{
"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 可获知自身在群组或频道的加入、被踢、权限变更等情况。以下给出两种常见情况的示例：
添加机器人到频道
{
"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"
}
}
}
}
从频道删除机器人
{
"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 转发消息示例
转发文档消息
{
"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
}
}
}
转发视频消息
{
"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 会按照顺序分别返回，示例中各消息数据均脱敏：
[
{
"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、类型以及可选的说明文字：
[
{
"media": "<MEDIA_ID_1>",
"caption": "视频说明",
"type": "video"
},
{
"media": "<MEDIA_ID_2>",
"type": "photo"
},
{
"media": "<MEDIA_ID_3>",
"type": "photo"
}
]
3.9 关联群组与编辑消息
关联群组的回复消息
当频道与某个讨论群组关联时，频道消息会自动转发到群组，用户在群组中的回复消息示例如下：
{
"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）：{ "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）：{ "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 应用。希望本指南能助您快速上手并进一步拓展项目。