# Webhook

## 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***

{% hint style="info" %}
**Webhook data khi cuộc gọi đã kết thúc**
{% endhint %}

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

<figure><img src="https://3454047468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LukDt3aTxo8xMLonIwO%2Fuploads%2F7HpBckIrHke7yN7ju6wz%2FUntitled.jpg?alt=media&#x26;token=35e7c32a-c941-4b63-a642-af2f78db4f4b" alt=""><figcaption></figcaption></figure>

```

{
  "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**

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

Danh sách thuộc tính mảng **user\_status**

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

{% hint style="info" %}
**Webhook khi cuộc gọi đang diễn ra**
{% endhint %}

* 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 (**&#x4B;hởi tạ&#x6F;**), early (**&#x43;huẩn bị đổ chuôn&#x67;**), ringing**(Đổ chuông)**, answered** (Kết nối) , **hangup** (Kết thúc)

<figure><img src="https://3454047468-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LukDt3aTxo8xMLonIwO%2Fuploads%2FNmYsmhNbOGDp0LmF3LDe%2FScreenshot%202025-06-09%20at%209.08.20%E2%80%AFAM.png?alt=media&#x26;token=962f06e7-f3dc-4944-bcfa-fb24e82098a1" alt=""><figcaption></figcaption></figure>

**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)**
  * &#x20;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ị&#x20;
    * Giá trị rỗng (empty)&#x20;
      * Kịch bản chỉ phát lời chào
      * Kịch bản kết thúc không hành động,&#x20;
      * 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Ộ&#x20;
    * 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