Hướng dẫn November 4, 2026

Dừng runtime UnifyPort mà không bị worker khôi phục tự khởi động lại

Để tạm dừng kết nối của tài khoản nhắn tin UnifyPort mà không xóa tài khoản, gửi {} đến POST /v1/accounts/{account_id}/runtime/stop. Xác nhận runtime_status: stopped; nếu là stopping, cần tiếp tục kiểm tra. Trước khi gọi API, hãy cho worker khôi phục của ứng dụng biết đây là lần dừng có chủ đích. Nếu không, worker duy trì kết nối có thể khởi động tài khoản trở lại.

Điểm chính

Dừng runtime giữ lại tài khoản, không phải xóa tài khoản.
Lưu bền vững quyết định tạm dừng trong ứng dụng trước khi dừng kết nối.
runtime_status quan sát được và quyền thực hiện khôi phục là hai quyết định khác nhau.
Kết nối hoạt động trở lại không chứng minh tin nhắn trong thời gian dừng đã được khôi phục.

Thao tác khôi phục đúng nhưng diễn ra sai thời điểm

Giả sử một nhân viên dừng tài khoản để bảo trì, worker kiểm tra sức khỏe đọc thấy stopped, rồi gọi start vì nhiệm vụ của nó là giữ tài khoản trực tuyến. Đây là tình huống minh họa, không phải sự cố khách hàng đã được ghi nhận. Hai yêu cầu có thể đều đúng theo API nhưng lại trái với chủ đích của người vận hành.

Cách giải quyết không phải đăng nhập lại, mà là thống nhất trong ứng dụng: tài khoản này có nên trực tuyến ngay lúc này không? Hướng dẫn khôi phục runtime giải quyết kết nối bị lỗi nhưng cần hoạt động. Dừng theo kế hoạch bổ sung một bước kiểm tra quyền trước logic đó.

Đây không phải cấu hình API mới. Tài liệu vòng đời tài khoản tách status của tài khoản, trạng thái xác thực và runtime_status. Bản ghi tạm dừng được đề xuất ở đây là dữ liệu riêng của ứng dụng, không phải trường UnifyPort mới hay hành vi được bảo đảm khi thay đổi status tài khoản.

Chọn đúng phần cần dừng

Mục tiêu	Lớp kiểm soát phù hợp
Dừng ghi CRM hoặc xử lý AI nhưng vẫn tiếp nhận tin nhắn	Tạm dừng consumer của ứng dụng
Dừng kết nối trực tiếp, giữ nguyên tài khoản	Stop runtime
Ngừng sử dụng và loại bỏ tài nguyên tài khoản	Quy trình xóa tài khoản riêng

Nếu chỉ bảo trì xử lý phía sau, chẳng hạn các tác vụ CRM dùng chung cho WhatsApp và Zalo, hãy xem so sánh các cách bảo trì webhook. Dừng kết nối không phải cơ chế lưu đệm tin nhắn bền vững.

Chỉ dùng hướng dẫn xóa tài khoản khi thực sự muốn loại bỏ tài nguyên. Hợp đồng runtime stop không hứa hoàn tiền, tạm dừng thuê bao, xóa tài khoản gốc trên nền tảng hay xóa tin nhắn đã lưu.

Cho worker thấy quyết định tạm dừng trước khi gửi yêu cầu

Đây là quy trình khuyến nghị ở phía ứng dụng:

Xác nhận workspace, account_id, kênh, người thao tác và lý do. Đọc tài khoản và trạng thái xác thực riêng biệt.
Lưu bền vững quyết định tạm dừng cho tài khoản này. Worker khôi phục và worker gửi tin theo lịch phải kiểm tra trước khi gửi yêu cầu mới.
Phối hợp với công việc đang chạy. Cờ vừa lưu không thể hủy API request đã gửi. Cần cơ chế điều phối theo tài khoản của ứng dụng và kiểm tra các thao tác còn đang thực hiện.
Giữ webhook receiver hoạt động để xác minh và lưu những sự kiện vẫn đến. Không hiểu runtime stop là bảo đảm mọi lượt giao webhook đã hoàn tất.
Gửi một yêu cầu dừng đã được duyệt, rồi kiểm tra kết quả.

Sau đây là mã giả của ứng dụng, không phải cú pháp SDK hay endpoint mới:

trước khi tự động gọi start hoặc reconnect:
    đọc chủ đích vận hành hiện tại của tài khoản trong dữ liệu nội bộ
    nếu người vận hành đã yêu cầu tạm dừng:
        không gửi yêu cầu khôi phục
    nếu không:
        kiểm tra xác thực và trạng thái runtime
        chọn thao tác khôi phục đã được tài liệu hóa

Mọi đường khôi phục đều phải tuân theo điều kiện này, kể cả tác vụ bị trì hoãn và nút khôi phục thủ công. Điều phối thay đổi dừng và mở lại để một tác vụ start cũ không trở nên hợp lệ chỉ vì có thao tác giao diện sau đó.

Dừng một lần, rồi đối chiếu kết quả thực tế

Tài liệu Stop runtime quy định body là JSON object rỗng. Ví dụ dưới đây chưa được thực thi tại đây. Điền các biến từ lựa chọn tài khoản đã được backend xác nhận và cấu hình API key được bảo vệ:

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

Giữ API key ở máy chủ. Lưu HTTP status và thông tin chẩn đoán có sẵn, không ghi bí mật vào log.

Quan sát	Ý nghĩa và bước tiếp theo
`runtime_status: stopped`	Đã dừng ở lớp runtime; giữ quyết định tạm dừng nội bộ
`runtime_status: stopping`	Đang chuyển trạng thái; kiểm tra tiếp
Timeout hoặc không đọc được response	Chưa biết kết quả; đọc trạng thái trước khi thay đổi thêm
Nội bộ vẫn yêu cầu dừng nhưng runtime thành `running`	Kiểm tra các đường start hoặc reconnect cạnh tranh; không báo đã sẵn sàng bảo trì

Dùng Get account hoặc Refresh runtime state để đối chiếu. Refresh đồng bộ trạng thái, không yêu cầu khởi động lại. Đặt chính sách kiểm tra và chuyển cấp có giới hạn trong ứng dụng, không tự giả định thời hạn hoàn tất cố định.

Đừng chờ sự kiện account.stopped không có trong danh mục công khai. Tài liệu vòng đời không bảo đảm account.status.updated xuất hiện cho mọi lần chuyển trạng thái do yêu cầu. Hộp thư không có tin mới cũng không chứng minh runtime đã dừng.

Mở lại là một lần chuyển trạng thái riêng cần xác nhận

Tiếp tục chặn tác vụ gửi trong khi kiểm tra xác thực hiện tại của tài khoản được giữ lại. Nếu cần người dùng thao tác, tiếp tục luồng xác thực tương ứng. Xác thực thành công thường tự khởi động runtime, nên không bắt đầu xác thực lại trong lúc tạm dừng nếu không chủ ý làm vậy.

Nếu xác thực còn hiệu lực và runtime đang dừng, dùng Start runtime. Phối hợp thao tác mở lại rõ ràng này với kiểm soát nội bộ, rồi kiểm tra đến khi thực sự là running. starting chưa phải hoàn tất.

Trước khi giải phóng các tác vụ tồn, kiểm tra từng tác vụ còn phù hợp hay không. Gửi một tin nhắn thử có kiểm soát và theo dõi sự kiện mới qua xác minh chữ ký, lưu trữ, rồi mới bật consumer và chính sách khôi phục tự động cần thiết.

Giao diện không chính thức của UnifyPort không bảo đảm phát lại payload bị bỏ lỡ và không cung cấp REST API tổng quát để đọc lịch sử tin nhắn. Ghi lại khoảng dừng như một khoảng có thể thiếu dữ liệu. Tin nhắn thử mới thành công chỉ chứng minh đường xử lý hiện tại đã hoạt động, không chứng minh dữ liệu thiếu đã được bù.

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

Stop có xóa tài khoản nhắn tin không?

Không. Thao tác được mô tả là dừng runtime nhưng giữ tài khoản. Khởi động lại là thao tác riêng.

Worker có nên khởi động mọi tài khoản stopped không?

Không. Trước hết phải kiểm tra ứng dụng hiện có muốn tài khoản đó trực tuyến hay không. Trạng thái runtime không thể hiện chủ đích của người vận hành.

Dừng thành công có hủy tin trả lời trong hàng đợi hoặc lượt giao webhook không?

Không nên giả định như vậy. Quản lý tác vụ ứng dụng riêng; hợp đồng công khai không hứa hủy công việc đã gửi hoặc chờ xử lý hết webhook.

Dừng kết nối có tạm dừng tính phí không?

Hợp đồng runtime stop không hứa điều đó. Không dùng trạng thái kết nối làm bằng chứng thay đổi tài chính.

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

Triển khai điều kiện cho phép khôi phục nội bộ cùng Stop runtime. Nên kiểm thử worker cạnh tranh, start đang thực hiện, mất response dừng, stopping, mở lại có chủ đích và tin trả lời cũ trong hàng đợi. Đây là các ca kiểm thử đề xuất, không phải kết quả đã đạt.

Tài liệu được đối chiếu ngày 2026-11-04:

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 Key Xem tham chiếu API