Telegram getWebhookInfo: chẩn đoán cập nhật tồn đọng và lỗi webhook

Khi cập nhật từ Telegram webhook có vẻ bị kẹt, hãy kiểm tra getWebhookInfo trước khi đổi cấu hình. pending_update_count là số cập nhật đang chờ chuyển đến hệ thống nhận, không phải số công việc chưa hoàn thành trong ứng dụng. Cần đối chiếu với last_error_date, last_error_message và nhật ký phía nhận. Hàng đợi bằng không không chứng minh quy trình nghiệp vụ đã xong; một lỗi còn lưu trong kết quả cũng không nhất thiết có nghĩa endpoint vẫn đang lỗi.

Điểm chính

• Chẩn đoán webhook hiện tại trước; đổi phương thức nhận cập nhật là thao tác riêng.
• So sánh nhiều lần quan sát và thời điểm lỗi, không kết luận từ một con số.
• Kiểm tra riêng việc nhận yêu cầu, lưu bền vững và xử lý nghiệp vụ.
• Không xóa cập nhật đang chờ chỉ để màn hình giám sát trông bình thường.

getWebhookInfo thực sự cho biết điều gì?

Theo tài liệu Telegram Bot API chính thức, getWebhookInfo không cần tham số và trả về đối tượng WebhookInfo. Gọi bằng client Bot API hiện có trong môi trường đáng tin cậy. Không đưa bot token hoặc webhook URL chứa thông tin nhạy cảm vào nhật ký hay ảnh chụp được chia sẻ.

Trường	Ý nghĩa trong tài liệu	Cách dùng khi chẩn đoán
url	URL webhook; rỗng nếu chưa thiết lập	Xác nhận đích thuộc đúng môi trường
pending_update_count	Số cập nhật đang chờ chuyển	So sánh lượng tồn đọng tăng hay giảm
last_error_date	Tùy chọn: thời gian Unix của lỗi chuyển webhook gần nhất	Kiểm tra lỗi có xảy ra trước khi sửa hay không
last_error_message	Tùy chọn: mô tả dễ đọc của lỗi đó	Chọn hướng kiểm tra, không coi là mã lỗi cố định
ip_address	Tùy chọn: địa chỉ IP webhook hiện đang dùng	Đối chiếu với đích công khai dự kiến
last_synchronization_error_date	Tùy chọn: thời điểm lỗi gần nhất khi đồng bộ cập nhật với trung tâm dữ liệu Telegram	Phân biệt với lỗi không kết nối được hệ thống nhận

Có URL trong cấu hình không chứng minh endpoint truy cập được. Không có trường lỗi tùy chọn cũng không chứng minh CRM hoặc worker đã xử lý xong.

Nếu url rỗng, hãy xác nhận bot này có thực sự cần dùng webhook hay không. Nếu nhiệm vụ là đổi chế độ nhận, xem quy trình chuyển giữa getUpdates và setWebhook. Bài này giữ nguyên webhook để kiểm tra đường chuyển dữ liệu hiện tại.

Đọc lượng tồn đọng cùng thời điểm lỗi

Ghi nhận trạng thái ban đầu, gửi một tin nhắn thử có kiểm soát mà bot phải nhận được, rồi kiểm tra lại. Ghi thời điểm quan sát vào nhật ký vận hành của bạn; đừng coi đó là trường do Telegram trả về.

Quan sát	Có thể cho thấy	Kiểm tra tiếp
Tồn đọng tăng, thời điểm lỗi chuyển tiếp tục cập nhật	Vẫn có lỗi chuyển trong thời gian quan sát	Cổng vào công khai, TLS, định tuyến và nhật ký HTTP response
Tồn đọng giảm, thời điểm lỗi vẫn cũ	Đường chuyển có thể đang phục hồi	Xác nhận cập nhật thử đã được lưu và xử lý
Tồn đọng bằng không nhưng không có hành động nghiệp vụ	Con số không đủ để xác định điểm lỗi	Lưu trữ, hàng đợi nội bộ, worker và quy tắc định tuyến
Vẫn còn tồn đọng nhưng không có lỗi mới	Một lần quan sát chưa đủ kết luận	Kiểm tra lại và đối chiếu lưu lượng phía nhận
Thời điểm lỗi đồng bộ tiếp tục cập nhật	Lỗi được báo thuộc bước đồng bộ cập nhật của Telegram	Lưu bằng chứng; đừng mặc định thay chứng chỉ sẽ giải quyết được

Đây là các nhánh điều tra, không phải chẩn đoán tự động. Tồn đọng giảm cũng không bảo đảm phục hồi đầy đủ: Telegram nêu rõ cập nhật không được giữ quá 24 giờ. Vì vậy, gián đoạn kéo dài có thể tạo khoảng mất dữ liệu, không phải hàng đợi có thể lấy lại vô thời hạn.

Lần theo đường đi của yêu cầu

Dùng mô tả lỗi mới nhất để thu hẹp phạm vi, rồi xác nhận bằng dữ liệu của hệ thống:

1. Đích công khai: đối chiếu host và path với môi trường production. Kiểm tra DNS, định tuyến đầu vào và ip_address nếu có.
2. TLS: kiểm tra hiệu lực chứng chỉ, tên host được bao phủ và chuỗi chứng chỉ thực tế được cung cấp. Hướng dẫn webhook chính thức của Telegram có phần xử lý vấn đề chứng chỉ. Không nới lỏng xác minh để che lỗi cấu hình.
3. Xử lý HTTP: xem trạng thái thực sự trả về tại cổng vào công khai, không chỉ nhật ký ứng dụng. Proxy có thể phản hồi trước khi handler chạy. Mở được trang bằng trình duyệt cũng không chứng minh đường POST của webhook hoạt động.
4. Lưu bền vững: xác nhận cập nhật đã vào kho lưu trữ tin cậy. Thiết kế khuyến nghị là xác thực nguồn yêu cầu, ghi thành công vào hộp thư hoặc hàng đợi bền vững, rồi mới xác nhận đã nhận. Để tác vụ bên ngoài chậm chạy sau đó.
5. Xử lý nghiệp vụ: lần theo cập nhật đã lưu đến worker. Dùng xử lý idempotent để lần chuyển lặp lại không tạo tác dụng phụ trùng lặp.

Telegram ghi rõ sẽ thử lại yêu cầu webhook không thành công khi phản hồi nằm ngoài 2XY, rồi dừng sau số lần thử hợp lý. Đây không phải lịch thử lại cố định được công bố. Đừng hứa thời gian phục hồi dựa trên khoảng thử lại tự suy đoán.

Kiểm tra phục hồi mà không xóa tồn đọng

Sau khi sửa nguyên nhân đã xác nhận, gửi thêm tin nhắn thử có kiểm soát. Kiểm tra đủ chuỗi: yêu cầu đến hệ thống nhận, bản ghi được lưu bền vững và hành động phía sau đúng mong đợi. Theo dõi lượng tồn đọng giảm hay không và có lỗi chuyển mới hay không.

Không dùng drop_pending_updates thay cho sửa lỗi. Theo tài liệu, tham số này loại bỏ cập nhật đang chờ; nó không sửa TLS hoặc worker. Cũng đừng tăng max_connections thiếu căn cứ: đây là số kết nối webhook đồng thời, không phải bảo đảm ứng dụng có thể lưu và xử lý tải tương ứng.

Giữ các khoảng gián đoạn chưa giải thích được trong danh sách cần đối soát. Xác nhận HTTP chỉ cho biết thành công tại ranh giới chuyển dữ liệu đó, không phải toàn bộ quy trình nghiệp vụ đã thành công.

UnifyPort phù hợp ở đâu, và giới hạn là gì?

getWebhookInfo quan sát Telegram Bot API webhook. Nó không kiểm tra hệ thống nhận của UnifyPort, cũng không lấy lại cập nhật tồn đọng của bot thông qua một danh tính khác. Để chọn mô hình nhận tin, xem so sánh Telegram Bot API webhook và webhook đầu vào hợp nhất.

Giao diện không chính thức của UnifyPort dùng hợp đồng sự kiện riêng, gồm message.received. Tài liệu chuyển webhook mô tả X-Device-Event-Id, xác nhận và cơ chế thử lại. Khi cấu hình signing_secret, xác minh X-Device-Signature bằng HMAC-SHA256 trên chuỗi gồm X-Device-Timestamp, một dấu chấm và phần thân yêu cầu nguyên gốc.

Ngay cả khi gom Telegram, Zalo và WhatsApp vào cùng hàng đợi nghiệp vụ, vẫn phải giám sát đường chuyển này riêng với trạng thái Bot API. UnifyPort không có REST API đọc lịch sử tin nhắn và không bảo đảm phát lại payload đã bỏ lỡ; hệ thống nhận vẫn chịu trách nhiệm lưu bền vững. Nếu sản phẩm cần danh tính bot, hãy tiếp tục dùng Bot API chính thức.

Câu hỏi thường gặp

pending_update_count có phải số tin nhắn chưa đọc không?

Không. Đây là số cập nhật đang chờ chuyển, không phải trạng thái chưa đọc trong cuộc trò chuyện hay số công việc chưa xong của ứng dụng.

Còn last_error_message nghĩa là webhook vẫn hỏng?

Không nhất thiết. Nó mô tả lỗi chuyển gần nhất. Hãy đối chiếu thời điểm lỗi với các lần quan sát sau và kiểm thử có kiểm soát xuyên suốt hệ thống.

Tồn đọng bằng không thì có thể kết thúc xử lý sự cố chưa?

Chỉ vậy là chưa đủ. Cần xác nhận việc lưu và xử lý, đồng thời điều tra gián đoạn có thể đã vượt thời hạn giữ cập nhật của Telegram.

Bước tiếp theo và nguồn

Với bot hiện có, kiểm tra getWebhookInfo và lần theo cập nhật thử trước khi đổi thiết lập. Với hệ thống nhận từ tài khoản nhắn tin đã kết nối, bắt đầu bằng hợp đồng chuyển dữ liệu của UnifyPort.

Tài liệu chính thức được kiểm tra ngày 2026-09-18:

• Telegram Bot API: WebhookInfo, setWebhook và Getting updates
• Hướng dẫn xử lý vấn đề Telegram webhook