Nhận Webhook cuộc gọi WhatsApp đi trong không gian làm việc thường
Không gian làm việc thường trên UnifyPort có thể chuẩn bị cuộc gọi WhatsApp đi một đối một. Nếu endpoint Webhook chỉ đăng ký ["*"], tin nhắn vẫn có thể đến trong khi callback cuộc gọi bị thiếu. Để nhận cả hai sự kiện, hãy liệt kê rõ call.answered và call.ended.
Tài liệu tạo cuộc gọi áp dụng cho cuộc gọi thoại và video đi do con người khởi tạo qua giao diện không chính thức của UnifyPort. call.incoming được dành cho tính năng cuộc gọi đến trong tương lai.
1. Kiểm tra quy tắc đăng ký
| Không gian làm việc | Đăng ký | Sự kiện cuộc gọi đi |
|---|---|---|
| Thường | ["*"], [] hoặc bỏ qua danh sách | Chỉ sự kiện thông thường |
| Thường | Liệt kê rõ tên trong subscribed_events | Nhận các sự kiện cuộc gọi đi được liệt kê |
| Thử nghiệm | Danh sách cụ thể, ký tự đại diện, danh sách rỗng hoặc bỏ qua | Nhận các sự kiện cuộc gọi đi khớp |
Endpoint đủ điều kiện sẽ nhận sự kiện tương ứng với tên đã liệt kê. Trong không gian thường, có thể giữ * và thêm hai tên sự kiện cuộc gọi để duy trì phạm vi ký tự đại diện cho sự kiện thông thường. Đăng ký rõ call.incoming dành riêng trong không gian thường trả về 403 beta_feature_not_enabled (41002).
2. Đọc cấu hình endpoint trước khi cập nhật
Dùng truy vấn endpoint Webhook để kiểm tra URL đích, trạng thái, đăng ký hiện tại và chính sách thử lại. Xác nhận endpoint thuộc không gian làm việc hay một tài khoản nhắn tin cụ thể. Bản cập nhật giữ liên kết tài khoản hiện có.
Cập nhật endpoint Webhook thay thế cấu hình. Chuẩn bị đầy đủ cấu hình mong muốn trước khi gửi và giữ URL, trạng thái, chính sách thử lại hiện tại. Nếu đã bật ký, lấy khóa hiện có từ cấu hình bảo mật của ứng dụng. Phản hồi truy vấn cung cấp signing_enabled, còn ứng dụng lưu giữ khóa. Bỏ qua hoặc để trống signing_secret sẽ tắt ký. Bỏ qua chính sách thử lại sẽ khôi phục mặc định ba lần thử lại sau lần gửi đầu tiên.
3. Thêm sự kiện cuộc gọi và giữ đăng ký tin nhắn
Với endpoint đang dùng ký tự đại diện, gửi phần thân sau tới PATCH /v1/webhook-endpoints/{endpoint_id}. Ví dụ giả định endpoint đang hoạt động, có chữ ký và cấu hình ba lần thử lại. Thay URL, trạng thái, khóa và chính sách thử lại bằng giá trị hiện tại. Giữ API key và khóa ký trên máy chủ.
{
"url": "https://support.example.com/webhook",
"status": "active",
"subscribed_events": ["*", "call.answered", "call.ended"],
"signing_secret": "<EXISTING_WEBHOOK_SIGNING_SECRET>",
"retry_policy": { "max_attempts": 3 }
}
Với danh sách cụ thể, sao chép các tên hiện có rồi thêm hai sự kiện cuộc gọi. Ví dụ, nếu danh sách cũ chỉ có message.received và message.read, kết quả là mảng dưới đây. Dùng mảng này cho trường subscribed_events trong phần thân cập nhật đầy đủ.
["message.received", "message.read", "call.answered", "call.ended"]
Truy vấn lại sau khi cập nhật. Đối chiếu URL, trạng thái, đăng ký, trạng thái ký và thiết lập thử lại. Xác nhận bên nhận xử lý được cả hai sự kiện cuộc gọi và các sự kiện tin nhắn hiện có.
4. Xác minh chuyển phát bằng một cuộc gọi mới
- Chọn hội thoại thử nghiệm từ cùng tài khoản nhắn tin WhatsApp đã được cấp quyền. Chuẩn bị cuộc gọi bằng
POST /v1/callsvà lưucall_idtrả về cùng tác vụ ứng dụng. - Phản hồi
201cóstate: preparingxác nhận liên kết đã sẵn sàng. Nhân viên mởjoin_urlriêng tư và nhấn Start call trướcexpires_at. - Khi cuộc gọi thử nghiệm đã kết nối và kết thúc, tìm sự kiện kết nối và sự kiện kết thúc. Đối chiếu
account_idvàdata.call.idvới bản ghi đã lưu. - Gửi một tin nhắn thử qua quy trình cũ và xác nhận sự kiện dự kiến vẫn tới bên nhận.
Với endpoint có chữ ký, xác minh phần thân nguyên gốc theo hướng dẫn chuyển phát và xác minh chữ ký. Loại trùng theo id sự kiện và xử lý thứ tự đến khác nhau. Sự kiện kết nối đến muộn có thể bổ sung bằng chứng trong khi cuộc gọi vẫn ở trạng thái kết thúc. Bản ghi cuộc gọi trong message.* có mục đích riêng.
5. Xử lý callback thiếu và chuẩn bị khôi phục
Khi thiếu callback, kiểm tra tên sự kiện chính xác, phạm vi và trạng thái hoạt động của endpoint. Sau đó kiểm tra nhật ký nhận, phản hồi HTTP và dữ liệu đã lưu trong ứng dụng. 2xx xác nhận chuyển phát. Kiểm tra riêng việc lưu trữ và liên kết tác vụ. Chuyển phát, thử lại và phát lại dead letter dùng quyền và đăng ký hiện tại.
Giữ cấu hình endpoint cũ và tham chiếu khóa ký. Để khôi phục, gửi lại cấu hình đầy đủ trước đó rồi kiểm tra chuyển phát tin nhắn. Nếu cần trợ giúp, cung cấp mã endpoint, tài khoản, cuộc gọi, thời gian UTC và kết quả bên nhận đã che dữ liệu nhạy cảm cho bộ phận hỗ trợ kỹ thuật. Giữ riêng API key, khóa ký và liên kết gọi đầy đủ.
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.