Kết nối tài khoản người dùng Telegram với webhook: mã đăng nhập và QR

Để kết nối một tài khoản người dùng Telegram hiện có với webhook, trước tiên hãy lấy api_id và api_hash cho ứng dụng của bạn, đăng ký webhook trước khi xác thực, tạo messaging account Telegram trong UnifyPort, rồi hoàn tất luồng bằng mã hoặc QR. Đăng nhập bằng mã cần số điện thoại và có thể yêu cầu mật khẩu xác thực hai bước. QR vẫn cần thông tin API, nhưng chủ tài khoản phê duyệt đăng nhập trong ứng dụng Telegram đã đăng nhập sẵn.

Điểm chính

• Tài khoản người dùng dùng api_id và api_hash, không dùng bot token của BotFather.
• Hãy tạo webhook trước để có nơi nhận trạng thái xác thực và tin nhắn mới.
• Chọn auth_mode: "code" khi người vận hành có thể nhập mã Telegram; chọn auth_mode: "qrcode" khi phê duyệt từ ứng dụng hiện có thuận tiện hơn.
• api_hash, mã đăng nhập, mật khẩu hai bước, nội dung QR, API key và signing_secret đều là bí mật.
• Sau khi xác thực, chỉ xử lý message.received đã kiểm tra chữ ký và có hướng inbound.

Nếu chưa rõ mô hình thông tin xác thực, hãy đọc Telegram API ID/API hash so với bot token trước.

Toàn bộ quy trình thiết lập webhook cho tài khoản Telegram

Kiến trúc có bốn ranh giới: thông tin ứng dụng Telegram, endpoint do bạn kiểm soát, messaging account trong UnifyPort và bước xác thực cần chủ tài khoản thao tác. Tách riêng bốn phần giúp chẩn đoán lỗi chính xác hơn.

1. Tạo thông tin ứng dụng Telegram của riêng bạn

Hướng dẫn tạo ứng dụng chính thức của Telegram nêu rằng xác thực người dùng cần api_id và api_hash. Hãy tạo chúng qua API development tools tại my.telegram.org, lưu hash trong trình quản lý bí mật và không đưa vào repository hoặc log.

Đây là mô hình khác với Bot API. Telegram mô tả Bot API chính thức là HTTP interface dành cho bot. Nếu bạn cần một danh tính bot riêng và tính năng đặc thù của bot, hãy dùng con đường chính thức đó. Nếu cần kết nối tài khoản người dùng hiện có hoặc đưa Telegram vào cùng bộ xử lý tin nhắn đến của nhiều kênh, luồng giao diện không chính thức trong bài này phù hợp hơn.

Nếu dự án đang dùng application ID mẫu hoặc đã bị công khai, hãy xác minh nguồn trước. Checklist khôi phục API_ID_PUBLISHED_FLOOD trình bày cách thay thông tin không phù hợp mà không để lộ giá trị mới.

2. Đăng ký webhook có chữ ký trước khi đăng nhập

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ị bỏ lỡ. Vì vậy, endpoint nhận phải sẵn sàng trước và lưu dữ liệu cần thiết ngay khi sự kiện đến.

curl -X POST https://api.unifyport.ai/v1/webhook-endpoints \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"url\": \"$PUBLIC_WEBHOOK_URL\",
    \"status\": \"active\",
    \"subscribed_events\": [\"message.received\", \"account.auth.required\", \"account.auth.succeeded\", \"account.auth.failed\", \"account.status.updated\"],
    \"signing_secret\": \"$WEBHOOK_SIGNING_SECRET\"
  }"

Xem hợp đồng request tại Create webhook endpoint. Khi bật chữ ký, hãy kiểm tra X-Device-Signature: đây là HMAC-SHA256 dạng hex của chuỗi gồm X-Device-Timestamp, một dấu chấm và raw request body. Hướng dẫn Webhook HMAC, retry và chống phát lại giải thích thêm về raw body, timestamp và tính idempotent.

3A. Xác thực bằng mã

Khi tạo tài khoản, gửi provider_data.api_id, provider_data.api_hash và provider_data.phone:

curl -X POST https://api.unifyport.ai/v1/accounts \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Telegram Support\",
    \"provider\": \"telegram\",
    \"region\": \"global\",
    \"status\": \"active\",
    \"auth_mode\": \"code\",
    \"capabilities\": [\"send_message\", \"receive_message\"],
    \"provider_data\": {
      \"api_id\": $TELEGRAM_API_ID,
      \"api_hash\": \"$TELEGRAM_API_HASH\",
      \"phone\": \"$TELEGRAM_PHONE\"
    }
  }"

Lưu id tài khoản từ response, bắt đầu quy trình rồi gửi mã Telegram nhận được:

curl -X POST "https://api.unifyport.ai/v1/accounts/$ACCOUNT_ID/auth/start" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X POST "https://api.unifyport.ai/v1/accounts/$ACCOUNT_ID/auth/code" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"code\": \"$TELEGRAM_LOGIN_CODE\"}"

Tài liệu xác thực người dùng chính thức của Telegram có nhánh mật khẩu hai bước. Chỉ gửi mật khẩu tới /v1/accounts/{account_id}/auth/password khi trạng thái UnifyPort là awaiting_password, và không ghi mật khẩu vào log.

3B. Xác thực bằng QR

Với QR, tạo tài khoản bằng auth_mode: "qrcode", kèm provider_data.api_id và provider_data.api_hash. Chế độ này không cần trường phone. Khởi động quy trình:

curl -X POST "https://api.unifyport.ai/v1/accounts/$ACCOUNT_ID/auth/qr/start" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Đọc trạng thái bằng GET /v1/accounts/{account_id}/auth hoặc kiểm tra qua POST /v1/accounts/{account_id}/auth/qr/check. Chỉ hiển thị auth_payload.qr_code cho chủ tài khoản. Đặc tả QR login chính thức của Telegram yêu cầu quét và chấp nhận QR bằng ứng dụng Telegram đã đăng nhập, đồng thời tạo lại token khi hết hạn. Khi API trả payload mới, giao diện cũng phải cập nhật QR.

Tất cả nhánh mã, QR, mật khẩu hai bước và session import đều có trong Telegram authorization API Reference.

4. Xác nhận trạng thái và nhận tin nhắn

Sau khi nhận account.auth.succeeded, hãy đối chiếu bằng GET /v1/accounts/{account_id}. Runtime thường tự khởi động sau khi xác thực thành công, nhưng ứng dụng cần đọc runtime_status thực tế thay vì mặc định kết nối đã sẵn sàng.

Tin nhắn Telegram đến theo envelope chuẩn:

{
  "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",
      "text": "Can you check my order?",
      "direction": "inbound",
      "sent_at": "2026-06-08T12:37:00Z"
    },
    "event": { "kind": "message_received" }
  }
}

Kiểm tra chữ ký trước, sau đó chỉ định tuyến sự kiện có type là message.received và data.message.direction là inbound. Dùng event ID để xử lý idempotent, phản hồi 2xx cho delivery hợp lệ và lưu các trường workflow cần.

Giới hạn và lựa chọn

Kết nối tài khoản người dùng không thay thế mọi tình huống bot. Nếu cần danh tính bot, lệnh bot và interface dành riêng cho bot của Telegram, Bot API chính thức phù hợp hơn. Nếu cần tài khoản người dùng hiện có, hoặc muốn đội hỗ trợ tại Việt Nam đưa Telegram, Zalo và WhatsApp vào cùng một hàng đợi inbound có chữ ký, luồng UnifyPort phù hợp hơn. LINE, TikTok và X cũng có thể dùng cùng handler sau đó.

UnifyPort là giao diện không chính thức, nên hành vi và mức sẵn sàng từ dịch vụ nguồn có thể khác nhau theo tài khoản. Bạn vẫn phải tuân thủ Telegram API Terms of Service cùng các nghĩa vụ bảo mật và quyền riêng tư của mình. Không để lộ credential, QR hoặc dữ liệu session cho bất kỳ ai ngoài chủ tài khoản đang hoàn tất đăng nhập.

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

Có cần Telegram bot token không?

Không. Tài khoản người dùng dùng api_id và api_hash; bot token thuộc Bot API chính thức.

QR login có còn cần API ID và API hash không?

Có. Luồng QR của UnifyPort vẫn cần provider_data.api_id và provider_data.api_hash; chỉ phương thức phê duyệt đăng nhập thay đổi.

Làm gì khi Telegram yêu cầu mật khẩu hai bước?

Chờ trạng thái awaiting_password, rồi gửi tới /v1/accounts/{account_id}/auth/password. Không ghi log và không lưu bản rõ sau yêu cầu.

Nên tạo webhook trước hay sau khi kết nối tài khoản?

Trước. Trạng thái xác thực và tin nhắn đều đi qua sự kiện, còn payload tin nhắn bị bỏ lỡ không được bảo đảm gửi lại.

Sự kiện nào nên khởi động workflow inbound?

Dùng message.received và yêu cầu data.message.direction bằng inbound. Phải kiểm tra HMAC trước khi phân tích hoặc thực hiện hành động.

Bước tiếp theo

Mở hướng dẫn Telegram authorization và chọn mã hoặc QR. Đăng ký, bảo vệ webhook trước; sau đó tạo messaging account và hoàn tất xác thực.

Nguồn

Nguồn chính thức được kiểm tra ngày 2026-08-13:

• Telegram: Creating your Telegram Application
• Telegram: Login via QR code
• Telegram: User Authorization
• Telegram Bot API