Hướng dẫn August 12, 2026

Khôi phục runtime cho tài khoản nhắn tin: Refresh, Reconnect, Start hay xác thực lại?

Khi một tài khoản nhắn tin UnifyPort ngừng nhận tin, đừng bắt đầu bằng việc yêu cầu người dùng đăng nhập lại. Hãy đọc cả trạng thái xác thực và runtime_status: refresh khi trạng thái chưa rõ hoặc đã cũ, reconnect khi tài khoản vẫn được xác thực nhưng kết nối trực tiếp gặp lỗi, start khi runtime đã dừng, và chỉ xác thực lại khi trạng thái auth hoặc sự kiện account.auth.required yêu cầu người dùng thao tác.

Điểm chính

status, trạng thái xác thực và runtime_status là ba lớp độc lập.
Sau khi xác thực thành công, runtime thường tự khởi động.
POST /runtime/refresh đồng bộ trạng thái, không khởi động lại kết nối.
POST /runtime/reconnect xây dựng lại kết nối lỗi nhưng giữ nguyên xác thực.
Webhook là tín hiệu; sau mỗi thao tác vẫn phải đối chiếu bằng API đọc tài khoản hoặc refresh.

Phân biệt ba lớp trạng thái

Tài liệu vòng đời tài khoản định nghĩa:

status là công tắc nghiệp vụ do workspace kiểm soát.
Trạng thái xác thực đến từ GET /v1/accounts/{account_id}/auth: pending_auth, awaiting_qr_scan, awaiting_code, awaiting_password, authorized hoặc failed.
runtime_status mô tả kết nối trực tiếp, với các giá trị chuẩn unknown, starting, running, stopping, stopped, reconnecting, disconnected và error.

Việc tách ba lớp này đặc biệt hữu ích cho đội ngũ Việt Nam vận hành cả Zalo và WhatsApp. Nếu tài khoản vẫn là authorized, hãy kiểm tra kết nối trước khi yêu cầu quét QR mới. Nếu phiên xác thực thực sự hết hiệu lực, gọi reconnect nhiều lần cũng không hoàn thành được bước cần người dùng xử lý.

Nếu bạn đang điều tra sự cố nền tảng hoặc trạng thái xét duyệt, hãy dùng checklist ứng phó WhatsApp Account Under Review để tách sự cố nền tảng, chính sách, runtime và webhook consumer.

Bảng quyết định: refresh, reconnect, start hay xác thực lại

Quan sát	Thao tác đầu tiên	Lý do
`runtime_status: unknown`	Refresh	Đồng bộ trạng thái mới nhất trước khi thay đổi kết nối.
`running` nhưng đã xác nhận kết nối không ổn định	Reconnect	Xây dựng lại kết nối và giữ auth hiện tại.
`disconnected`, auth là `authorized`	Reconnect rồi đối chiếu	Auth còn hiệu lực, runtime đang ngoại tuyến.
`stopped` và tài khoản cần trực tuyến	Start	Runtime đã dừng cần được khởi động rõ ràng.
`starting`, `stopping` hoặc `reconnecting`	Đối chiếu trước	Một thao tác đã đang diễn ra.
Auth là `pending_auth`, `awaiting_*` hoặc `failed`	Tiếp tục luồng auth phù hợp	Điều khiển runtime không thay thế bước xác thực của người dùng.
Nhận `account.auth.required`	Xác thực theo `auth_payload`	Phiên hiện tại cần người dùng thao tác.
`runtime_status: error`	Refresh và kiểm tra ngữ cảnh lỗi	Không giả định mọi lỗi có cùng cách xử lý.

API reconnect dành cho tài khoản vẫn tồn tại và được xác thực nhưng kết nối runtime không khỏe. API start điều khiển runtime, không thực hiện xác thực.

Triển khai quy trình khôi phục

1. Đọc tài khoản và auth cùng lúc

curl https://api.unifyport.ai/v1/accounts/acc_8c21d0 \
  -H "X-Api-Key: $UNIFYPORT_API_KEY"

curl https://api.unifyport.ai/v1/accounts/acc_8c21d0/auth \
  -H "X-Api-Key: $UNIFYPORT_API_KEY"

