本文详细阐述了如何在 Telegraf.js 框架下有效接收来自 Telegram Web App 通过 Telegram.WebApp.sendData() 方法发送的数据。核心机制在于，sendData() 触发的是一个标准的 Telegram 消息事件，数据会封装在 ctx.message.web_app_data.data 字段中。文章提供了前端 Web App 和后端 Telegraf.js 的示例代码，并强调了数据解析、错误处理及安全考量等最佳实践。
理解 Telegram Web App 与 Telegraf.js 的数据交互
Telegram Web App 允许开发者在 Telegram 聊天界面内嵌入功能丰富的网页应用。当用户在 Web App 中完成特定操作后，通常需要将一些数据回传给机器人进行处理。Telegram.WebApp.sendData(data) 是 Web App 提供的一个关键方法，用于将数据发送回与之关联的 Telegram 机器人。
对于 Telegraf.js 这样的机器人框架而言，接收这些数据的方式与处理普通用户消息略有不同，但并非完全独立。关键在于，sendData() 方法实际上会触发一个特殊的“消息”事件，该消息的 web_app_data 字段中包含了 Web App 发送的实际数据。
在 Telegraf.js 中接收 Web App 数据
要从 Telegram.WebApp.sendData() 接收数据，Telegraf.js 机器人需要监听常规的 message 事件。不同于一些开发者可能预期的 web_app_data 专用事件，sendData() 产生的数据会作为 message 对象的一部分传递。
在 message 事件的处理函数中，你可以通过 ctx.message.web_app_data 属性来访问 Web App 发送的数据。这个属性本身是一个对象，其中包含一个 data 字段，即为 Web App 通过 sendData() 发送的原始字符串。
示例代码：
首先，在你的前端 Web App 中，你需要使用 Telegram.WebApp.sendData() 发送数据。通常，这些数据会被 JSON 字符串化以便于传输复杂结构。
1. 前端 Web App 代码 (index.html 或 app.js):
Web App 数据发送示例
Telegram Web App 数据发送
点击按钮将数据发送给机器人。
2. 后端 Telegraf.js 机器人代码 (bot.js):
const { Telegraf, Markup } = require('telegraf');
require('dotenv').config(); // 用于加载 .env 文件中的 BOT_TOKEN
const bot = new Telegraf(process.env.BOT_TOKEN);
// 替换为你的 Web App 的实际 URL
const WEB_APP_URL = 'https://your-domain.com/your-web-app-path';
// 处理 /start 命令，提供一个打开 Web App 的按钮
bot.start(async (ctx) => {
ctx.reply('欢迎使用！点击下方按钮打开 Web App 进行操作：', {
reply_markup: Markup.inlineKeyboard([
Markup.button.webApp('打开 Web App', WEB_APP_URL)
])
});
});
// 监听所有消息事件，包括来自 Web App 的数据
bot.on('message', async (ctx) => {
// 检查消息是否包含 web_app_data
if (ctx.message && ctx.message.web_app_data) {
const receivedRawData = ctx.message.web_app_data.data;
console.log('从 Web App 接收到原始数据:', receivedRawData);
try {
// 尝试将接收到的数据解析为 JSON 对象
const parsedData = JSON.parse(receivedRawData);
// 回复用户，显示接收到的数据
await ctx.reply(`已从 Web App 接收到数据：\n\`\`\`json\n${JSON.stringify(parsedData, null, 2)}\n\`\`\``, {
parse_mode: 'MarkdownV2'
});
// 根据接收到的数据执行业务逻辑
if (parsedData.action === 'user_authentication') {
console.log(`用户 ${parsedData.userId} (${parsedData.username}) 已通过 Web App 完成认证。`);
await ctx.reply(`感谢您的认证，${parsedData.username}！`);
// 这里可以进行数据库更新、用户状态管理等操作
} else {
await ctx.reply('接收到未知类型的 Web App 数据。');
}
} catch (e) {
console.error('解析 Web App 数据失败:', e);
await ctx.reply(`从 Web App 接收到非 JSON 格式数据或解析错误：\`${receivedRawData}\``, {
parse_mode: 'MarkdownV2'
});
}
} else if (ctx.message && ctx.message.text) {
// 处理其他类型的文本消息
await ctx.reply(`我收到了您的消息："${ctx.message.text}"`);
} else {
// 处理其他非文本、非 Web App 数据的消息类型
await ctx.reply('我收到了一个消息，但它不是文本或 Web App 数据。');
}
});
// 启动机器人
bot.launch();
// 优雅地停止机器人（处理 SIGINT 和 SIGTERM 信号）
process.once('SIGINT', () => bot.stop('SIGINT'));
process.once('SIGTERM', () => bot.stop('SIGTERM'));注意事项与最佳实践
- 数据格式化： Telegram.WebApp.sendData() 接收的是一个字符串。如果需要发送复杂的对象，务必在前端使用 JSON.stringify() 将其转换为 JSON 字符串，并在后端使用 JSON.parse() 进行解析。
- 错误处理： 在后端解析数据时，始终使用 try...catch 块来处理 JSON.parse() 可能抛出的错误，以应对前端发送了无效 JSON 字符串的情况。
- 数据验证： 从 Web App 接收到的数据应被视为用户输入，必须进行严格的验证和清理，以防止安全漏洞（如 SQL 注入、XSS 等）。
- 用户反馈： 机器人接收到数据并处理后，应及时给用户一个反馈，告知数据已收到并处理，提升用户体验。
- Web App URL 配置： 确保 WEB_APP_URL 变量指向你的实际 Web App 地址，并且该 URL 已在 BotFather 中配置为你的 Web App 域名。
- initDataUnsafe 的使用： 在 Web App 中，window.Telegram.WebApp.initDataUnsafe 包含了启动 Web App 的用户信息，可以用于在发送数据时附带用户身份信息，方便后端进行关联。但请注意，initDataUnsafe 并非完全安全，其数据应在后端进行哈希校验以确保未被篡改。
总结
通过上述方法，Telegraf.js 开发者可以有效地从 Telegram Web App 接收数据，实现机器人与 Web App 之间的双向通信。核心在于理解 Telegram.WebApp.sendData() 会触发一个带有 web_app_data 字段的常规 message 事件，并在此事件处理器中正确地解析和处理数据。遵循最佳实践，可以确保数据传输的健壮性和安全性。
