Telegram Bot设置Webhook到自有服务器完整步骤

在开发Telegram Bot时，获取更新消息的方式主要有两种：长轮询（Long Polling）和Webhook。相比长轮询，Webhook更为高效——当有新消息时，Telegram服务器会主动将更新请求推送到你指定的URL，从而显著降低延迟和服务器资源消耗。本文将手把手教你如何将Telegram Bot的Webhook设置到自有服务器，涵盖从准备工作到安全验证的完整流程，并提供可直接运行的代码示例。

什么是Webhook及其工作原理

Webhook（网络钩子）是一种基于HTTP的回调机制。对于Telegram Bot而言，当你为Bot设置Webhook后，Telegram服务器会在新更新（如用户发送消息、点击按钮等）产生时，立即向你的服务器指定的URL发送一个HTTP POST请求，请求体为JSON格式的Update对象。你的服务器只需接收并处理该请求即可，无需不断调用getUpdates方法轮询。

与长轮询相比，Webhook的优点在于实时性更强、服务器负载更低，尤其适合生产环境。但前提是你必须拥有一个公网可访问的HTTPS地址（Telegram要求Webhook必须使用HTTPS，除非你使用自签名证书并向Telegram上传公钥）。

准备工作：创建Bot与服务器环境

在开始设置Webhook之前，需要确保以下准备工作已完成：

创建Bot并获取Token：在Telegram中向@BotFather发送 /newbot 命令，按照提示设置Bot名称和用户名，即可获得一个API Token（形如 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11），请妥善保管。
准备服务器：你需要一台具备公网IP的服务器（云服务器或VPS均可），并安装好Web服务器环境（如Nginx、Apache）或应用框架（如Node.js、Python Flask、PHP等）。确保服务器支持HTTPS。
域名与HTTPS证书：推荐为你的服务器绑定一个域名，并申请受信任的SSL证书（如Let's Encrypt免费证书）。如果你没有域名或证书，也可以使用自签名证书，但后续设置时需要向Telegram上传公钥文件。
开放端口：确保服务器防火墙允许HTTP（80）和HTTPS（443）端口的外部访问，且你的Webhook URL路径可被外部访问。

使用setWebhook方法绑定Webhook地址

Telegram Bot API提供了 setWebhook 方法用于设置或更新Webhook地址。调用方式非常简单，你只需发起一个HTTP GET或POST请求到以下URL（推荐使用POST以便传递更多参数）：

https://api.telegram.org/bot<TOKEN>/setWebhook?url=<WEBHOOK_URL>

其中 <TOKEN> 是你在BotFather获取的API Token，<WEBHOOK_URL> 是你服务器的HTTPS地址，例如 https://yourdomain.com/telegram-bot。

你可以使用 curl 命令快速完成设置：

curl -F "url=https://yourdomain.com/telegram-bot" \
     -F "max_connections=40" \
     -F "allowed_updates=[\"message\",\"callback_query\"]" \
     https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/setWebhook

常用的可选参数包括：

max_connections：最大连接数，默认40，范围为1~100。
allowed_updates：允许的更新类型，例如消息、回调查询等，可减少不必要的请求。
secret_token：自定义密钥，用于验证请求来源，在后续安全设置中会用。
certificate：自签名证书的公钥文件，仅在使用自签名证书时需要上传。

编写服务器端回调处理程序

设置好Webhook后，你的服务器需要能够接收并响应Telegram发来的POST请求。下面分别以Python Flask和PHP为例，演示如何编写简单的回调处理程序。

Python Flask示例

首先安装Flask：pip install flask，然后创建 app.py：

from flask import Flask, request
import json

app = Flask(__name__)

# 返回的Webhook URL路径必须与setWebhook时一致
@app.route('/telegram-bot', methods=['POST'])
def webhook():
    update = request.get_json()
    if 'message' in update:
        chat_id = update['message']['chat']['id']
        text = update['message'].get('text', '')
        print(f"收到来自  的消息: ")
        # 你可以在这里调用Bot API发送回复，例如使用requests库
        # requests.post(f'https://api.telegram.org/bot/sendMessage', json={'chat_id': chat_id, 'text': '收到'})
    return 'OK', 200

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

