← Tất cả bài viết
Hướng dẫn

Telegram getUpdates và setWebhook bị xung đột: runbook chuyển đổi an toàn

Telegram Bot API có một quy tắc quan trọng: cùng một bot không nên nhận updates bằng cả polling getUpdates và push setWebhook cùng lúc. Nếu sau khi deploy, tin nhắn không vào hệ thống, hãy kiểm tra receiver nào đang hoạt động trước. Sau đó bạn mới quyết định xóa webhook để quay lại polling, hoặc dừng polling worker trước khi đặt webhook. Với đội ở Việt Nam đang dùng cả WhatsApp, Zalo và Telegram, hãy tách rõ bài toán Bot API với bài toán inbox đa kênh.

Điểm chính

  • getUpdates và setWebhook là hai chế độ nhận updates chính thức của Telegram Bot API, không phải hai lớp chạy song song.
  • Gọi getWebhookInfo trước khi thay đổi; nó cho biết webhook URL có còn được đặt hay không.
  • Nếu quay lại polling, gọi deleteWebhook và quyết định cẩn thận về drop_pending_updates.
  • Nếu bạn vẫn đang chọn kiến trúc nhận tin, đọc Telegram Bot API webhook vs unified inbound webhook trước.
  • Nếu vấn đề nằm ở credential, bắt đầu với Telegram API ID/API hash vs bot token.

Ranh giới từ tài liệu chính thức

Tài liệu Bot API của Telegram mô tả hai cách nhận updates: getUpdates là long polling từ ứng dụng của bạn đến Telegram; webhook là Telegram gửi HTTPS request đến URL của bạn. Cùng tài liệu đó nói rằng bạn không thể nhận updates bằng getUpdates khi outgoing webhook còn được cấu hình; để quay lại polling, dùng deleteWebhook.

Dấu hiệuTrạng thái có thểKiểm tra đầu tiên
Polling không trả về tin nhắnWebhook URL vẫn tồn tạigetWebhookInfo
Webhook endpoint không có requestPolling worker cũ còn chạy, hoặc webhook đặt chưa đúngDừng worker rồi kiểm tra
Queue nội bộ bị trùng hoặc mấtNhiều instance xử lý cùng một luồngChọn một owner
Tin nhắn test cũ xuất hiện sau chuyển đổiPending updates được giữ lạiQuyết định xử lý hay xóa

Bước 1: kiểm tra receiver hiện tại

Đặt BOT_TOKEN trong environment variable và không ghi vào log:

curl "https://api.telegram.org/bot$BOT_TOKEN/getWebhookInfo"

Nếu url trong response không rỗng, webhook vẫn được cấu hình. Nếu url rỗng, Bot API webhook không bật và getUpdates có thể là đường nhận hiện tại.

Bước 2: chuyển từ webhook về getUpdates

Trước tiên xóa webhook:

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

Với tin nhắn hỗ trợ khách hàng, thường nên để false và cho một polling worker xử lý idempotent. Chỉ dùng true khi backlog là traffic test hoặc đội sản phẩm đã quyết định cắt sạch.

Sau đó chỉ chạy một polling worker và cập nhật offset sau mỗi response của getUpdates:

curl "https://api.telegram.org/bot$BOT_TOKEN/getUpdates?timeout=30"

Bước 3: chuyển từ getUpdates sang setWebhook

Dừng polling worker trước. Sau đó đặt URL do production service của bạn quản lý:

curl -X POST "https://api.telegram.org/bot$BOT_TOKEN/setWebhook" \
  -d "url=https://support.example.com/telegram/bot-webhook"

Endpoint nên phản hồi nhanh: lưu Telegram update trước, rồi để CRM, AI routing hoặc phân công nhân viên chạy bất đồng bộ. Nguyên tắc store-first này giống webhook-first inbound integration checklist, dù Telegram Update và UnifyPort event schema khác nhau.

Khi nào dùng unified inbound webhook

Runbook này xử lý việc nhận updates cho Telegram bot. Nó không biến bot thành inbox của tài khoản Telegram thông thường, và không tự chuẩn hóa WhatsApp, LINE, TikTok, Zalo hoặc X.

Nếu đội của bạn cần một event layer chung cho hỗ trợ đa kênh, hãy tạo webhook trong UnifyPort. Tài liệu sâu là Create webhook endpoint: đặt HTTPS url, status: "active", subscribe message.received hoặc ["*"], và dùng signing_secret khi cần kiểm tra X-Device-Signature.

{
  "id": "evt_b1a7c3e5f8",
  "type": "message.received",
  "provider": "telegram",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T12:37:00Z",
  "data": {
    "conversation": { "id": "5005", "type": "user" },
    "sender": { "id": "4004", "type": "user", "name": "Jordan Lee" },
    "message": { "id": "3003", "direction": "inbound", "sent_at": "2026-06-08T12:37:00Z", "text": "Can you check my order?" },
    "event": { "kind": "message_received" }
  }
}

Dùng Bot API chính thức khi người dùng nên nói chuyện với bot identity và bạn cần Telegram Update. Dùng unofficial interface của UnifyPort khi mục tiêu là inbound intake từ tài khoản đã kết nối hoặc queue đa nền tảng.

FAQ

Có thể dùng getUpdates và setWebhook cùng lúc không?

Không. Telegram mô tả chúng là hai cách nhận updates loại trừ nhau cho Bot API bot. Xóa webhook trước khi polling, hoặc dừng polling trước khi đặt webhook.

Có nên đặt drop_pending_updates=true không?

Chỉ khi pending updates có thể bỏ. Với tin nhắn hỗ trợ production, hãy giữ lại và xử lý idempotent.

Đây có phải kết nối tài khoản Telegram thông thường không?

Không. Bot API dùng bot token. Khi kết nối tài khoản Telegram qua UnifyPort, bạn nhận event chuẩn hóa message.received.

Sources checked on 2026-09-09

UnifyPort API

Biến tích hợp nhắn tin thành một pipeline sản phẩm ổn định.

Bắt đầu bằng cách gửi qua một API, rồi đưa mọi tin nhắn inbound trở lại hệ thống kinh doanh bằng sự kiện chuẩn.

Lấy API KeyXem tham chiếu API