Cuộc gọi thoại WhatsApp không đổ chuông? Kiểm tra từ preparing đến kết nối

Nếu yêu cầu tạo cuộc gọi thoại WhatsApp trả về 201 nhưng điện thoại người nhận không đổ chuông, hãy xác định bước cuối cùng có thể xác nhận. Phản hồi state: preparing chỉ có nghĩa là liên kết gọi trên trình duyệt đã sẵn sàng, không phải đã bắt đầu quay số. Tạo cuộc gọi liên tục có thể khiến lần thử ban đầu khó truy vết hơn.

Hướng dẫn này áp dụng cho cuộc gọi thoại đi một đối một do con người khởi tạo, trong bản thử nghiệm riêng của UnifyPort qua giao diện không chính thức. Đây không phải hướng dẫn Meta WhatsApp Business Calling API. Để thiết lập ban đầu và xem ví dụ yêu cầu đầy đủ, hãy đọc hướng dẫn tích hợp cuộc gọi thoại. Bài này tập trung vào việc xác định lỗi từ bằng chứng đã có trong ứng dụng.

1. Xác định bằng chứng thực sự cho biết điều gì

Bằng chứng	Có thể xác nhận	Không thể xác nhận
Tạo trả về 201 và preparing	Liên kết gọi đã được chuẩn bị	Đã quay số, đổ chuông hoặc kết nối
Truy vấn cuộc gọi hiện tại trả về active	Một cuộc gọi được hệ thống quản lý đã kết nối và đang diễn ra	Webhook đã đến ứng dụng
Nhận được call.answered	Cuộc gọi tương ứng đã kết nối	Phiếu hỗ trợ đã được cập nhật
Nhận được call.ended	Cuộc gọi tương ứng đã kết thúc	Thời lượng bằng 0 đồng nghĩa chưa được trả lời
Truy vấn cuộc gọi hiện tại trả về data: {}	Không tìm thấy cuộc gọi hiện tại do UnifyPort quản lý	Kết quả cuộc gọi trước đó hoặc trạng thái bận trên ứng dụng di động

Trước khi ghép các thông tin này, hãy đối chiếu không gian làm việc, account_id và mã cuộc gọi. Phản hồi API dùng call_id, còn sự kiện cuộc gọi dùng data.call.id. Một nhân viên khác có thể đã bắt đầu cuộc gọi khác trên cùng tài khoản nhắn tin.

2. Tạo thành công nhưng người nhận không nghe đổ chuông

Kiểm tra theo thứ tự sau và đối chiếu với hợp đồng tạo cuộc gọi:

1. Xác nhận ứng dụng chọn đúng tài khoản nhắn tin WhatsApp đã được cấp quyền và runtime_status của tài khoản là running.
2. Kiểm tra yêu cầu đã lưu: to.id phải là conversation_id được trả về từ tài khoản đó, to.type là user, và media_type là voice. Không thay bằng chuỗi số điện thoại.
3. So sánh thời gian hiện tại với expires_at trong phản hồi. Thời gian chuẩn bị mặc định là hai phút kể từ lúc tạo, nhưng máy chủ có thể điều chỉnh nên phải dùng thời hạn trả về. Thời hạn này không giới hạn độ dài cuộc gọi đã kết nối.
4. Xác nhận nhân viên được giao đã mở liên kết riêng tư dùng một lần join_url và nhấn Start call trước khi hết hạn. Chỉ mở trang sẽ không bắt đầu quay số. Quyền micrô là bắt buộc, camera là tùy chọn. Đã cấp quyền cũng không phải bằng chứng kết nối.

Không dùng lại liên kết hết hạn. Truy vấn cuộc gọi hiện tại trước khi chủ động chuẩn bị lần thử mới. Nếu các bước trên đều đạt nhưng vẫn chưa xác nhận được đổ chuông, hãy lưu bằng chứng từ yêu cầu và trình duyệt. Đừng kết luận lỗi nằm ở điện thoại người nhận, trình duyệt hay mạng khi chưa có căn cứ.

3. Hết thời gian chờ hoặc xung đột khiến kết quả chưa rõ

Yêu cầu tạo hết thời gian chờ nghĩa là chưa rõ kết quả, không chứng minh rằng chưa tạo cuộc gọi. Khi nhận phản hồi xung đột, giữ lại nội dung lỗi thực tế thay vì cho rằng mọi xung đột có cùng nguyên nhân. Chạy truy vấn cuộc gọi hiện tại chỉ đọc trên máy chủ:

curl 'https://api.unifyport.ai/v1/calls/active?account_id=acc_example' \
  -H 'X-Api-Key: <YOUR_API_KEY>'

Cuộc gọi thoại đi đã kết nối có thể trả về:

{
  "request_id": "req_example",
  "data": {
    "call_id": "call_example",
    "state": "active",
    "direction": "outbound",
    "media_type": "voice"
  }
}

Khi không có cuộc gọi hiện tại do hệ thống quản lý:

{
  "request_id": "req_example",
  "data": {}
}