注意：如果使用自签名证书，需要将证书文件与私钥放置到服务器，并在部署时指定。生产环境建议使用gunicorn或uWSGI。

PHP示例

在服务器上创建 webhook.php，内容如下：

<?php
$update = json_decode(file_get_contents('php://input'), true);
if (isset($update['message'])) {
    $chat_id = $update['message']['chat']['id'];
    $text = $update['message']['text'] ?? '';
    file_put_contents('log.txt', "$chat_id: $text\n", FILE_APPEND);
    // 可选：调用Bot API回复
    // file_get_contents("https://api.telegram.org/botTOKEN/sendMessage?chat_id=$chat_id&text=收到");
}
http_response_code(200);
?>

确保Web服务器已将请求转发至该PHP文件，并正确配置HTTPS。

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

出于安全考虑，你必须验证收到的POST请求确实来自Telegram，而不是恶意伪造。常用方法有以下几种：

使用secret_token：在调用 setWebhook 时设置一个自定义 secret_token，Telegram会在每个请求头 X-Telegram-Bot-Api-Secret-Token 中携带该值。你只需要在服务器端校验该请求头是否匹配即可。
限制IP地址：Telegram官方公布了Bot API服务器的IP段，你可以在网关卡或应用层只允许这些IP访问你的Webhook地址。IP段列表可从 https://core.telegram.org/bots/webhooks 获取。
自签名证书验证：如果你使用自签名证书，Telegram会携带证书公钥，服务器可进行双向TLS验证，但实现较复杂。更简单的做法是使用上述secret_token方式。

示例：在Flask中校验secret_token：

from flask import request, abort
import os

SECRET_TOKEN = os.environ.get('BOT_SECRET_TOKEN', 'my_secret')

@app.route('/telegram-bot', methods=['POST'])
def webhook():
    token = request.headers.get('X-Telegram-Bot-Api-Secret-Token')
    if token != SECRET_TOKEN:
        abort(401)
    # 继续处理...
    return 'OK'

常见问题与调试技巧

1. 如何查看当前Webhook的设置状态？
调用 getWebhookInfo 方法即可获得当前Webhook的URL、是否发生错误等信息：
curl https://api.telegram.org/bot/getWebhookInfo

2. 如何删除Webhook？
使用 deleteWebhook 方法：
curl https://api.telegram.org/bot/deleteWebhook

3. 设置Webhook后收不到更新？
首先通过 getWebhookInfo 查看 last_error_message，常见错误有：证书无效、URL无法访问等。确保你的HTTPS地址从外网可以访问（可使用在线工具测试），且路径与setWebhook时完全一致。

4. 本地调试Webhook
如果你的服务器在本地或内网，可以使用内网穿透工具（如ngrok）生成临时公网HTTPS地址，将Webhook指到该地址进行测试。注意使用免费域名时Telegram可能会拒绝，建议使用付费或自建转发。

总结

通过Webhook方式接入Telegram Bot，不仅提升了实时性，也降低了服务器轮询压力。本文为你完整展示了从创建Bot到服务器端处理程序以及安全验证的全过程。记住，设置Webhook只是第一步，在实际开发中你还需要根据业务需求解析不同类型的Update，并通过Bot API进行回复。希望这篇指南能帮助你快速上手，构建出稳定、安全的Bot服务。

Telegram Bot设置Webhook到自有服务器完整步骤

什么是Webhook及其工作原理

准备工作：创建Bot与服务器环境

使用setWebhook方法绑定Webhook地址

编写服务器端回调处理程序

Python Flask示例

PHP示例

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

常见问题与调试技巧

总结

Telegram 中文版下载

多平台客户端选择

常见问题

延伸阅读