Telegram机器人使用Webhook接收消息的完整教程

为什么需要Webhook？

在Telegram机器人开发中，接收用户消息有两种主要方式：轮询（getUpdates）和Webhook。轮询需要不断向Telegram服务器发送请求，不仅延迟较高，还会消耗不必要的资源。而Webhook则是Telegram主动将新消息推送到你的服务器，实时性更强，且更节省API调用配额。对于生产环境的机器人，Webhook几乎是最佳选择。

Webhook核心原理

简单来说，你需要在你的服务器上部署一个HTTPS接口，然后通过Telegram的API将机器人绑定到这个接口。当有用户向机器人发送消息时，Telegram会将该消息以JSON格式POST到你的接口。你的接口只需要解析请求体并做出响应，就能实现复杂的业务逻辑。

准备工作

一个Telegram机器人Token（通过BotFather创建）
一台具有公网IP的服务器，且支持HTTPS（必须）
一个已解析到该服务器的域名（Telegram要求Webhook必须使用HTTPS，且证书有效）
Python环境以及python-telegram-bot或requests库

完整配置步骤

1. 设置Webhook

使用以下接口将机器人绑定到你的HTTPS地址：

https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://你的域名/webhook路径

配置成功后，Telegram会返回true。你也可以用Python代码实现：

import requests

token = '123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11'
webhook_url = 'https://example.com/webhook'

resp = requests.post(f'https://api.telegram.org/bot/setWebhook', json={'url': webhook_url})
print(resp.json())

2. 编写Webhook接收服务器

以Flask为例，创建一个简单的HTTP接口：

from flask import Flask, request, jsonify
import requests

app = Flask(__name__)

TOKEN = '123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11'

def send_message(chat_id, text):
    url = f'https://api.telegram.org/bot/sendMessage'
    requests.post(url, json={'chat_id': chat_id, 'text': text})

@app.route('/webhook', methods=['POST'])
def webhook():
    data = request.get_json()
    if 'message' in data:
        chat_id = data['message']['chat']['id']
        text = data['message'].get('text', '')
        send_message(chat_id, f'你发送了：')
    return jsonify({'status': 'ok'})

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8443, ssl_context=('cert.pem', 'key.pem'))

注意：这里使用了self-signed证书，实际生产中建议使用Let's Encrypt，或者使用反向代理（如Nginx）处理HTTPS。

3. 验证Webhook配置

使用getWebhookInfo接口可以查看当前配置状态：

https://api.telegram.org/bot<TOKEN>/getWebhookInfo

返回结果中的pending_update_count表示待处理的更新数量，如果该数字持续增长，说明你的服务器处理速度较慢或出现错误。

安全验证：确保请求来自Telegram

为了防止攻击者伪造请求，Telegram支持一个可选参数secret_token。在设置Webhook时添加该参数，并在你的服务器中验证这个token：

resp = requests.post(f'https://api.telegram.org/bot/setWebhook', json={'url': webhook_url, 'secret_token': '你的自定义密钥'})

然后在Webhook处理器中检查请求头：

from flask import request

secret = '你的自定义密钥'

@app.route('/webhook', methods=['POST'])
def webhook():
    if request.headers.get('X-Telegram-Bot-Api-Secret-Token') != secret:
        return jsonify({'error': 'invalid'}), 403
    # 处理消息...
    return jsonify({'status': 'ok'})

Webhook与getUpdates的对比

对比项	Webhook	getUpdates
实时性	高，Telegram主动推送	低，需轮询间隔
资源消耗	低	高
代码复杂度	中等（需要维护HTTPS服务器）
适用场景	生产环境、高频交互	开发测试、低流量应用

常见问题与排错

Webhook设置失败：检查URL是否为HTTPS，证书是否有效，域名是否解析正确。
收不到消息：查看getWebhookInfo中last_error_message字段。
响应超时：Telegram要求服务器在数秒内返回200，如果处理耗时长，建议先返回'ok'，再异步处理业务。
本地调试：可以使用ngrok等工具将本地端口映射为HTTPS公网地址。

总结

Webhook是Telegram机器人实现高效消息接收的核心机制。通过setWebhook配置HTTPS接口，结合secret_token进行安全验证，你的机器人将具备实时响应、低延迟的优势。推荐在正式项目中使用Python Flask + Nginx + Let's Encrypt的架构，打造稳定可靠的机器人服务。希望本教程能帮你顺利接入Webhook！