Đối tượng tài khoản cung cấp runtime_status. Tài nguyên auth cung cấp status riêng và có thể kèm auth_payload hoặc last_error. Không suy ra auth chỉ từ runtime.

2. Với unknown, refresh trước

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

Refresh đồng bộ trạng thái của nhà cung cấp và trả về runtime_status đã chuẩn hóa. Bạn cũng có thể dùng nó để đối chiếu sau start, reconnect hoặc auth, nhưng nó không thay thế webhook receiver hay kho lưu tin nhắn.

3. Chỉ reconnect khi auth còn hiệu lực

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

Kết quả tức thời có thể là reconnecting. Đây là trạng thái đang xử lý, không phải bằng chứng luồng tin nhắn đã phục hồi. Hãy đối chiếu lại sau đó.

4. Start khi runtime là stopped

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

Xác thực thành công thường tự khởi động runtime. Vì vậy, đăng nhập lại không nên là điều kiện mặc định cho mỗi lần gọi start.

5. Chỉ xác thực lại khi có bằng chứng từ auth

account.auth.required có thể chứa auth_status, runtime_status và auth_payload như QR, URL, PIN hoặc mã xác minh tùy nhà cung cấp và chế độ auth. Chỉ hiển thị bước cần thiết cho chủ tài khoản và không ghi dữ liệu phiên vào log.

Dùng Webhook làm tín hiệu, dùng API để đối chiếu

Đăng ký account.status.updated, account.started, account.auth.required, account.auth.succeeded và account.auth.failed, hoặc dùng subscribed_events: ["*"]. Payload công khai nằm trong danh mục sự kiện chuẩn.

account.status.updated báo thay đổi do nhà cung cấp quan sát, nhưng không được đảm bảo cho mọi transition được yêu cầu. Sau reconnect, start hoặc auth, hãy đọc tài khoản hoặc refresh. Trước khi tin cậy sự kiện, luôn kiểm tra chữ ký; hướng dẫn Webhook HMAC, chống phát lại và retry mô tả hợp đồng ký raw body.

đọc auth và runtime_status
nếu auth cần người dùng: chạy auth flow phù hợp
nếu unknown: refresh
nếu disconnected: reconnect
nếu stopped: start
nếu thao tác đang chạy: đối chiếu
nếu running: không thay đổi
trường hợp khác: refresh và chuyển xử lý kèm ngữ cảnh lỗi

Giới hạn và đánh đổi

Khôi phục runtime không chứng minh webhook endpoint, queue, cơ sở dữ liệu hoặc tự động hóa phía sau đều khỏe. Nếu tài khoản là running nhưng ứng dụng không thấy tin nhắn, hãy kiểm tra riêng việc giao Webhook và consumer.

Reconnect cũng không đảm bảo phát lại lịch sử. UnifyPort không có REST API đọc lịch sử tin nhắn và không đảm bảo phát lại payload bị lỡ. WhatsApp có thể gửi đồng bộ lịch sử giới hạn theo best-effort sau bootstrap hoặc reconnect, nhưng đó không phải kho lưu trữ đầy đủ. Hãy lưu sự kiện khi nhận được.

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

`runtime_status: disconnected` có phải quét QR mới không?

Không nhất thiết. Kiểm tra auth trước; nếu vẫn là authorized, hãy reconnect. Chỉ bắt đầu auth flow mới khi trạng thái auth hoặc account.auth.required yêu cầu.

Refresh khác reconnect thế nào?

Refresh đọc và chuẩn hóa trạng thái mới nhất. Reconnect chủ động xây dựng lại kết nối đang lỗi.

Có cần gọi start sau mỗi lần xác thực thành công không?

Thông thường là không. Runtime thường tự chạy; chỉ gọi start khi trạng thái quan sát được cho thấy cần thiết.

Runtime là running nhưng không có tin nhắn thì kiểm tra gì?

Kiểm tra trạng thái Webhook, chữ ký, HTTP acknowledgement, retry, queue và lưu trữ. Kết nối khỏe và consumer khỏe là hai điều kiện khác nhau.

Bước tiếp theo

Triển khai bảng quyết định theo tài liệu vòng đời tài khoản và thêm Refresh runtime state vào runbook vận hành.

Nguồn chính thức

Các tài liệu chính thức của UnifyPort được kiểm tra ngày 12 tháng 8 năm 2026: