Cuộc gọi thoại và video WhatsApp trong UnifyPort: bản beta giới hạn

Khách hàng đã mô tả vấn đề qua WhatsApp, nhưng thêm một đoạn tin nhắn nữa vẫn khó làm rõ tình huống. Nhân viên của bạn cần trao đổi trực tiếp về chi tiết giao hàng hoặc xem vấn đề qua camera. Bản beta giới hạn của UnifyPort bổ sung cách chuẩn bị cuộc gọi thoại hoặc video WhatsApp một-một từ ứng dụng nghiệp vụ, để nhân viên bắt đầu cuộc gọi trong trình duyệt và để backend nhận các sự kiện trạng thái cuộc gọi.

Phạm vi hiện tại là cuộc gọi WhatsApp đi do con người thực hiện. Đội hỗ trợ kỹ thuật cấp quyền riêng cho từng không gian làm việc (workspace). Chỉ tạo API key chưa đủ để bật tính năng gọi, và bản beta này chưa mở chức năng nhận cuộc gọi đến.

Bản beta bổ sung những gì

Tài liệu API cuộc gọi hiện mô tả ba thao tác:

• POST /v1/calls chuẩn bị cuộc gọi thoại hoặc video và trả về join_url có thời hạn ngắn, chỉ dùng một lần.
• GET /v1/calls/active lấy cuộc gọi hiện tại do UnifyPort quản lý cho tài khoản được chọn.
• POST /v1/calls/{call_id}/hangup kết thúc cuộc gọi được chỉ định.

Hai sự kiện Webhook giúp ứng dụng theo dõi cuộc gọi: call.answered thông báo khi kết nối được thiết lập, còn call.ended thông báo khi cuộc gọi kết thúc, kèm lý do và thời lượng đã kết nối. Các thành phần này giúp nhà phát triển thêm bước gọi trực tiếp giữa nhân viên và khách hàng vào quy trình hỗ trợ hiện có.

Yêu cầu API chỉ chuẩn bị cuộc gọi. Nhân viên mở liên kết được trả về rồi bấm Start call để quay số. Hãy thể hiện rõ thao tác này trong giao diện để nhân viên kiểm tra đúng khách hàng trước khi bắt đầu.

Khi chat cần chuyển sang trao đổi trực tiếp

Hãy xem những tình huống hỗ trợ giả định sau:

• Xác nhận đơn hàng: nhân viên và khách hàng trao đổi về phương án giao hàng đã trở nên khó giải thích bằng tin nhắn ngắn.
• Khắc phục sự cố: nhân viên hướng dẫn khách hàng thực hiện từng bước kiểm tra qua cuộc gọi thoại.
• Hỗ trợ qua hình ảnh: cuộc gọi video giúp khách hàng cho nhân viên xem vấn đề của sản phẩm hoặc việc lắp đặt.

Đây là các quy trình ứng dụng có thể xây dựng, không phải kết quả đã ghi nhận từ khách hàng. Nhóm của bạn vẫn quyết định khi nào nên gọi và ghi lại bước xử lý tiếp theo trong hệ thống hỗ trợ riêng.

Hộp thư có thể đặt nút gọi bên cạnh cuộc trò chuyện WhatsApp đang được chọn. Hãy sử dụng conversation_id của cuộc trò chuyện thuộc tài khoản nhắn tin đã kết nối; API cuộc gọi không nhận một chuỗi số điện thoại tùy ý. Việc phân công và giải quyết yêu cầu vẫn được quản lý trong ứng dụng của bạn, như mô tả trong hướng dẫn hộp thư WhatsApp dùng chung.

Chuẩn bị cuộc gọi, rồi để nhân viên bắt đầu

Trước tiên, hãy yêu cầu quyền truy cập beta cho workspace và kết nối một tài khoản nhắn tin WhatsApp đã được xác thực. Nếu bạn vẫn đang thiết lập quyền truy cập tài khoản, hướng dẫn xác thực bằng QR và Passkey giải thích bước kết nối tài khoản riêng này.

Gửi yêu cầu tạo từ backend với X-Api-Key của workspace. JSON dưới đây minh họa body được tài liệu quy định; hãy thay acc_example và <conversation_id> bằng tài khoản được chọn và mã cuộc trò chuyện thực tế của tài khoản trước khi gửi tới POST /v1/calls:

{
  "account_id": "acc_example",
  "to": {
    "id": "<conversation_id>",
    "type": "user"
  },
  "media_type": "video"
}

Dùng voice cho cuộc gọi thoại hoặc video cho cuộc gọi hỗ trợ video. Giữ API key trên máy chủ và chỉ chuyển join_url được trả về một cách riêng tư cho nhân viên sẽ thực hiện cuộc gọi.

Thao tác tạo trả về 201 Created với call_id, state: preparing, join_url và expires_at. Phản hồi này không có nghĩa là đã quay số cho khách hàng hoặc khách hàng đã trả lời.

Thời gian chuẩn bị mặc định là hai phút kể từ lúc tạo. Hãy dùng expires_at được trả về làm thời hạn thực tế, vì máy chủ có thể điều chỉnh thời hạn. Nhân viên phải mở liên kết và bấm Start call trước thời điểm đó. Thời hạn chuẩn bị này không giới hạn thời lượng của cuộc gọi đã kết nối.

Trình duyệt yêu cầu quyền sử dụng micro; quyền truy cập camera là tùy chọn. Hãy coi liên kết là thông tin riêng tư chỉ dùng một lần: không công khai hoặc ghi toàn bộ URL vào log.

Đưa trạng thái cuộc gọi về quy trình xử lý

Trong hệ thống riêng, hãy gắn call_id được trả về với tài khoản, cuộc trò chuyện và yêu cầu hỗ trợ được chọn. Endpoint lấy cuộc gọi hiện tại có thể lấy cuộc gọi do UnifyPort quản lý khi cần, kể cả khi bạn đã mất mã cuộc gọi. Endpoint trả về data: {} nếu không có cuộc gọi nào đang được quản lý. Nó không thể xác định một trong hai người có đang bận trong ứng dụng WhatsApp trên điện thoại hay không.

Đăng ký call.answered và call.ended để cập nhật bản ghi cuộc gọi trong ứng dụng. Nếu chỉ định danh sách subscribed_events, danh sách cần có hai tên sự kiện này. Với workspace beta, *, danh sách rỗng hoặc việc bỏ qua danh sách đều bao gồm các sự kiện cuộc gọi được phép. Workspace thông thường không nhận các sự kiện đó qua đăng ký wildcard.

Sự kiện kết thúc bao gồm data.call.id, reason và duration_seconds. Thời lượng đo thời gian đã kết nối, làm tròn xuống đến giây nguyên, nên riêng giá trị 0 không chứng minh cuộc gọi chưa được trả lời. Hãy theo dõi cả sự kiện trả lời. Lỗi đồng bộ khi tạo cuộc gọi có thể không phát sinh callback kết thúc; cần xử lý lỗi HTTP riêng.

Làm theo tài liệu gửi Webhook để xác minh chữ ký và loại bỏ sự kiện trùng theo event ID. Ứng dụng có thể dùng những thông tin này để hỗ trợ công việc theo dõi tiếp theo; kết thúc cuộc gọi không tự động giải quyết vấn đề của khách hàng.

Phạm vi của bản beta giới hạn hiện tại

Bản beta này hỗ trợ cuộc gọi thoại và video WhatsApp một-một được bắt đầu qua quy trình trên trình duyệt. Cuộc gọi nhóm, cuộc gọi kênh, cuộc gọi trên các nền tảng nhắn tin khác và xử lý cuộc gọi đến nằm ngoài phạm vi hiện tại. Sự kiện call.incoming trong tài liệu là hợp đồng dự phòng; sự hiện diện của nó trong danh mục sự kiện không bật tính năng nhận cuộc gọi.

Ghi âm, chuyển lời nói thành văn bản, tích hợp SIP/PBX và nhân viên thoại AI không phải các khả năng được cung cấp trong bản beta này. UnifyPort cung cấp một giao diện không chính thức; bài viết mô tả hợp đồng cuộc gọi của riêng UnifyPort, không gọi đây là WhatsApp Business Calling API chính thức của Meta.

Cờ workspace is_beta chỉ đọc và mặc định bị tắt. Đội hỗ trợ kỹ thuật phải cấp quyền đủ điều kiện. Workspace chưa có quyền nhận 403 beta_feature_not_enabled với mã số 41002 khi sử dụng API cuộc gọi. Đặt metadata hoặc gửi PATCH cho workspace không thể bật quyền truy cập.

Những câu hỏi trước khi dùng thử

Tôi có thể bắt đầu cuộc gọi chỉ bằng số điện thoại không?

Không. Hãy dùng conversation_id thực tế của tài khoản nhắn tin WhatsApp được chọn, với to.type: user.

API có quay số ngay không?

Không. API chuẩn bị liên kết cuộc gọi. Một người phải mở liên kết và bấm Start call trước expires_at để quay số.

Cuộc gọi có bị giới hạn trong hai phút không?

Không. Hai phút là thời gian chuẩn bị mặc định kể từ lúc tạo. Đây không phải giới hạn thời lượng cho cuộc gọi đã kết nối.

Quyền truy cập beta có cho phép nhóm trả lời cuộc gọi đến không?

Không. Bản beta hiện tại chưa mở cuộc gọi đến, kể cả với workspace có is_beta: true.

Yêu cầu quyền truy cập cho nhóm

Liên hệ đội hỗ trợ kỹ thuật để yêu cầu quyền truy cập bản beta cuộc gọi cho workspace của bạn. Để giải thích nhu cầu sử dụng, bạn có thể cung cấp workspace ID, tình huống hỗ trợ qua WhatsApp và nhu cầu gọi thoại hay video của nhóm. Đây là các thông tin hữu ích cho yêu cầu, không phải quy trình tự động đăng ký. Không đưa API key hoặc liên kết cuộc gọi riêng tư vào yêu cầu.

Sau khi quyền truy cập được bật, hãy dùng tài liệu tạo cuộc gọi để kết nối một cuộc trò chuyện thử nghiệm được chủ động lựa chọn với quy trình trình duyệt của nhân viên. Bắt đầu từ quy trình bạn muốn cải thiện và dùng bản beta để đánh giá cuộc gọi do con người thực hiện phù hợp thế nào với ứng dụng hỗ trợ của bạn.