Tổng quan Webhook

Webhook là cơ chế thông báo chủ động theo thời gian thực (Event-driven) từ tổng đài ODS đến hệ thống máy chủ của doanh nghiệp (CRM, ERP, Helpdesk) qua giao thức HTTP POST mỗi khi phát sinh các sự kiện trong vòng đời cuộc gọi.

Khái niệm và cơ chế hoạt động

Để tích hợp đúng phạm vi dịch vụ ODS, cần phân biệt Webhook với các thành phần công nghệ khác trong hệ sinh thái tổng đài:

• Khác biệt với REST API:
  • REST API hoạt động theo cơ chế kéo (Pull/Command): Máy chủ CRM chủ động gửi yêu cầu lên ODS khi cần lấy dữ liệu hoặc thực thi hành động (như tạo máy nhánh, kích hoạt cuộc gọi).
  • Webhook hoạt động theo cơ chế đẩy (Push/Notification): Tổng đài ODS chủ động gửi dữ liệu về máy chủ CRM ngay khi sự kiện diễn ra.
• Webhook chỉ truyền dữ liệu, không truyền âm thanh:
  • Webhook chỉ mang các gói tin JSON chứa siêu dữ liệu (Metadata) của cuộc gọi như số điện thoại, máy nhánh, mốc thời gian và trạng thái kết nối.
  • Webhook không phải là WebSocket hay WebRTC và không truyền dẫn luồng âm thanh thoại. Luồng đàm thoại được xử lý độc lập qua kênh SIP/WebRTC hoặc thiết bị đầu cuối IP Phone.
• Bản chất của tính năng Popup cuộc gọi:
  • Popup hiển thị thông tin khách hàng là một ứng dụng của dữ liệu Webhook, không phải một cơ chế truyền sự kiện khác của ODS. Cách hệ thống khách hàng chuyển dữ liệu đã nhận đến giao diện nằm ngoài contract Webhook này.

Điều kiện chuẩn bị tích hợp

Trước khi tiếp nhận dữ liệu Webhook từ tổng đài, doanh nghiệp cần chuẩn bị:

1. Endpoint URL tiếp nhận:
   • Một đường dẫn API công khai trên máy chủ của doanh nghiệp có khả năng nhận request HTTP POST với body JSON (ví dụ: https://crm.example.com/api/webhook/ods-call).
   • Lưu ý: Đây là URL thuộc hạ tầng của khách hàng, không sử dụng domain của ODS.
2. Giao thức bảo mật HTTPS:
   • Khuyến nghị sử dụng HTTPS để mã hóa dữ liệu cuộc gọi và thông tin khách hàng trên đường truyền Internet.
3. Khóa xác thực Webhook (apikey) — Tùy chọn:
   • Doanh nghiệp có thể cung cấp một giá trị khóa đã thống nhất với ODS. Khi được cấu hình, ODS gửi khóa trong field apikey của body JSON; không đổi tên thành ApiKey, X-API-Key hoặc Authorization.
   • Nếu chưa cấu hình khóa, payload mẫu hiện tại có thể chứa "apikey": null. Đây không phải chỉ dẫn để bỏ qua một khóa sai và apikey Webhook không phải AuthKey của REST API.
4. Thông tin cung cấp cho ODS:
   • Doanh nghiệp cung cấp Endpoint URL và apikey nếu muốn dùng xác thực tùy chọn. Tài liệu này không giả định một giao diện Portal cụ thể để cấu hình hai giá trị đó.
5. Phản hồi xác nhận tiếp nhận:
   • Sau khi tiếp nhận body JSON, endpoint trả một HTTP status thuộc dải 2xx. Phản hồi này chỉ xác nhận endpoint đã tiếp nhận request, không phải trạng thái cuộc gọi và ODS không yêu cầu một response JSON cố định trong contract hiện tại.

Vòng đời năm sự kiện cuộc gọi

Tổng đài ODS phân loại tiến trình cuộc gọi thành 5 sự kiện chính thông qua trường Event:

Mô hình định danh cuộc gọi đa nhánh

Trong môi trường tổng đài doanh nghiệp, một cuộc gọi có thể đổ chuông nhiều máy nhánh hoặc chuyển tiếp qua nhiều bộ phận. Hệ thống phân định bằng 3 tham số cốt lõi:

• LID (Linked ID):
  • Mã định danh cấp cao nhất của toàn bộ phiên cuộc gọi (Session ID).
  • Tất cả các sự kiện thuộc cùng một cuộc gọi (dù qua IVR, chuyển máy hay đổ chuông nhiều người) đều mang chung một giá trị LID.
• Ext (Extension):
  • Số máy nhánh nội bộ của nhân viên liên quan trực tiếp đến sự kiện hiện tại (ví dụ: 7877).
• Uid (Unique ID):
  • Mã định danh của từng nhánh kênh thoại viễn thông cụ thể (Channel Unique ID).
  • Khi một cuộc gọi đổ chuông đồng thời 4 máy nhánh, tổng đài sẽ tạo ra 4 nhánh kênh với 4 Uid khác nhau nhưng dùng chung 1 LID.
  • Uid và LID có vai trò khác nhau. Giá trị có thể bằng nhau trong một số kịch bản, nhưng không được giả định chúng luôn bằng nhau.

Lưu ý cho hệ thống quản lý nhiều tổng đài:

• Nếu doanh nghiệp vận hành nhiều tổng đài ODS cùng lúc và trỏ về chung một backend endpoint, cần phân vùng dữ liệu theo Nguồn tổng đài + LID để tránh xung đột mã định danh.
• Contract hiện tại không bổ sung field tenant hoặc source vào payload. apikey: null không cung cấp thông tin để xác định nguồn tổng đài; cách nhận biết nguồn tích hợp phải được thống nhất riêng theo cấu hình thực tế.

Hai luồng sự kiện minh họa từ thực tế

Dựa trên dữ liệu log thực tế từ hệ thống ODS, dưới đây là tiến trình diễn ra trong 2 tình huống phổ biến:

Kịch bản A: Cuộc gọi ra (Outbound) được trả lời

Khi nhân viên gọi ra cho khách hàng và khách hàng nhấc máy:

1. register: Ghi nhận máy nhánh bắt đầu khởi tạo kết nối gọi ra. LID và Uid được tạo.
2. show: Bắt đầu quay số đến khách hàng (TimeDial).
3. answer: Khách hàng nhấc máy, ghi nhận thời điểm bắt đầu đàm thoại (TimeAnswer).
4. finish: Một trong hai bên gác máy. Ghi nhận thời điểm kết thúc (TimeEnd), kết quả Disposition: ANSWERED và đường dẫn nghe file ghi âm recordingfileURL. (Lưu ý: Trong kịch bản gọi ra thành công này, hệ thống không phát sinh sự kiện hide).

Kịch bản B: Cuộc gọi vào (Inbound) đổ chuông nhóm máy nhánh

Khi khách hàng gọi vào Hotline, nghe lời chào IVR và cuộc gọi được phân phối đổ chuông đồng thời đến 4 máy nhánh (Ring Group / Queue):

1. register: Khách hàng kết nối vào tổng đài. Sự kiện lúc này chưa có thông tin Ext hay Uid vì cuộc gọi đang nằm ở tầng Trunk/IVR.
2. Nhiều sự kiện show: Tổng đài phát nhiều webhook show tương ứng với từng máy lẻ đang đổ chuông (Ext: 7875, 7877, 7874, 7873).
3. answer: Nhân viên tại máy lẻ 7877 bấm nghe máy.
4. Các sự kiện hide: Các máy lẻ còn lại (7875, 7874, 7873) ngừng đổ chuông và nhận sự kiện hide với trạng thái Disposition: ANSWERED_ELSEWHERE.
5. finish: Khi cuộc đàm thoại giữa máy lẻ 7877 và khách hàng kết thúc, tổng đài gửi sự kiện finish kèm thông tin tổng kết và liên kết file ghi âm.

Ứng dụng thực tế của dữ liệu Webhook

Dữ liệu sự kiện từ Webhook cho phép doanh nghiệp hiện thực hóa các chức năng:

• Bật cửa sổ thông tin khách hàng (Screen Pop-up): Dùng CID và Ext trong sự kiện show để hệ thống khách hàng xác định thông tin cần hiển thị cho đúng máy nhánh.
• Cập nhật trạng thái bàn làm việc (Agent Presence): Hiển thị trạng thái nhân viên đang bận đàm thoại (answer) hoặc đã sẵn sàng nhận cuộc gọi mới (finish).
• Đối chiếu vòng đời cuộc gọi: Dùng LID, các mốc thời gian và Disposition để liên kết dữ liệu sự kiện với nghiệp vụ của ứng dụng tiếp nhận.
• Đồng bộ tệp ghi âm tự động: Lấy liên kết recordingfileURL từ sự kiện finish để gắn vào hồ sơ khách hàng phục vụ quản lý chất lượng cuộc gọi.

Bài viết tiếp theo

Để xem chi tiết cấu trúc JSON payload của từng sự kiện và từ điển các trường dữ liệu, vui lòng xem: