Webhook

Webhook cuộc gọi

Nhận dữ liệu cuộc gọi từ Webhook

• Đối tác khai báo API để nhận dữ liệu cuộc gọi từ WEBHOOK trả về

• METHOD : POST

• Content-type : application/json

Webhook data khi cuộc gọi đã kết thúc

Truy cậu cấu hình tại :

{
  "answer_sec": 39, // Số giây trả lời. Dùng để nhận dạng cuộc gọi Trả lời/ Không trả lời (Bao gồm gọi thường và gọi tự động)
  "bill_sec": 41, // Số giây tính tiền
  "bill_sec_forward_out": 0, // Số giây chuyển tiếp 
  "call_out_price": 699.05, // Cước cuộc gọi
  "call_uuid": "ad97a435-659e-49b4-ae83-4484c.....", // Id cuộc gọi
  "create_by": { // Thông tin nhân viên
    "contact_id": "63857253b1fd5112977dfade",
    "id": "63857254b1fd5112977dfadf",
    "name": "Thùy Nhân",
    "type": "agent"
  },
   "collect_info_variables": // CallBot : Thông tin mảng biến thu thập
   [
    {
      "collect_info_executed_time": {
        "end": 17.440811157226562,
        "start": 13.95820426940918
      },
      "entire_user_sentence": "tầm 2 giờ chiều nhá",
      "entity_type_code": "omi_entity_datetime",
      "variable_code": "AeMd2JtJ7O",
      "variable_name": "new_ship_time",
      "variable_value": "02:00"
    }
  ],
  "users_status": [
    {
      "answer_at": 1748832946,
      "auto_answer": false,
      "call_uuid": "602d98ab-a577-4297-a285-7d71aed06171",
      "extension": "100",
      "group_index": 0,
      "group_number": "62714",
      "is_busy": false,
      "is_dnd": false,
      "is_online": true,
      "ring_at": 1748832941,
      "timeout": 30
    }
  ],
  "created_date": 1748310220317, //Ngày tạo record json
  "destination_number": "0966....", // Thuê bao bị gọi (Callee)
  "direction": "outbound", // Hướng gọi. Gọi ra (outbound). Gọi vào (inbound). Gọi nội bộ (local) 
  "domain_fusion": "vihat", // Domain tổng đài doanh nghiệp
  "duration": 44, //Số giây giây khởi tạo cuộc gọi
  "endby_name": "end_call_by_customer", //Hình thức kết thúc
  "from_number": "2022", // Thuê bao người gọi (Caller)
  "hangup_cause": "NORMAL_CLEARING", //Mã HANGUP
  "hangup_cause_q850": 16,
  "hotline": "02873022488", //Hotline
  "is_auto_call": false, // Gọi thủ công (false) / Gọi tự động (true)
  "is_have_forward_out": false, // Cuộc gọi có chuyển tiếp ra SIM (true). Không chuyển tiếp ra SIM (false) 
  "is_same_network": false, // Nội mạng (true) / Ngoại mạng (false)
  "is_same_network_forward_out": false, // Cuộc gọi chuyển tiếp ra SIM cùng mạng (true). Ra SIM ngoại mạng (false). So sánh giữa Hotline và SIM được chuyển)
  "is_voicemail": false, // Cuộc gọi có hộp thư thoại (true). Không có hộp thư thoại (false)
  "ivr": "none",// Cuộc gọi có bấm phím 
  "note": "",// Ghi chú về cuộc gọi 
  "out_of_working_time": false, // Ngoài giờ làm việc (true). Trong giờ làm việc (false)
  "phone_number": "096606....", // Số điện thoại khách hàng
  "provider": "viettel", // Nhà mạng của khách hàng
  "provider_of_number": "fpt", // Nhà mạng của số Hotline
  "record_seconds": 39, // Số giây ghi âm cuộc gọi. Chỉ ghi nhận với những cuộc >3 giây đàm thoại
  "recording_file_url": "https://public-v1-stg.omicrm.com/......", // URL file ghi âm
  "send_num_retry": 1, // Số lần gửi cho đối tác 
  "sip_number": "02873022488", // Hotline 
  "sip_number_tags": [], // Tags phân loại của Hotline, hỗ trợ cho doanh nghiệp phân loại Hotline theo pháp nhân đứng tên
  "sip_user": "2022", // Định danh người gọi (Caller) 
  "source_number": "02873022488", // Định danh thuê bao gọi (Caller) 
  "state": "cdr", // Trạng thái cuộc gọi 
  "tag": [], //Danh sách Tags cuộc gọi đính kèm
  "tenant_id": "5cbfc17a580dd80007ffc....", // Id doanh nghiệp
  "time_end_call": 1748310215, // Thời gian kết thúc cuộc gọi Unix time (seconds)
  "time_start_call": 1748310171, // Thời gian khởi tạo cuộc gọi Unix time (seconds)
  "time_start_to_answer": 1748310171, // Thời gian cuộc gọi bắt đầu được trả lời Unix time (seconds)
  "to_number": "09660....",
  "transaction_id": "ad97a435-659e-49b4-ae83-4484.....",
  "transfer_histories": [], // Lịch sử chuyển tiếp cuộc gọi
  "classifies": [
            {
              "name": "Khách từ chối",
              "previous_staff_node_id": "ILwHGUvlz5"
            }
          ],
  "user": [ //Danh sách nhân viên có tương tác với cuộc gọi
    {
      "full_name": "Thùy Nhân - Admin CS",
      "full_name_unsigned": "Thuy Nhan - Admin CS"
    }
  
  ],
   "call_stacks": [
             {
                "from": "0909689867", // Vị trí khởi tạo của leg call (stack)
                "to": "70759-118", //Nhân viên thuộc nhóm nội bộ
                "phone_number": "0909689867", //Số điện thoại khách hàng
                "type": "criteria-script", //Tiêu chí
                "at": 1757408394, //Thời điểm cuộc gọi đi vào nhánh
                "ringing_at": 1757408394, //Thời điểm cuộc gọi bắt đầu ring đến user
                "answer_at": 1757408400, //Thời điểm user bắt máy
                "bye_at": 1757408408, //Thời điểm kết thúc nhánh (stack)
                "index": 1,
                "is_answer": true, //Trạng thái trả lời
                "is_online": true, //Trạng thái trực tuyến
                "is_busy": false, //Trạng thái bận (user đang trong cuộc gọi khác)
                "is_dnd": false, //Trạng thái không làm phiền
                "timeout": 30
            },
}

Một vài biến JSON quan trọng cần lưu ý lúc tích hợp

Field	Type	Description
transaction_id	String	Là Id cuộc gọi. OMI có thể sẽ bắn nhiều lần cho đối tác, do cuộc gọi có thể chuyển tiếp ra nhiều lớp trong kịch bản. Và đối tác cần Get Update lại dữ liệu. Vì Id cuộc gọi là duy nhất
create_by	Object	Nhân viên chịu trách nhiệm về cuộc gọi. Trường hợp create_by.name = 'create_default_by_tenant' được dùng để định danh cuộc gọi KHÔNG XÁC ĐỊNH, KHÔNG KẾT NỐI tới nhân viên
direction	String	Hướng gọi : outbound : Gọi ra inbound : Gọi vào local : Gọi nội bộ (2 nhân viên với nhau)
answer_sec	Number	Là số giây để nhận dạng cuộc gọi TRẢ LỜI (answer_sec >0) hoặc KHÔNG TRẢ LỜI (answer_sec=0)
time_start_call	Number	Là thời gian khởi tạo cuộc gọi (x 1000 = Unix time milisecond)
time_end_call	Number	Là thời gian kết thúc cuộc (x 1000 = Unix time milisecond)
time_start_to_answer	Number	Là thời gian bắt đầu trả lời (x 1000 = Unix time milisecond)
phone_number	String	Số điện thoại khách hàng
hotline	String	Số Hotline
bill_sec	Number	Số giây tính tiền (hay Thời Lượng Cuộc Gọi)
duration	Number	Là số giây được tính từ lúc : Khởi tạo cuộc gọi -> Kết thúc
note	String	Ghi chú về cuộc gọi
tags	List	Danh sách Tags được đính kèm với cuộc gọi
sip_user	String	Là số máy lẻ của nhân viên, chịu trách nhiệm về cuộc gọi
recording_file_url	String	Đường dẫn file ghi âm
record_seconds	Number	Số giây ghi âm
user_status	List	Mảng trạng thái của nhân viên, khi có cuộc gọi đi qua

Danh sách thuộc tính mảng user_status

Field	Type	Description
extension	String	Số máy lẻ nhân viên
is_busy	Boolean	Nhân viên có đang bận (true), không bận (false)
is_dnd	Boolean	Nhân viên có đang ở trạng thái không làm phiền (true), Sẵn sàng (false)
is_online	Boolean	Nhân viên có đang trực tuyến (true), không trực tuyến (false)
group_number	String	Nhóm nội bộ (id hàng đợi)
ring_at	Number	Thời gian bắt đầu rung chuông ở nhân viên
answer_at	Number	Thời gian bắt đầu nhân viên trả lời
timeout	Number	Thời gian TimeOut của nhóm
auto_answer	Boolean	Hàng đợi bật trạng thái đếm giây(true)., không bật (false)

Webhook khi cuộc gọi đang diễn ra

• Gửi thông tin cuộc gọi đang diễn ra cho đối tác tích hợp

• Trạng thái gồm : create (Khởi tạo), early (Chuẩn bị đổ chuông), ringing(Đổ chuông), answered (Kết nối) , hangup (Kết thúc)

Cấu trúc JSON Event Gọi Ra

{
  "to_number": "0966060...", // Thuê bao người bị gọi (Callee), Số điện thoại khách hàng
  "created_time": 1748310171450, // Thời gian tạo dữ liệu json
  "extension": "2022", // Số máy lẻ nhân viên 
  "unique_id": "c5885d6d-3fb1-4393-9e1e-8b325b771191", // Id Event
  "hotline": "02873022488", // Số hotline
  "source": "webhookEvent", // Loại Webhook 
  "date_time": 1748310172296, // Thời gian gửi dữ liệu json cho đối tác 
  "from_number": "2022", // Thuê bao người gọi (Caller)
  "call_uuid": "ad97a435-659e-49b4-ae83-4484c0c3f4c6", // Id cuộc gọi
  "phone_number": "0966060...", // Số điện thoại khách hàng 
  "state": "ringing", // Trạng thái cuộc gọi
  "device": "OmiWebV2-eb2cc7f4afbd/ Chrome/ 136.0.0.0/ Windows NT 10.0; Win64; x64", // Thiết bị của Caller 
  "event_time": 1748310172250, // Thời gian khởi tao của Event
  "direction": "outbound" // Hướng gọi ,
  "event_name":""
}

Cấu trúc JSON Event Gọi Vào

{
  "to_number": "33659",// Thuê bao người bị gọi (Callee), Số máy lẻ nhân viên
  "created_time": 1748312242480, // Thời gian khởi tạo JSON
  "extension": "33659", // Số máy lẻ nhân viên
  "unique_id": "55638ccf-d18e-4246-9543-ddce371e0f9f", // Id Event
  "hotline": "842871010898", // Số hotline
  "source": "webhookEvent", // Loại Webhook 
  "date_time": 1748312314530, // Thời gian gửi JSON cho đối tác
  "from_number": "0906022...", // Thuê bao người gọi (Caller), thuê bao khách hàng
  "call_uuid": "55638ccf-d18e-4246-9543-ddce371e0f9f", // Id cuộc gọi
  "phone_number": "0906022...", // Số điện thoại khách hàng
  "state": "ringing", // Trạng thái cuộc gọi
  "device": "VOS3000 V2.1.9.07", // Thiết bị 
  "event_time": 1748312314480, //Thời gian khởi tạo Event
  "direction": "inbound" // Hướng gọi 
}

Một vài chú ý với Webhook Event

• Một cuộc gọi sẽ có 2 Leg (Leg Khách hàng , Leg Nhân viên)

• Webhook Event hỗ trợ việc callback data json, trạng thái trên mỗi Leg cho đối tác

• Nếu một cuộc gọi thành công, có kết nối máy với khách hàng, có trả lời sẽ có 3 trạng thái : ringing (Rung chuông), answered (Trả lời) , hangup (Kết thúc)

• Một vài chú ý khi gọi vào (Inbound)

  • Nếu cuộc gọi đổ vào hệ thống sẽ đi qua nhiều kịch bản mà doanh nghiệp setup

  • to_number có thể là các giá trị

    • Giá trị rỗng (empty)

      • Kịch bản chỉ phát lời chào

      • Kịch bản kết thúc không hành động,

      • Kịch bản hộp thư thoại

      • Cuộc gọi khởi tạo thành công xuống máy nhân viên, nhưng không nhận được phản hồi từ nhân viên (Do thiết bị không online, thiết bị có vấn đề)

    • Số định danh của nhóm hàng đợi nếu cuộc gọi đi vào NHÓM NỘI BỘ

    • Số định danh của kịch bản phím bấm khi cuộc gọi vào KỊCH BẢN BẤM PHÍM

    • Số định danh máy nhánh của nhân viên khi cuộc gọi vào NHÂN VIÊN (EXTENSION)

    • Số định danh của nhóm ngoài khi cuộc gọi đổ ra NHÓM NGOÀI

• from_number, to_number : Là giá trị định danh của người gọi và người bị gọi cho 2 hướng, gọi ra và gọi vào. from_number và to_number chỉ có giá trị khi có tín hiệu được khởi tạo trên mỗi Leg

  • Nếu gọi ra (outbound)

    • from_number: Số máy nhánh nhân viên

    • to_number: Số điện thoại khách hàng

  • Nếu gọi vào đổ tới nhân viên (inbound)

    • from_number : Số điện thoại khách hàng

    • to_number : Số máy nhánh nhân viên