Truy vấn cũng có thể trả về preparing, dialing, ringing hoặc connecting; đừng cho rằng lần gọi nào cũng đi qua mọi trạng thái. Truy vấn không khôi phục liên kết gọi bị mất, không cung cấp lịch sử cuộc gọi và không xác định được bên nào đang bận trên ứng dụng WhatsApp di động. Truy vấn thất bại không được xem như phản hồi thành công có dữ liệu rỗng.

Đối chiếu mã trả về với ánh xạ cuộc gọi và phiếu hỗ trợ trong ứng dụng. Không tự động tạo cuộc gọi khác hoặc ngắt cuộc gọi chưa rõ chủ thể để giải phóng tài khoản. Nếu kết quả vẫn chưa rõ, xác minh với nhân viên trước khi thử lại. Khi chủ động ngắt cuộc gọi, cả ended và failed trong phản hồi đều là trạng thái kết thúc; chỉ riêng failed không phải lý do để liên tục gửi yêu cầu ngắt.

4. Đã kết nối nhưng thiếu callback

Kiểm tra lần lượt từ quyền sử dụng đến trạng thái được lưu trong ứng dụng:

• Quyền sử dụng: is_beta là cờ chỉ đọc của không gian làm việc, do bộ phận hỗ trợ bật. Đăng ký ký tự đại diện không cấp quyền thử nghiệm. Không gian chưa có quyền sẽ nhận 403 beta_feature_not_enabled khi đăng ký rõ các sự kiện cuộc gọi.
• Đăng ký: với không gian đủ điều kiện, subscribed_events phải có tên sự kiện cần thiết, hoặc dùng *, danh sách rỗng hay bỏ qua trường. Danh sách cụ thể chỉ khớp các sự kiện được liệt kê. Kiểm tra cả sự kiện kết nối và sự kiện kết thúc.
• Chuyển phát: kiểm tra URL và trạng thái endpoint đã cấu hình, nhật ký truy cập của bên nhận và phản hồi HTTP. 2xx xác nhận chuyển phát, không chứng minh phiếu hỗ trợ đã được cập nhật thành công.
• Xử lý: làm theo hướng dẫn chuyển phát và xác minh chữ ký. Khi đã cấu hình signing_secret, xác minh X-Device-Signature bằng X-Device-Timestamp và phần thân yêu cầu nguyên gốc. Kiểm tra riêng việc loại trùng theo id sự kiện, lưu trữ bền vững và liên kết cuộc gọi với phiếu hỗ trợ.

Thứ tự chuyển phát không được bảo đảm. Nếu sự kiện kết nối đến sau sự kiện kết thúc, hãy lưu bổ sung bằng chứng kết nối nhưng đừng đưa cuộc gọi đã kết thúc về trạng thái đang diễn ra trên giao diện. Chỉ thiếu callback không đủ để kết luận cuộc gọi chưa từng kết nối.

5. Thời lượng bằng 0 và kết quả rỗng cần thêm ngữ cảnh

duration_seconds đo thời gian kết nối và làm tròn xuống số giây nguyên. Vì vậy, số 0 không chứng minh cuộc gọi chưa được trả lời. Lưu bằng chứng từ sự kiện kết nối cùng lý do kết thúc. Lỗi đồng bộ trong giai đoạn tạo có thể không sinh sự kiện kết thúc; đừng để mọi lần tạo thất bại chờ callback vô thời hạn.

Xét một ví dụ chẩn đoán giả định: nhân viên bắt đầu cuộc gọi đã chuẩn bị, truy vấn hiện tại cho thấy đã kết nối, bên nhận đã lưu sự kiện kết nối, nhưng phiếu hỗ trợ vẫn hiển thị “đang chờ”. Bước tiếp theo là kiểm tra liên kết và cập nhật trạng thái trong ứng dụng. Gọi lại không sửa được bản ghi này. Nếu truy vấn sau đó trả về rỗng, nó cũng không tái tạo được lịch sử bị thiếu; hãy dùng các sự kiện và yêu cầu đã lưu.

6. Chuẩn bị thông tin để chuyển tiếp xử lý

Ghi lại mã không gian làm việc, tài khoản nhắn tin, cuộc hội thoại và cuộc gọi, request_id, thời gian UTC, phản hồi đã che dữ liệu nhạy cảm, thao tác và trạng thái quyền của nhân viên, cùng nhật ký bên nhận hiện có. Đánh dấu từng mục là “đã xác nhận” hoặc “chưa rõ”. Không đưa API key, khóa ký hay liên kết gọi riêng tư đầy đủ vào ảnh chụp và nhật ký chia sẻ.

Nếu vẫn còn điểm chưa giải thích được, gửi bản ghi cho bộ phận hỗ trợ kỹ thuật. Hướng dẫn này không hàm ý hỗ trợ cuộc gọi đến, gọi nhóm, ghi âm, chuyển lời nói thành văn bản, tích hợp SIP/PBX hay AI tự động gọi đi.