Telegram có thể gửi webhook bot trực tiếp đến localhost không?

Không. Telegram không thể định tuyến các yêu cầu đến localhost hoặc địa chỉ mạng LAN riêng. Sử dụng đường hầm HTTPS công cộng để chuyển tiếp yêu cầu đến máy chủ bot cục bộ của bạn.

Làm cách nào để xác thực các yêu cầu webhook của bot Telegram?

Chuyển một secret_token ngẫu nhiên tới setWebhook và so sánh tiêu đề X-Telegram-Bot-Api-Secret-Token của mọi yêu cầu với giá trị đó bằng cách sử dụng so sánh an toàn về thời gian.

Tại sao webhook Telegram của tôi nhận được các bản cập nhật trùng lặp?

Telegram thử lại việc gửi hàng không thành công. Trả lại 2xx nhanh chóng và loại bỏ công việc trùng lặp bằng update_id để các lần thử lại không thể lặp lại tác dụng phụ.

Tôi có thể sử dụng getUpdates khi webhook Telegram đang hoạt động không?

Không. API Bot của Telegram không cho phép getUpdates trong khi webhook gửi đi được định cấu hình. Xóa webhook trước khi quay lại bỏ phiếu dài.

Kiểm thử webhook bot Telegram trên localhost

Để kiểm tra webhook bot Telegram trên localhost, hãy hiển thị máy chủ cục bộ của bạn bằng đường hầm HTTPS công cộng, gọi setWebhook bằng URL đó và xác thực tiêu đề mã thông báo bí mật của Telegram cho mọi yêu cầu. Điều này cung cấp cho bạn thông báo thực, truy vấn gọi lại và cập nhật thành viên mà không cần triển khai sau mỗi lần thay đổi mã. Vòng lặp hoàn chỉnh là: chạy trình xử lý bot, bắt đầu npx portpreview 3000, đăng ký URL kết quả, gửi tin nhắn cho bot của bạn và kiểm tra yêu cầu cục bộ.

Tại sao Telegram không thể gửi cập nhật trực tiếp tới localhost

API Bot của Telegram gửi các bản cập nhật webhook từ cơ sở hạ tầng Telegram tới một URL có thể truy cập được trên Internet. localhost, 127.0.0.1 và các địa chỉ mạng LAN riêng không thể định tuyến được từ cơ sở hạ tầng đó. Đường hầm localhost chấm dứt HTTPS tại một địa chỉ công cộng và chuyển tiếp yêu cầu HTTP không thay đổi tới cổng cục bộ của bạn.

Các bot Telegram có thể nhận thông tin cập nhật theo hai cách loại trừ lẫn nhau: bỏ phiếu dài thông qua getUpdates hoặc webhooks. Tham chiếu chính thức setWebhook nêu rõ rằng getUpdates không khả dụng khi webhook gửi đi được định cấu hình. Nếu quá trình bỏ phiếu vẫn đang chạy, hãy dừng quá trình đó trước khi đánh giá luồng webhook.

Xây dựng điểm cuối webhook cục bộ

Ví dụ Express này giữ cho trình xử lý có kích thước nhỏ một cách có chủ ý. Nó kiểm tra bí mật được chia sẻ trước khi chạm vào bản cập nhật, xác nhận nhanh chóng và di chuyển công việc ra ngoài đường dẫn phản hồi.

import express from 'express';
import crypto from 'node:crypto';

const app = express();
app.use(express.json({ limit: '1mb' }));

function sameSecret(received = '', expected = '') {
  const a = Buffer.from(received);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post('/webhooks/telegram', (req, res) => {
  const received = req.get('x-telegram-bot-api-secret-token') || '';
  if (!sameSecret(received, process.env.TELEGRAM_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }

  const update = req.body;
  res.sendStatus(200);
  queueMicrotask(() => handleUpdate(update));
});

app.listen(3000, () => console.log('Listening on http://localhost:3000'));

Telegram gửi một Update được tuần tự hóa JSON. Không giống như các nhà cung cấp dựa trên HMAC, tính năng secret_token của Telegram không ký vào phần thân. Nó đặt giá trị bạn đã chọn vào X-Telegram-Bot-Api-Secret-Token. Mã thông báo chứng minh rằng người gửi biết giá trị được sử dụng khi webhook được đăng ký nhưng không cung cấp thông báo tải trọng. TLS bảo vệ yêu cầu trong quá trình chuyển tiếp.

Hiển thị điểm cuối bằng HTTPS

Khởi động ứng dụng và xác nhận curl -i http://localhost:3000/webhooks/telegram đến máy chủ, ngay cả khi GET trả về 404.
Mở thiết bị đầu cuối thứ hai và chạy npx portpreview 3000.
Sao chép nguồn gốc HTTPS công khai và nối thêm /webhooks/telegram.
Giữ quá trình đường hầm chạy trong khi Telegram cung cấp các bản cập nhật.

API Bot chấp nhận URL webhook HTTPS. Tài liệu Telegram hỗ trợ webhook trên các cổng 443, 80, 88 và 8443; điểm cuối công cộng của đường hầm được quản lý thường sử dụng 443 ngay cả khi quy trình cục bộ được chuyển tiếp lắng nghe trên 3000.

Đăng ký webhook Telegram một cách an toàn

Tạo một bí mật ngẫu nhiên chỉ chứa các chữ cái, chữ số, dấu gạch dưới hoặc dấu gạch nối. Telegram cho phép 1–256 ký tự. Không sử dụng lại mã thông báo bot làm giá trị này.

export TELEGRAM_WEBHOOK_SECRET="$(openssl rand -hex 32)"

curl -sS -X POST \
  "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook" \
  -d "url=https://YOUR-TUNNEL.portpreview.dev/webhooks/telegram" \
  -d "secret_token=${TELEGRAM_WEBHOOK_SECRET}" \
  -d 'allowed_updates=["message","callback_query"]' \
  -d "drop_pending_updates=true"

allowed_updates giảm tiếng ồn và chỉ nên liệt kê các loại cập nhật mà bot xử lý. drop_pending_updates=true rất hữu ích khi bắt đầu một phiên cục bộ mới nhưng nó sẽ loại bỏ vĩnh viễn các bản cập nhật được xếp hàng đợi, vì vậy hãy bỏ qua nó khi những sự kiện đó quan trọng. Tài liệu cập nhật của Telegram mô tả các trường như message, callback_query và my_chat_member.

Xác nhận đăng ký trước khi gỡ lỗi mã

Sử dụng getWebhookInfo để phân biệt lỗi cấu hình với lỗi trình xử lý:

curl -sS "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getWebhookInfo"

Kiểm tra url, pending_update_count, last_error_message và last_error_date. URL trống có nghĩa là đăng ký không thành công. Số lượng đang chờ xử lý ngày càng tăng thường có nghĩa là Telegram không thể kết nối hoặc điểm cuối của bạn trả về trạng thái không phải 2xx. Gửi tin nhắn trực tiếp tới bot sau khi đăng ký; chỉ mở cuộc trò chuyện không nhất thiết tạo ra bản cập nhật.

Xử lý cập nhật mà không phải thử lại

Xác nhận trước khi làm việc chậm

Trả lại phản hồi 2xx ngay khi yêu cầu được xác thực và được chấp nhận lâu dài. Xuất cơ sở dữ liệu, lệnh gọi AI và API của bên thứ ba sẽ chạy không đồng bộ. Telegram thử lại các yêu cầu không thành công sau các phản hồi không phải 2xx, vì vậy công việc đồng bộ chậm có thể tạo ra các yêu cầu trùng lặp.

Không trùng lặp với update_id

Mỗi bản cập nhật đều có update_id. Lưu trữ các ID đã xử lý có thời hạn hết hạn hoặc thực thi khóa cơ sở dữ liệu duy nhất. Lần thử lại không được gửi biên lai thanh toán thứ hai, tạo vé trùng lặp hoặc thực hiện cùng một lệnh gọi lại hai lần.

Mô hình hóa mọi loại cập nhật một cách rõ ràng

Không phải mọi bản cập nhật đều chứa message.text. Các nút gọi lại nằm dưới callback_query; bài đăng kênh và thay đổi thành viên có các lĩnh vực khác. Phân nhánh trên trường cấp cao nhất hiện tại và coi các loại không xác định là không hoạt động hợp lệ thay vì ném.

Quy tắc bảo mật để thử nghiệm bot Telegram địa phương

Xác thực tiêu đề bí mật trước. Từ chối các giá trị bị thiếu hoặc không chính xác trước khi ghi nhật ký hoặc phân tích cú pháp các trường nhạy cảm.
Giữ mã thông báo khỏi URL và nhật ký. Mã thông báo Bot API trong lệnh đăng ký là thông tin xác thực. Tránh lịch sử shell trên các hệ thống dùng chung và xoay mã thông báo bị lộ thông qua BotFather.
Sử dụng một tuyến đường không thể đoán được và bí mật. Tuyến đường này có chiều sâu phòng thủ; tiêu đề bí mật là kiểm tra ứng dụng thực tế.
Giới hạn dữ liệu được ghi. Tin nhắn có thể chứa tên, tên người dùng, số điện thoại, tệp và văn bản cuộc trò chuyện riêng tư. Biên tập lại nhật ký và xóa các ảnh chụp cục bộ khi hoàn tất.
Không bao giờ tắt xác thực trong quá trình phát triển. Đường hầm công cộng là công khai. Mã địa phương phải thực hiện các bước kiểm tra tương tự như mã sản xuất.

Xem hướng dẫn bảo mật đường hầm localhost rộng hơn để biết các phương pháp kiểm soát truy cập và lưu giữ dữ liệu.

Khắc phục sự cố webhook Telegram phổ biến

Telegram báo lỗi chứng chỉ hoặc kết nối

Sử dụng URL HTTPS của đường hầm, không phải mục tiêu HTTP cục bộ của nó. Xác nhận đường hầm đang hoạt động và URL không thay đổi. Thay vào đó, nếu bạn cung cấp chứng chỉ tự ký của riêng mình, Telegram sẽ yêu cầu tải chứng chỉ công khai lên dưới dạng tệp; điểm cuối TLS được quản lý sẽ tránh thiết lập đó.

Điểm cuối trả về 401

So sánh bí mật được truyền cho setWebhook với biến môi trường được quy trình sử dụng. Tên tiêu đề không phân biệt chữ hoa chữ thường, nhưng proxy hoặc phần mềm trung gian có thể loại bỏ các tiêu đề tùy chỉnh. Kiểm tra các tiêu đề đến mà không in giá trị bí mật.

Không có yêu cầu nào đến

Chạy getWebhookInfo, xác minh đường dẫn đã đăng ký khớp chính xác với tuyến đường của bạn và đảm bảo không có tường lửa nào chặn kết nối cục bộ của đường hầm. Nếu gần đây bạn đã sử dụng tính năng thăm dò ý kiến, hãy xác nhận rằng URL webhook hiện đã được điền. Kích hoạt bản cập nhật thực tế bằng cách nhắn tin cho bot.

Các bản cập nhật liên tục được gửi đến

Trạng thái nhật ký và thời gian phản hồi. Các trường hợp ngoại lệ sau khi nhận được yêu cầu có thể biến 200 dự định thành 500. Trả lại 200 ngay lập tức, xử lý bình thường và sử dụng phát lại webhook được kiểm soát thay vì đợi nhà cung cấp thử lại trong quá trình gỡ lỗi.

Kiểm tra các tệp và truy vấn gọi lại, không chỉ văn bản

Một ma trận kiểm tra bot hữu ích bao gồm hơn message.text. Gửi ảnh có chú thích, chia sẻ liên hệ, chỉnh sửa tin nhắn và nhấn nút bàn phím nội tuyến. Đối với các truy vấn gọi lại, hãy gọi ngay answerCallbackQuery để khách hàng ngừng hiển thị chỉ báo tiến trình, sau đó thực hiện công việc chậm hơn một cách riêng biệt. Cập nhật tệp chứa số nhận dạng; tải xuống byte là thao tác Bot API thứ hai và không được làm trì hoãn phản hồi webhook.

Giữ các thiết bị cố định được tạo từ các bản cập nhật đã được dọn dẹp cho các thử nghiệm đơn vị nhưng vẫn giữ nguyên đường dẫn truyền tải đầy đủ cho ít nhất một thử nghiệm của từng loại được hỗ trợ. Một thiết bị cố định chứng tỏ người điều phối của bạn hiểu được trọng tải; việc phân phối theo đường hầm thực sự cũng chứng minh hành vi đăng ký, TLS, tiêu đề, phân tích nội dung và xác nhận. Khi thêm mục nhập allowed_updates mới, hãy gọi lại setWebhook và xác minh getWebhookInfo phản ánh cấu hình dự định.

Xóa webhook sau phiên cục bộ

curl -sS -X POST \
  "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/deleteWebhook" \
  -d "drop_pending_updates=false"

Việc xóa webhook cho phép bạn quay lại getUpdates. Nếu URL đường hầm thay đổi trong phiên tiếp theo, hãy gọi lại setWebhook. Để có chẩn đoán bổ sung, hãy làm theo quy trình chung quy trình gỡ lỗi webhook cục bộ.