# Giới thiệu

Đây là tài liệu tham khảo cho các nhà phát triển tích hợp nền tảng CareSoft vào môi trường làm việc của khách hàng.

## Tổng quan

Trang này cung cấp các trợ giúp để tích hợp gồm

* Restful API:  Tạo phiếu ghi, khách hàng và truy xuất lịch sử tương tác
* Voice API: Tạo cuộc gọi từ ứng dụng của khách thông qua nền tảng CareSoft
* Widget: Tạo và cấu hình các form nhúng thu thập yêu cầu của khách hàng hoặc các hộp live chat
* Apps: Các ứng dụng phổ biến mà CareSoft có thể hỗ trợ hiển thị thông tin như KiotViet, Haravan

## Thông tin cần thiết?

 Các thông tin cơ bản cần thiết để tích hợp Restful API CareSoft vào hệ thống của bạn

{% content-ref url="/pages/pWtFAw3Awp43J4MN9Hrh" %}
[Thông tin chung](/thong-tin-chung)
{% endcontent-ref %}

## Chuyên sâu

Chi tiết các API CareSoft cung cấp

{% content-ref url="/pages/ZvVoV4AtG3Df0i6nIVxW" %}
[Restful Api của CareSoft](/danh-muc/restful-api-cua-caresoft)
{% endcontent-ref %}

## Tích hợp thoại

Cách thức tích hợp thực hiện cuộc gọi thông qua nền tảng CareSoft từ CRM/ERP của khách hàng

{% content-ref url="/pages/l4OiAffMMCEbMLmmZo9A" %}
[Tích hợp thoại](/danh-muc/tich-hop-thoai)
{% endcontent-ref %}

## Một số mẫu tích hợp điển hình

Hướng dẫn một số trường hợp tích hợp hệ thống điển hình 

{% content-ref url="/pages/ZhQqE2KyPY8HJeJRtd8k" %}
[Case study](/danh-muc/case-study)
{% endcontent-ref %}


# Thông tin chung

Các thông tin cần thiết để tích hợp nền tảng CareSoft vào môi trường làm việc của bạn

## **Các thông tin cơ bản**

* Domain: Là chuỗi ký tự đại diện cho một tài khoản doanh nghiệp mà khách hàng sử dụng trên nền tảng CareSoft.  Ví dụ sau khi ký hợp đồng và triển khai nghiệp vụ caresoft bàn giao cho khách hàng địa chỉ đăng nhập là `https://caresoft.vn/`**`khachhang01`**  thì chuỗi "**khachhang01**" sẽ được gọi là domain trên hệ thống CareSoft.  Trong các API sẽ định nghĩa phần này bằng biến <mark style="color:green;background-color:purple;">`{{domain}}`</mark>. Domain này do CareSoft cung cấp cho mỗi khách hàng.
* Api token: Là chuỗi mã bảo mật được cấu hình trên hệ thống CareSoft. Token chỉ thay đổi khi người quản trị bấm nút reset trên màn hình cấu hình. Trong các API sẽ định nghĩa phần này bằng biến <mark style="color:green;">`{{apiToken}}`</mark>.&#x20;
* Host: Là địa chỉ gốc để truy cập các api. CareSoft sử dụng địa chỉ

  * `https://api.caresoft.vn/` làm địa chỉ gốc, dự phòng là&#x20;
  * `https://api2.caresoft.vn/`

  Các mô tả dưới đây sẽ mặc định kèm tiền tố host ở đầu mỗi truy xuất \
  **Ví dụ**: Tài liệu mô tả lấy danh sách agent sẽ ghi `GET {domain}/api/v1/agents.` Khi truy xuất sẽ nối chuỗi thành `https://api.caresoft.vn/{domain}/api/v1/agents`

## Cách lấy Api Token trên giao diện CareSoft

Để lấy API Token. Cần tài khoản Admin để đăng nhập vào tài khoản trên hệ thống CareSoft, Truy cập vào phần <mark style="color:green;">`Admin-->Api -->Api token`</mark>

{% hint style="info" %}
Bạn có thể khởi tạo và cập nhật bất cứ lúc nào. Lưu ý nếu thay đổi API KEY này các chương trình đang tích hợp sẽ bị mất kết nối.&#x20;
{% endhint %}

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FFIrQi1MV6pJmOJmZpziH%2FTaoAPI.png?alt=media&amp;token=6e7c4122-5462-4fb8-86c7-36dac8128785" alt=""><figcaption><p>Màn hình cấu hình tạo và nhận kết quả API token trên hệ thống Caresoft</p></figcaption></figure>

## Phương thức xác thực

Xác thực qua access token, mỗi domain (account) sẽ được cấp 1 access token, yêu cầu tất cả các request gọi lên đều phải thêm "Authorization" header, kiểu dữ liệu yêu cầu là Json.&#x20;

Các API được mô tả trong tài liệu này ngầm hiểu đã được đính kèm\
&#x20;<mark style="color:green;background-color:green;">`Authorization`</mark> và <mark style="color:green;">`Content-Type`</mark> trong header &#x20;

Ví dụ về set header vào request lấy danh sách chuyên viên

```bash
curl 
--location 'https://api.caresoft.vn/{{domain}}/api/v1/agents' \
--header 'Authorization: Bearer {{apiToken}}' \
--header 'Content-Type: application/json'

```

## Tạo request đầu tiên

Thử nghiệm với API danh sách khách hàng để hiểu cơ chế hoạt động của hệ thống&#x20;

## Lấy danh sách Agents

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/agents`

Lấy danh sách các agent của 1 domain trên hệ thống CareSoft

#### Headers

| Name                                            | Type                | Description                       |
| ----------------------------------------------- | ------------------- | --------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | Bearer {{apiToken}} | Mã API token từ hệ thống CareSoft |
| Content-Type<mark style="color:red;">\*</mark>  | application/json    | Kiểu dữ liệu                      |

{% tabs %}
{% tab title="200: OK Thành công" %}
{% tabs %}
{% tab title="Ví dụ điển hình" %}

```json
{
    "code": "ok",
    "agents": [
        {
            "id": 142928097,
            "username": "Sample",
            "email": "DiegoS@50pdp0.onmicrosoft.com",
            "phone_no": "0336842288",
            "agent_id": "50007",
            "created_at": "2022-07-08 09:48:41",
            "updated_at": "2022-08-08 17:42:08",
            "group_id": 12153,
            "group_name": "Default Group",
            "role_id": 1,
            "login_status": "AVAILABLE",
            "call_status": "AVAILABLE"
        }
        ]
}
```

{% endtab %}

{% tab title="Cấu trúc kết quả" %}

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="401: Unauthorized Sai API Token hoặc không cung cấp API Token" %}
{% tabs %}
{% tab title="Cấu trúc kết quả" %}

<table><thead><tr><th width="117" data-type="number">STT</th><th>Tên trường</th><th>Ghi chú</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>Trạng thái: <br>- errors: Lỗi</td></tr><tr><td>2</td><td>message</td><td><pre><code>Authorization header is either missing or incorrect
</code></pre></td></tr></tbody></table>
{% endtab %}

{% tab title="Ví dụ điển hình" %}

```json
{
    "code": "errors",
    "message": "Authorization header is either missing or incorrect"
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="500: Internal Server Error Lỗi chung " %}

{% endtab %}

{% tab title="422: Unprocessable Entity Thiếu thông tin đầu vào (một số trường hợp)" %}

{% endtab %}

{% tab title="404: Not Found Không tìm thấy tài nguyên, Lỗi này kiểm tra lại API Url xem chính xác hay chưa" %}

{% endtab %}
{% endtabs %}

<table><thead><tr><th width="66" data-type="number">STT</th><th>Tên trường</th><th width="227">Ghi chú</th><th>Kiểu dữ liệu</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>Trạng thái kết quả api: <br>-  ok:  Có kết quả<br>-  errors: Lỗi </td><td>String</td></tr><tr><td>2</td><td>agents</td><td>Mảng dữ liệu danh sách chuyên viên</td><td>Array []</td></tr><tr><td>3</td><td>agents.id</td><td>ID người dùng trên toàn hệ thống</td><td>Int</td></tr><tr><td>4</td><td>agents.username</td><td>Họ tên</td><td>String</td></tr><tr><td>5</td><td>agents.email</td><td>Email của chuyên viên</td><td>Email</td></tr><tr><td>6</td><td>agents.phone_no</td><td>Số điện thoại của chuyên viên</td><td>String</td></tr><tr><td>7</td><td>agents.agent_id</td><td>Mã Ipphone của chuyên viên</td><td>Int</td></tr><tr><td>8</td><td>agents.updated_at</td><td>Ngày cập nhật dữ liệu</td><td>DateTime</td></tr><tr><td>9</td><td>agents.created_at</td><td>Ngày tạo</td><td>DateTime</td></tr><tr><td>10</td><td>agents.login_status</td><td><p>Trạng thái đăng nhập có các giá trị</p><ul><li><code>AVAILABLE: Đang đăng nhập</code> </li><li><code>NOTAVAILABLE: Không đăng nhập</code><br></li></ul></td><td>String</td></tr><tr><td>11</td><td>agents.call_status</td><td><p>Trạng thái thoại có các giá trị</p><ul><li><code>AVAILABLE: Đang đăng nhập</code> </li><li><code>NOTAVAILABLE: Không đăng nhập</code><br></li></ul></td><td>String</td></tr><tr><td>12</td><td>agents.group_id</td><td>ID phòng ban của chuyên viên (*)</td><td>Int</td></tr><tr><td>13</td><td>agents.group_name</td><td>Tên phòng ban</td><td>String</td></tr><tr><td>14</td><td>agents.role_id</td><td><p>Vai trò của chuyên viên <br>Trong đó: </p><p><code>1: Admin</code><br><code>2: Chuyên viên</code></p><p><code>4: Supper</code></p><p><code>5: Sub Admin</code></p><p><code>6: Máy nhánh (ext)</code></p><p><code>7: Mobile</code></p><p><code>8: Chuyên viên QA</code></p><p><code>9: Qa lead</code></p><p></p></td><td>Int</td></tr></tbody></table>

Ví dụ điển hình khi triệu gọi API CareSoft qua `curl`: Bạn cũng có thể áp dụng  để tạo Api call trên ứng dụng của bạn hoặc trên ứng dụng  Postman&#x20;

{% tabs %}
{% tab title="curl" %}
{% code title="Cấu hình curl với thông tin xác thực" overflow="wrap" %}

```sh

curl 
--location 'https://api.caresoft.vn/{{domain}}/api/v1/agents' \
--header 'Authorization: Bearer {{apiToken}}' \
--header 'Content-Type: application/json'

```

{% endcode %}
{% endtab %}

{% tab title="postman" %}

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2F1LGQqiIyQRszKuN0Oh5P%2FCauhinhPostman.png?alt=media&amp;token=bd95012c-ec40-4a69-8d11-34cd86250d61" alt=""><figcaption><p>Cấu hình chèn thông tin xác thực trên postman</p></figcaption></figure>
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Lưu ý:** Trong một số trường hợp thông tin yêu cầu bắt buộc được trả về trong body response. Cần kiểm tra thêm dữ liệu trả về để xử lý lỗi. Các trường hợp như vậy CareSoft sẽ mô tả rõ trong từng API chi tiết
{% endhint %}

## **THAM KHẢO**&#x20;

* **POSTMAN**\
  \
  Postman là một loại công cụ cho phép người dùng có thể thao tác với API, mà trong đó phổ biến nhất là REST. Với thử nghiệm API thì Postman là một trong những công cụ phổ biến vì được thực nghiệm nhiều nhất. Nhờ Postman lập trình viên có thể gọi Rest API mà không cần phải viết bất kỳ dòng code nào. Postman có khả năng hỗ trợ mọi phương thức HTTP bao gồm: POST, PUT, DELETE, PATCH, GET,... Ngoài ra, Postman còn cho phép lập trình viên lưu lại lịch sử của các lần request nên vô cùng tiện lợi cho nhu cầu sử dụng lại.\
  \
  Đây là loại công cụ mã nguồn mở nên rất dễ để tải về.  Bạn cần truy cập vào website: <https://www.getpostman.com/downloads/>. Sau đó lựa chọn nền tảng mà bạn muốn tải (có thể là Windows, Linux hoặc Mac).

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FKiewIETOc0HcPEKk9R0C%2FPOSTMAN.png?alt=media&amp;token=0898dbc1-9264-4336-81a6-3fa2885949d2" alt=""><figcaption><p>Giao diện trang web postman </p></figcaption></figure>


# Phân trang dữ liệu

Hệ thống API  CareSoft có giới hạn về số bản ghi tối đa được gọi về và số lần call API trong giây

Mặc định rpp là <mark style="color:green;">**50 bản ghi**</mark>, tối đa là <mark style="color:orange;">**500 bản ghi/ lượt request**</mark>

Trong các api trả về luôn có biến số numFound là số lượng bản ghi đáp ứng yêu cầu triệu goi. Để chuyển trang dữ liệu sử dụng đồng thời các tham số kèm theo. \ <mark style="color:green;">`page:`</mark>` ``Số trang (Int)`\ <mark style="color:green;">`count:`</mark>` ``Số bản ghi cần lấy  (int)`&#x20;

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FhRraa5gQBpdLs8D7A3xT%2FPhantrang.png?alt=media&amp;token=aa737771-957c-483c-ae0b-7fdbc4415cbb" alt=""><figcaption><p>Bổ sung thêm param page, count vào mỗi request để chuyển trạng</p></figcaption></figure>


# Trường động (Custom fields)

Trường dữ liệu mở rộng, có thể tùy chỉnh trên Caresoft

Trên nền tảng CareSoft, có 3 đối tượng dữ liệu chính gồm: `Phiếu ghi` (tickets), `Khách hàng` (contacts) và `Tổ chức` (organizations)&#x20;

Các đối tượng dữ liệu trên ngoài các trường thông tin cố định thì còn được cung cấp thêm 20 trường dữ liệu cho mỗi loại. CareSoft gọi nó là trường động, kèm với đối tượng dữ liệu đó, ví dụ: **Trường động khách hàng**, **trường động phiếu ghi**...

Các trường động có nhiều kiểu dữ liệu khác nhau, mục đích nhằm phân loại và khai thác dữ liệu sâu hơn.&#x20;

Để tạo ra các trường động, admin của từng domain sẽ sử dụng giao diện CareSoft và vào từng Đối tượng thông tin để thực hiện cấu hình.

*Ảnh minh họa danh sách và cấu hình trường động phiếu ghi trên giao diện CareSoft*&#x20;

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FCjhXuwH6xfibYOVSaLSQ%2FticketAditionField.png?alt=media&amp;token=f6b55544-750f-48e8-8f00-c08cebe6cc72" alt=""><figcaption></figcaption></figure>

## Danh sách kiểu dữ liệu&#x20;

Bảng kê dưới đây mô tả kiểu dữ liệu, ứng dụng và đối tượng áp dụng của chúng&#x20;

<table><thead><tr><th width="69.33333333333331">STT</th><th width="186">Tên kiểu</th><th width="295">Đối tượng áp dụng<select multiple><option value="6d2ea5a5451848469a8f1a4a0b8ff498" label="Phiếu ghi" color="blue"></option><option value="5a39453cd0fe45169e8304b7ea5c5b3b" label="Khách hàng" color="blue"></option><option value="8fe5c0930fd24c8c9487ec82ddc0e40a" label="Tổ chức" color="blue"></option></select></th><th>Ý nghĩa</th></tr></thead><tbody><tr><td>1</td><td>TEXT</td><td><span data-option="6d2ea5a5451848469a8f1a4a0b8ff498">Phiếu ghi, </span><span data-option="5a39453cd0fe45169e8304b7ea5c5b3b">Khách hàng, </span><span data-option="8fe5c0930fd24c8c9487ec82ddc0e40a">Tổ chức</span></td><td>Ký tự</td></tr><tr><td>2</td><td>NUMERIC</td><td><span data-option="6d2ea5a5451848469a8f1a4a0b8ff498">Phiếu ghi, </span><span data-option="5a39453cd0fe45169e8304b7ea5c5b3b">Khách hàng, </span><span data-option="8fe5c0930fd24c8c9487ec82ddc0e40a">Tổ chức</span></td><td>Số </td></tr><tr><td>3</td><td>DATE</td><td><span data-option="6d2ea5a5451848469a8f1a4a0b8ff498">Phiếu ghi, </span><span data-option="5a39453cd0fe45169e8304b7ea5c5b3b">Khách hàng, </span><span data-option="8fe5c0930fd24c8c9487ec82ddc0e40a">Tổ chức</span></td><td>Ngày tháng<br>Định dạng (YYYY/MM/DD) </td></tr><tr><td>4</td><td>SINGLE DROP-DOWN LIST</td><td><span data-option="6d2ea5a5451848469a8f1a4a0b8ff498">Phiếu ghi, </span><span data-option="5a39453cd0fe45169e8304b7ea5c5b3b">Khách hàng, </span><span data-option="8fe5c0930fd24c8c9487ec82ddc0e40a">Tổ chức</span></td><td>Chọn 1 giá trị</td></tr><tr><td>5</td><td>MULTIPLE  DROP-DOWN LIST</td><td><span data-option="6d2ea5a5451848469a8f1a4a0b8ff498">Phiếu ghi, </span><span data-option="5a39453cd0fe45169e8304b7ea5c5b3b">Khách hàng, </span><span data-option="8fe5c0930fd24c8c9487ec82ddc0e40a">Tổ chức</span></td><td>Chọn nhiều giá trị</td></tr><tr><td>6</td><td>URL</td><td><span data-option="6d2ea5a5451848469a8f1a4a0b8ff498">Phiếu ghi</span></td><td>Liên kết</td></tr><tr><td>7</td><td>TEXTAREA</td><td><span data-option="6d2ea5a5451848469a8f1a4a0b8ff498">Phiếu ghi</span></td><td>Văn bản</td></tr><tr><td>8</td><td>STAGE</td><td><span data-option="6d2ea5a5451848469a8f1a4a0b8ff498">Phiếu ghi</span></td><td>Tiến trình (salefunnel) </td></tr></tbody></table>

## Cấu trúc thông tin trường động

Thực hiện lấy cấu hình các trường động. Tùy theo kiểu dữ liệu của trường động, các trường thông tin trong đó cũng sẽ thay đổi theo&#x20;

{% code title="Đối tượng trường động điển hình" %}

```json
[{
            "custom_field_id": 6740,
            "custom_field_lable": "Phân loại",
            "type": "Single drop-down list",
            "code":null, 
            "values": [
                {
                    "id": 109398,
                    "lable": "Đơn mua",
                    "code":"DONMUA",
                    "parent_value_id": -1
                },
                {
                    "id": 109399,
                    "code":"HOTRO",
                    "lable": "Hỗ trợ khách hàng",
                    "parent_value_id": -1
                }
            ]
        },       
       {   "custom_field_id": 6103,
           "code":"MADONHANG",
            "custom_field_lable": "Mã đơn hàng",
            "type": "Text"
        }]
```

{% endcode %}

Ý nghĩa các trường thông tin&#x20;

<table><thead><tr><th width="242.33333333333331">Tên trường</th><th>Ý nghĩa</th><th>Ghi chú</th></tr></thead><tbody><tr><td><code>custom_field_id</code><br>(int)</td><td>ID của trường dữ liệu</td><td></td></tr><tr><td><code>custom_field_lable</code><br>(string)</td><td>Tên trường </td><td></td></tr><tr><td><code>type</code><br>(string)</td><td>Kiểu dữ liệu </td><td>(trong danh sách kiểu) <a data-mention href="#danh-sach-kieu-du-lieu">#danh-sach-kieu-du-lieu</a></td></tr><tr><td><code>values</code><br>(array)</td><td>Giá trị lựa chọn. Đối với kiểu trường lựa chọn, chọn nhiều hay tiến trình. trường dữ liệu này chứa các giá trị định sẵn với ID riêng và nhãn cho từng  lựa chọn. </td><td><strong>Chỉ có với các kiểu dữ liệu:</strong><br>- <code>SINGLE DROP-DOWN LIST</code><br>- <code>MULTIPLE  DROP-DOWN LIST</code><br>- <code>STAGE</code></td></tr><tr><td>code</td><td>Mã trường động tự cấu hình (trong giao diện cấu hình)</td><td>Dùng để mapping các trường dữ liệu giữa các hệ thống</td></tr></tbody></table>

Chi tiết đối tượng Values của các trường dạng `SINGLE DROP-DOWN LIST, MULTIPLE  DROP-DOWN LIST, và STAGE`

<pre data-title="(click vào field để xem) "><code>"<a data-footnote-ref href="#user-content-fn-1">values</a>": [
                {
                    "<a data-footnote-ref href="#user-content-fn-2">id</a>": 109398,
                    "<a data-footnote-ref href="#user-content-fn-3">lable</a>": "Đơn mua",
                    "code":"DONMUA"
                    "<a data-footnote-ref href="#user-content-fn-4">parent_value_id</a>": -1
                },
<strong>                {
</strong>                    "id": 109399,
                    "lable": "Hỗ trợ khách hàng",
                    "code":"HOTRO",
                    "parent_value_id": -1
                }
            ]
</code></pre>

## Cách thức khai thác thông tin&#x20;

Để biết các đối tượng trên có những trường động nào. Lập trình viên sử dụng từng Api riêng lẻ dưới đây để thực hiện lấy về các thông tin đã cấu hình.

{% hint style="info" %}
LƯU Ý:  Trong quá trình vận hành Admin của domain có thể xóa, sửa tên, sửa kiểu dữ liệu hoặc thêm mới trường thông tin. Cần có cơ chế đồng bộ định kỳ hằng ngày để đảm bảo thông tin thông suốt&#x20;
{% endhint %}

### Trường động phiếu ghi

## Danh sách trường động phiếu ghi

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/tickets/custom_fields`

#### Headers

| Name   | Type   | Description                                  |
| ------ | ------ | -------------------------------------------- |
| \*\*\* | String | [Thông tin xác thực chung](/thong-tin-chung) |

{% tabs %}
{% tab title="200: OK " %}
{% code title="Kết quả điển hình" %}

```json
{
    "code": "ok",
    "custom_fields": [
        {
            "custom_field_id": 5164,
            "code":"PHANLOAI",
            "custom_field_lable": "Phân loại phiếu ghi( Không được đổi của Liên)",
            "type": "Single drop-down list",
            "values": [
                {
                    "id": 89496,
                    "code":"TIENTRINHDEAL",
                    "lable": "Tiến trình Leads",
                    "parent_value_id": -1
                },
                {
                    "id": 89497,
                    "lable": "Tiến trình Deals",
                    "code":"null",
                    "parent_value_id": -1
                },
                {
                    "id": 98211,
                    "code":"KHIEUNAI",
                    "lable": "Case Khiếu nại",
                    "parent_value_id": -1
                }
            ]
        },
        {
            "custom_field_id": 6068,
            "custom_field_lable": "Phân loại tương tác",
            "code":"TUONGTAC",
            "type": "Single drop-down list",
            "values": [
                {
                    "id": 106902,
                    "lable": "Spam",
                    "code":"null",
                    "parent_value_id": -1
                },
                {
                    "id": 106903,
                     "code":"null",
                    "lable": "Nội dung",
                    "parent_value_id": -1
                }
            ]
        },

```

{% endcode %}

{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="400: Bad Request " %}

{% endtab %}
{% endtabs %}

### Trường động khách hàng

## Danh sách trường động khách hàng

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/contacts/custom_fields`

#### Headers

| Name                                     | Type   | Description                                  |
| ---------------------------------------- | ------ | -------------------------------------------- |
| \*\*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung](/thong-tin-chung) |

{% tabs %}
{% tab title="200: OK Tương tự trường động phiếu ghi" %}

{% endtab %}
{% endtabs %}

### Trường động tổ chức

## Danh sách trường động tổ chức

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/organizations/custom_fields`

#### Headers

| Name                                   | Type   | Description                                  |
| -------------------------------------- | ------ | -------------------------------------------- |
| \*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung](/thong-tin-chung) |

{% tabs %}
{% tab title="200: OK Tương tự trường động phiếu ghi" %}

{% endtab %}
{% endtabs %}

Khi lấy về thông tin trường động, cách tốt để tích hợp là làm 1 bảng dữ liệu mapping trường dữ liệu tương ứng từ CRM sang CareSoft<br>

*Ví dụ:* 1 Bảng dữ liệu mapping với trường  trạng thái đơn hàng từ CRM sang CareSoft tương ứng

<table><thead><tr><th>crmField</th><th width="155.33333333333331">crmValue</th><th>caresoftField</th><th>caresoftValue</th></tr></thead><tbody><tr><td>orderStatus</td><td>New</td><td><a data-footnote-ref href="#user-content-fn-5">6740</a></td><td><a data-footnote-ref href="#user-content-fn-6">109398</a></td></tr><tr><td>orderStatus</td><td>Delivery</td><td>6740</td><td>109399</td></tr><tr><td>orderStatus</td><td>Payment</td><td>6740</td><td>109400</td></tr></tbody></table>

Khi tạo mới thông tin sang CareSoft, Object custom\_fields sẽ được trình bày bằng cấu trúc sau

{% code overflow="wrap" %}

```json
{
  "username" : "...", 
  "custom_fields" : [
    {
     "id": "{{custom_field_id: ID của trường động}}",
     "value": "{{Giá trị muốn truyền vào nếu trường động kiểu Date/Text/Number/Url/Textarea hoặc ID values của lựa chọn nếu là kiểu Single Select, State hoặc Multiple Select}}" 
     },
         .....
    ]
   }
```

{% endcode %}

{% hint style="info" %}
**DEMO:** \
Ứng dụng, tạo mới phiếu ghi kèm thông tin trường động [xem tại đây](/danh-muc/restful-api-cua-caresoft/tao-phieu-ghi-lead-deal-kem-thong-tin-truong-dong). Các đối tượng dữ liệu khác thực hiện tương tự&#x20;
{% endhint %}

[^1]: Mảng giá trị trường động dạng lựa chọn&#x20;

[^2]: Id lựa chọn

[^3]: Tên lựa chọn

[^4]: Id trường cha của lựa chọn&#x20;

[^5]: ID trường động dạng chọn 1&#x20;

[^6]: ID Giá trị lựa chọn tương ứng với  trạng thái New trên CRM&#x20;


# Rate limit - Giới hạn yêu cầu

Các API CareSoft được giới hạn số lần yêu cầu tối đa  15 lần/giây hay 54.000 lần/ giờ . Quá số lượt này hệ thống sẽ nhận diện là **request spam** và hạn chế giao tiếp vào hệ thống theo thời gian tăng dần.

Khi hết số lượng request theo giờ. Hệ thống sẽ thông báo lỗi 429.

{% code title="Mã 429" %}

```json
{code:"errors",message:"Too Many Attempts."}
```

{% endcode %}

Nếu request tiếp tục bị gọi vào. Hệ thống sẽ đếm số lần lỗi 429 và quá 20 lần liên tiếp sau lỗi 429 sẽ có thông báo lỗi 404. &#x20;

{% code title="Mã 404" %}

```json
{
    "code": "errors",
    "message": "Domain incorrect too many times , retry after 15 minutes "
}
```

{% endcode %}

Khi phát sinh lỗi này cần phải tạm dừng gọi API tới hệ thống theo thời gian yêu cầu.&#x20;


# Restful Api của CareSoft

Danh mục các API có thể khai thác trên hệ thống CareSoft

## Phiếu ghi

Các API liên quan đến thêm mới, cập nhật, thông tin trường dữ liệu, danh sách của phiếu ghi

{% content-ref url="/pages/F0R3JcyjSskq3JJ6jvD7" %}
[Phiếu ghi](/danh-muc/restful-api-cua-caresoft/phieu-ghi)
{% endcontent-ref %}

## Người dùng/ Khách hàng

Các api liên quan đến thêm mới, cập nhật, thông tin trường dữ liệu tùy biến, danh sách chi tiết của người dùng

{% content-ref url="/pages/pgCczgsdxwC9jFJMPgP9" %}
[Khách hàng](/danh-muc/restful-api-cua-caresoft/khach-hang)
{% endcontent-ref %}

## Chiến dịch

Các API liên quan đến chiến dịch: Thêm mới khách hàng, thêm hành động, lấy kết quả chiến dịch..

{% content-ref url="/pages/LvaC6AM8Jws45s0NsXek" %}
[Chiến dịch](/danh-muc/restful-api-cua-caresoft/chien-dich)
{% endcontent-ref %}

## Cuộc gọi&#x20;

Các API liên quan đến cuộc gọi thoại trên CareSoft: Lịch sử cuộc gọi, file ghi âm...&#x20;

{% content-ref url="/pages/Yc3UhvLjhlUVbKeAuGDM" %}
[Cuộc gọi](/danh-muc/restful-api-cua-caresoft/cuoc-goi)
{% endcontent-ref %}

## Chat

Các API Liên quan đến truy xuất dữ liệu chat trên CareSoft: Lịch sử chat

{% content-ref url="/pages/Hcv9on7RyGOSqRYZBl14" %}
[Chat](/danh-muc/restful-api-cua-caresoft/chat)
{% endcontent-ref %}


# Chuyên viên

Các thông tin cần thiết để tích hợp nền tảng CareSoft vào môi trường làm việc của bạn.

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FoYc19jzzfOV7pTXqWH8a%2Fimage.png?alt=media&amp;token=70c7842f-8336-41b1-ab5c-e166e6c4f362" alt=""><figcaption><p>Giao diện cấu hình chuyên viên hệ thống CareSoft </p></figcaption></figure>

Chuyên viên trên hệ thống CareSoft tương đương với một nhân viên nghiệp vụ ở môi trường doanh nghiệp thực tế.&#x20;

{% hint style="info" %}
**Lưu ý:**  Danh sách chuyên viên sẽ thay đổi khi doanh nghiệp tăng, giảm số lượng thuê bao hoặc chuyển phòng ban. Cần thiết lập cơ chế tự đồng bộ lại hàng tuần để đảm bảo thông tin chính xác.
{% endhint %}

{% hint style="info" %}
**Gợi ý**: Sử dụng email của nhân viên hoặc số điện thoại của nhân viên trong doanh nghiệp để làm key liên kết thông tin sau đó lưu danh sách này trên CSDL của doanh nghiệp, đặt lịch mỗi ngày quét lại danh sách này 1 lần để đồng bộ thông tin để đảm bảo thông tin giữa CRM/ERP của khách hàng luôn đồng nhất với các tài khoản thuê bao trên CareSoft.&#x20;
{% endhint %}

## Lấy danh sách Agents

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/agents`

Lấy danh sách các chuyên viên của 1 domain trên hệ thống CareSoft

#### Headers

| Name                                  | Type | Description                                                        |
| ------------------------------------- | ---- | ------------------------------------------------------------------ |
| \* <mark style="color:red;">\*</mark> |      | [Thông tin xác thực chung ](/thong-tin-chung#phuong-thuc-xac-thuc) |

{% tabs %}
{% tab title="200: OK Thành công" %}
{% tabs %}
{% tab title="Ví dụ điển hình" %}

```json
{
    "code": "ok",
    "agents": [
        {
            "id": 142928097,
            "username": "Sample",
            "email": "DiegoS@50pdp0.onmicrosoft.com",
            "phone_no": "0336842288",
            "agent_id": "50007",
            "created_at": "2022-07-08 09:48:41",
            "updated_at": "2022-08-08 17:42:08",
            "group_id": 12153,
            "group_name": "Default Group",
            "role_id": 1,
            "login_status": "AVAILABLE",
            "call_status": "AVAILABLE"
        }
        ]
}
```

{% endtab %}

{% tab title="Cấu trúc kết quả" %}

<table><thead><tr><th width="66" data-type="number">STT</th><th>Tên trường</th><th width="227">Ghi chú</th><th>Kiểu dữ liệu</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>Trạng thái kết quả api: <br>-  ok:  Có kết quả<br>-  errors: Lỗi </td><td>String</td></tr><tr><td>2</td><td>agents</td><td>Mảng dữ liệu danh sách chuyên viên</td><td>Array []</td></tr><tr><td>3</td><td>agents.id</td><td>ID người dùng trên toàn hệ thống</td><td>Int</td></tr><tr><td>4</td><td>agents.username</td><td>Họ tên</td><td>String</td></tr><tr><td>5</td><td>agents.email</td><td>Email của chuyên viên</td><td>Email</td></tr><tr><td>6</td><td>agents.phone_no</td><td>Số điện thoại của chuyên viên</td><td>String</td></tr><tr><td>7</td><td>agents.agent_id</td><td>Mã Ipphone của chuyên viên</td><td>Int</td></tr><tr><td>8</td><td>agents.updated_at</td><td>Ngày cập nhật dữ liệu</td><td>DateTime</td></tr><tr><td>9</td><td>agents.created_at</td><td>Ngày tạo</td><td>DateTime</td></tr><tr><td>10</td><td>agents.ticket_status</td><td><p>Trạng thái đăng nhập có các giá trị</p><ul><li><code>AVAILABLE: Đang đăng nhập</code> </li><li><code>NOT AVAILABLE: Không đăng nhập</code></li><li>LOGOUT: Đằng xuất  <br></li></ul></td><td>String</td></tr><tr><td>11</td><td>agents.call_status</td><td><p>Trạng thái thoại có các giá trị</p><ul><li><code>AVAILABLE: Đang đăng nhập</code> </li><li><code>NO ANSWER: Trạng thái được trả về khi Agent không trả lời số lượng cuộc gọi liên tiếp vượt quá ngưỡng cấu hình (NUM_CALL_CHANGE_NO_ANSWER_WEBPHONE hoặc NUM_CALL_CHANGE_NO_ANSWER_IPPHONE, mặc định 3) được cấu hình trong tài khoản hệ thống</code></li><li><code>NOT AVAILABLE: Không đăng nhập</code><br></li><li><code>LOGOUT: Đăng xuất tất cả hoặc (Đăng xuất không chọn tất cả thiết bị nhưng ở trạng thái: Nghe gọi qua IP Phone,  Nghe gọi qua trình duyệt)</code><br><br><strong>Trong trường hợp đăng xuất không chọn tất cả các thiết bị thì ở các phương thức sau hệ thỗng sẽ giữ trạng thái trước đó</strong></li><li>Nghe gọi qua IP Phone/Softphone (Phải đăng nhập) </li><li> Chuyển cuộc gọi ra số di động </li><li>Nghe gọi qua ứng dụng di động <br></li></ul></td><td>String</td></tr><tr><td>12</td><td>agents.chat_status</td><td><p></p><ul><li><code>AVAILABLE: Đang đăng nhập</code> </li><li><code>NOT AVAILABLE: Không đăng nhập</code></li><li>LOGOUT: Đằng xuất</li></ul><p><strong>Trong trường hợp đăng xuất không chọn tất cả các thiết bị thì ở các phương thức sau hệ thỗng sẽ giữ trạng thái trước đó</strong> </p></td><td></td></tr><tr><td>13</td><td>agents.group_id</td><td>ID phòng ban của chuyên viên (*)</td><td>Int</td></tr><tr><td>14</td><td>agents.group_name</td><td>Tên phòng ban</td><td>String</td></tr><tr><td>15</td><td>agents.role_id</td><td><p>Vai trò của chuyên viên <br>Trong đó: </p><p><code>1: Admin</code><br><code>2: Chuyên viên</code></p><p><code>4: Supper</code></p><p><code>5: Sub Admin</code></p><p><code>6: Máy nhánh (ext)</code></p><p><code>7: Mobile</code></p><p><code>8: Chuyên viên QA</code></p><p><code>9: Qa lead</code></p><p></p></td><td>Int</td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="401: Unauthorized Sai API Token hoặc không cung cấp API Token" %}
{% tabs %}
{% tab title="Cấu trúc kết quả" %}

<table><thead><tr><th width="117" data-type="number">STT</th><th>Tên trường</th><th>Ghi chú</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>Trạng thái: <br>- errors: Lỗi</td></tr><tr><td>2</td><td>message</td><td><pre><code>Authorization header is either missing or incorrect
</code></pre></td></tr></tbody></table>
{% endtab %}

{% tab title="Ví dụ điển hình" %}

```json
{
    "code": "errors",
    "message": "Authorization header is either missing or incorrect"
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="500: Internal Server Error Lỗi chung " %}

{% endtab %}

{% tab title="422: Unprocessable Entity Thiếu thông tin đầu vào (một số trường hợp)" %}

{% endtab %}

{% tab title="404: Not Found Không tìm thấy tài nguyên, Lỗi này kiểm tra lại API Url xem chính xác hay chưa" %}

{% endtab %}
{% endtabs %}

Ví dụ điển hình khi triệu gọi API CareSoft qua `curl`: Bạn cũng có thể áp dụng  để tạo Api call trên ứng dụng của bạn hoặc trên ứng dụng  Postman&#x20;

{% tabs %}
{% tab title="curl" %}
{% code overflow="wrap" %}

```

curl 
--location 'https://api.caresoft.vn/{{domain}}/api/v1/agents' \
--header 'Authorization: Bearer {{apiToken}}' \
--header 'Content-Type: application/json'

```

{% endcode %}
{% endtab %}

{% tab title="postman" %}

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2F1LGQqiIyQRszKuN0Oh5P%2FCauhinhPostman.png?alt=media&amp;token=bd95012c-ec40-4a69-8d11-34cd86250d61" alt=""><figcaption><p>Cấu hình api token trên postman</p></figcaption></figure>
{% endtab %}
{% endtabs %}

## Một số trường hợp điển hình của trạng thái chuyên viên&#x20;

#### 1, Trạng thái online 3 kênh thoại/chat/ticket của 1 agent khi dùng api lấy danh sách chuyên viên

```json
            {
            "id": 63203703,
            "username": "Đặng Phương Thu Thảo",
            "email": "thut***@gmail.com",
            "phone_no": "08***8",
            "agent_id": "5045",
            "created_at": "2021-08-25 15:17:20",
            "updated_at": "2025-10-15 11:31:52",
            "group_id": 15257,
            "group_name": "Không xóa bộ phận cũ đi nhé",
            "role_id": 1,
            "call_status": "AVAILABLE",
            "ticket_status": "AVAILABLE",
            "chat_status": "AVAILABLE"
            }
```

#### 2, Trạng thái offline thoại/chat/ticket của 1 agent khi dùng api lấy danh sách chuyên viên

```json
         {
        "id": 63203703,
        "username": "Đặng Phương Thu Thảo",
        "email": "thut***@gmail.com",
        "phone_no": "08***8",
        "agent_id": "5045",
        "created_at": "2021-08-25 15:17:20",
        "updated_at": "2025-10-15 11:31:52",
        "group_id": 15257,
        "group_name": "Không xóa bộ phận cũ đi nhé",
        "role_id": 1,
        "call_status": "NOT AVAILABLE",
        "ticket_status": "NOT AVAILABLE",
        "chat_status": "NOT AVAILABLE"
        }
```

#### 3, Trạng thái online ticket của 1 agent và offline thoại/chat của agent đó khi dùng api lấy danh sách chuyên viên

```json
    {
        "id": 63203703,
        "username": "Đặng Phương Thu Thảo",
        "email": "thut***@gmail.com",
        "phone_no": "08***8",
        "agent_id": "5045",
        "created_at": "2021-08-25 15:17:20",
        "updated_at": "2025-10-15 11:31:52",
        "group_id": 15257,
        "group_name": "Không xóa bộ phận cũ đi nhé",
        "role_id": 1,
        "call_status": "NOT AVAILABLE",
        "ticket_status": "AVAILABLE",
        "chat_status": "NOT AVAILABLE"
        }
```

#### 4, Đăng xuất&#x20;

* Thông tin agent khi dùng api lấy danh sách chuyên và agent đó đăng xuất là chọn logout tất cả các thiết bị&#x20;

```json
 {
        "id": 63203703,
        "username": "Đặng Phương Thu Thảo",
        "email": "thut***@gmail.com",
        "phone_no": "08***8",
        "agent_id": "5045",
        "created_at": "2021-08-25 15:17:20",
        "updated_at": "2025-10-15 11:31:52",
        "group_id": 15257,
        "group_name": "Không xóa bộ phận cũ đi nhé",
        "role_id": 1,
        "call_status": "LOGOUT",
        "ticket_status": "LOGOUT",
        "chat_status": "LOGOUT"
        }
```

* &#x20;Trường hợp thể hiện 3 trạng thái đăng nhập đăng xuất logout của các tham số
  * Chọn nghe gọi qua app và đăng xuất web&#x20;
  * Online trạng thái thoại/ticket và offline chat

```json
{
        "id": 63203703,
        "username": "Đặng Phương Thu Thảo",
        "email": "thut***@gmail.com",
        "phone_no": "08***8",
        "agent_id": "5045",
        "created_at": "2021-08-25 15:17:20",
        "updated_at": "2025-10-15 11:31:52",
        "group_id": 15257,
        "group_name": "Không xóa bộ phận cũ đi nhé",
        "role_id": 1,
        "call_status": "AVAILABLE",
        "ticket_status": "LOGOUT",
        "chat_status": "NOT AVAILABLE"
        }
```


# Bộ phận

Bộ phận/Phòng ban trên hệ thống CareSoft

Bộ phận trên CareSoft là đối tượng gom nhóm các chuyên viên về 1 nhóm. Tương đương mô hình 1 phòng ban trong mỗi doanh nghiệp. Có trưởng nhóm (Supper)  và các chuyên viên (Agent)&#x20;

Các API khác khi sử dụng bộ phận sẽ dùng `{{group_id}}`  là ID của bộ phận để thực hiện giao thức

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FX4FyfMnW78DqVen6qpyA%2Fimage.png?alt=media&amp;token=e8b5c66a-4793-49d1-94fe-33a257a41841" alt=""><figcaption><p>Giao diện cấu hình bộ phận trên CareSoft </p></figcaption></figure>

{% hint style="info" %}
**Lưu ý:** Bộ phận có thể cấu hình thay đổi tên gọi hoặc thêm mới từ giao diện. Cần đặt tiến trình đồng bộ mỗi ngày để đảm bảo thông tin chính xác&#x20;
{% endhint %}

## Lấy danh sách bộ phận

### Danh sách bộ phận được cấu hình trên hệ thống

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/groups`

#### Headers

| Name | Type   | Description                                                        |
| ---- | ------ | ------------------------------------------------------------------ |
| \*\* | String | [Thông tin xác thực chung ](/thong-tin-chung#phuong-thuc-xac-thuc) |

{% tabs %}
{% tab title="200: OK " %}
{% tabs %}
{% tab title="Mẫu trả về" %}

```json
{
    "code": "ok",
    "groups": [
        {
            "group_id": 12153,
            "group_name": "Default Group",
            "created_at": "2020-10-01 02:48:15"
        },
        {
            "group_id": 12945,
            "group_name": "Kinh doanh",
            "created_at": "2021-10-27 14:55:31"
        },        
        {
            "group_id": 14181,
            "group_name": "Chăm sóc khách hàng",
            "created_at": "2023-03-21 09:33:23"
        }
    ]
}
```

{% endtab %}

{% tab title="Cấu trúc thông tin" %}

*Chi tiết mảng thông tin groups*
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="404: Not Found " %}

{% endtab %}

{% tab title="500: Internal Server Error " %}

{% endtab %}
{% endtabs %}

<table><thead><tr><th width="133" data-type="number">STT</th><th width="181">Tên trường</th><th>Ghi chú</th></tr></thead><tbody><tr><td>1</td><td>group_id</td><td>ID bộ phận</td></tr><tr><td>2</td><td>group_name</td><td>Tên bộ phận</td></tr><tr><td>3</td><td>created_at</td><td>Ngày tạo</td></tr></tbody></table>

<table><thead><tr><th width="132" data-type="number">STT</th><th width="158">Tên trường</th><th>Kiểu</th><th>Ghi chú</th></tr></thead><tbody><tr><td>1</td><td>groups</td><td>Array</td><td>Mảng dữ liệu bộ phận</td></tr><tr><td>2</td><td>code</td><td>String</td><td>Trạng thái (OK, NOK)</td></tr></tbody></table>


# Dịch vụ

Danh sách các dịch vụ trên CareSoft

Danh sách các Dịch vụ tích hợp trên CareSoft. Các serviceId trong API  dưới đây có thể dùng làm mapping nguồn phiếu ghi hoặc tạo mới phiếu ghi qua API để phân phối cho nhóm chuyên viên được gán.&#x20;

## **Các loại dịch vụ trên API**&#x20;

<table><thead><tr><th width="253">TypeId</th><th>Loại</th></tr></thead><tbody><tr><td>1</td><td>Gọi vào</td></tr><tr><td>2</td><td>Live chat</td></tr><tr><td>3</td><td>Email</td></tr><tr><td>4</td><td>Facebook</td></tr><tr><td>6</td><td>Miss chat</td></tr><tr><td>7</td><td>Voicemail</td></tr><tr><td>8</td><td>Inbox Facebook</td></tr><tr><td>9</td><td>Api</td></tr><tr><td>10</td><td>Zalo</td></tr><tr><td>11</td><td>Voice out</td></tr><tr><td>12</td><td>Ivr</td></tr><tr><td>13</td><td>Ticket form</td></tr></tbody></table>

## Danh sách các dịch vụ trên Caresoft

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/services`

#### Query Parameters

| Name        | Type | Description                                              |
| ----------- | ---- | -------------------------------------------------------- |
| type        | Int  | Lọc theo loại dịch vụ dựa trên Type ID ở bảng mô tả trên |
| service\_id | Int  | Id dịch vụ                                               |

#### Headers

| Name                                   | Type   | Description                                                        |
| -------------------------------------- | ------ | ------------------------------------------------------------------ |
| \*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung ](/thong-tin-chung#phuong-thuc-xac-thuc) |

{% tabs %}
{% tab title="200: OK Thành công" %}
{% tabs %}
{% tab title="Kết quả điển hình" %}

```json

{
    "code": "ok",
    "services": [
     {
            "service_id": 1005815,
            "service_name": "99-991-Gọi vào",
            "service_type": "Gọi vào",
            "type": 1,
            "detail": {
                "line": "991_1111",
                "number": "",
                "description": "99-991-Gọi vào (1111)",
                "created_at": "2021-12-03 13:09:50",
                "updated_at": "2021-12-03 13:11:31"
            }
        },
        {
            "service_id": 1005817,
            "service_name": "99-992-Gọi vào",
            "service_type": "Gọi vào",
            "type": 1,
            "detail": {
                "line": "992_1111",
                "number": "",
                "description": "99-992-Gọi vào (1111)",
                "created_at": "2021-12-03 13:09:50",
                "updated_at": "2021-12-03 13:11:31"
            }
        },

...
```

{% endtab %}

{% tab title="Mô tả kết quả " %}

<table><thead><tr><th width="102">STT</th><th width="163">Trường dữ liệu</th><th>Chú thích</th></tr></thead><tbody><tr><td>1</td><td>service_name</td><td>Tên dịch vụ</td></tr><tr><td>2</td><td>service_id</td><td>Id dịch vụ</td></tr><tr><td>3</td><td>service_type</td><td>Loại dịch vụ</td></tr><tr><td>4</td><td>type</td><td>ID loại dịch vụ</td></tr><tr><td>5</td><td>detail</td><td>Object chi tiết theo từng dịch vụ (Xem bảng dưới) </td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}
{% endtabs %}

## Mẫu các dữ liệu chi tiết của từng dịch vụ

### Gọi vào và IVR ( Interactive Voice Response)&#x20;

ID loại dịch vụ: 1 và 12&#x20;

{% tabs %}
{% tab title="Dữ liệu mẫu" %}

```json
 {
        "service_id": 1005815,
        "service_name": "99-991-Gọi vào",
        "service_type": "Gọi vào",
        "type": 1,
        "detail": {
              "line": "991_1111",
              "number": "19001800",
              "description": "99-991-Gọi vào (1111)",
              "created_at": "2021-12-03 13:09:50",
              "updated_at": "2021-12-03 13:11:31",
              "status": 1
         }
}

```

{% endtab %}

{% tab title="Mô tả cấu trúc" %}
Object Detail

<table><thead><tr><th width="247">Trường dữ liệu</th><th>Ghi chú</th></tr></thead><tbody><tr><td>line</td><td>Nhánh hotline</td></tr><tr><td>number</td><td>Đầu số gốc</td></tr><tr><td>description</td><td>Mô tả</td></tr><tr><td>created_at</td><td>Ngày tạo</td></tr><tr><td>updated_at</td><td>Ngày cập nhật</td></tr><tr><td>status</td><td>Trạng thái dịch vụ: 0: Ngưng sử dụng, 1: Đang sử dụng</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

### Live Chat

ID loại dịch vụ: 2

{% tabs %}
{% tab title="Dữ liệu mẫu" %}

```json
 {
            "service_id": 6006242,
            "service_name": "test",
            "service_type": "Live chat",
            "type": 2,
            "detail": {
                "domain": "vi2_ticketsharing",
                "status": 1,
                "description": "Box chat trên site bán hàng"
            }
  }
```

{% endtab %}

{% tab title="Mô tả cấu trúc" %}
Object Detail

<table><thead><tr><th width="219">Trường dữ liệu</th><th>Ghi chú</th></tr></thead><tbody><tr><td>domain</td><td>Domain chat của dịch vụ</td></tr><tr><td>status</td><td>Trạng thái sử dụng: <br>0: Tạm ngừng<br>1: Đang sử dụng</td></tr><tr><td>description</td><td>Tên dịch vụ chat</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

### Email

ID loại dịch vụ: 3

{% tabs %}
{% tab title="Dữ liệu mẫu" %}

```json
 {
            "service_id": 9004932,
            "service_name": "Test cập nhật Email",
            "service_type": "Email",
            "type": 3,
            "detail": {
                "in_email_address": "hungnx03009@gmail.com",
                "out_email_address": "hungnx03009@gmail.com",
                "status": 0,
                "description": "Test cập nhật Email",
                "last_update": "2022-08-03 10:28:44"
            }

```

{% endtab %}

{% tab title="Mô tả cấu trúc" %}

<table><thead><tr><th width="245">Trường</th><th>Ghi chú</th></tr></thead><tbody><tr><td>in_email_address</td><td>Email nhận</td></tr><tr><td>out_email_address</td><td>Email gửi ra</td></tr><tr><td>status</td><td>Trạng thái: 0: Đang tạm ngưng, 1: Kích hoạt</td></tr><tr><td>description</td><td>Ghi chú</td></tr><tr><td>last_update</td><td>Lần cập nhật cuối</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

### Facebook/Instagram

ID loại dịch vụ: 4

{% tabs %}
{% tab title="Dữ liệu mẫu" %}

```json

  {
            "service_id": 9105775,
            "service_name": "Camera Man",
            "service_type": "Facebook",
            "type": 4,
            "detail": {
                "page_id": "546869858829726",
                "active": "1",
                "description": "Camera Man",
                "created_at": "2021-11-02 10:55:38",
                "platform": "MESSENGER"
            }
        }

```

{% endtab %}

{% tab title="Mô tả cấu trúc" %}

| Tên trường    | Ghi chú                                                                                                   |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| page\_id      | ID trang                                                                                                  |
| active        | <p>Trạng thái: <br>0: ngưng kích hoạt<br>1: Đang kích hoạt</p>                                            |
| description   | Ghi chú                                                                                                   |
| created\_at   | Ngày tạo                                                                                                  |
| platform      | <p><strong>Nền tảng</strong><br>MESSENGER: Trang facebook hoặc Inbox Facebook<br>INSTAGRAM: Instagram</p> |
| {% endtab %}  |                                                                                                           |
| {% endtabs %} |                                                                                                           |

### Miss chat Zalo, Facebook, Live chat&#x20;

ID loại dịch vụ: 6

{% tabs %}
{% tab title="Dữ liệu mẫu" %}

```json

  {
    "service_id": 9405942,
    "service_name": "How to swiming",
    "service_type": "Miss chat",
    "type": 6,
    "detail": {
         "page_id": "714542025321103",
         "active": "1",
         "description": "How to swiming",
         "created_at": "2021-11-24 22:35:07",
         "platform": "MESSENGER",
          "chat_type": "FACEBOOK"
    }
  },
  {
    "service_id": 9406241,
    "service_name": "Caresoft contact center",
    "service_type": "Miss chat",
    "type": 6,
    "detail": {
      "oa_id": "285586298586590917",
      "active": 0,
      "description": "Giải pháp phần mềm quản lý tương tác, bán hàng và dịch vụ khách hàng đa kênh. Nâng cao chất lượng dịch vụ và tỉ lệ chuyển đổi Hotline, Facebook, Zalo, Web, Apps, Email Sms",
      "name": "Caresoft contact center",
      "chat_type": "ZALO"
    }
  },
  {
    "service_id": 9406243,
    "service_name": "test",
    "service_type": "Miss chat",
    "type": 6,
    "detail": {
      "domain": "vi2_ticketsharing",
      "status": 1,
      "description": "test",
      "chat_type": "CHAT"
    }
  }

```

{% endtab %}

{% tab title="Mô tả cấu trúc" %}
Loại dịch vụ Miss chat gồm 3 loại Miss chat khác nhau. Có 1 key phân biệt trong object Detail là "chat\_type"

**chat\_type** gồm các giá trị

* CHAT: Live chat
* FACEBOOK:   Messenger và Instagram
* ZALO: Zalo

**Đối với Live Chat (chat\_type: CHAT)**

| Trường      | Ghi chú                             |
| ----------- | ----------------------------------- |
| domain      | domain chat cấu hình trên giao diện |
| status      | Trạng thái                          |
| chat\_type  | Kiểu Miss, Giá trị: CHAT            |
| description | Ghi chú                             |

**Đối với Messenger và Instagram  (chat\_type: FACEBOOK)**

| Trường      | Ghi chú                                                   |
| ----------- | --------------------------------------------------------- |
| page\_id    | Page ID                                                   |
| active      | Trạng thái kích hoạt: 0: Mất kích hoạt, 1: Đang hoạt động |
| description | Ghi chú                                                   |
| created\_at | Ngày tạo                                                  |
| platform    | <p>Nền tảng<br>MESSENGER hoặc INSTAGRAM</p>               |
| chat\_type  | FACEBOOK                                                  |

**Đối với ZALO  (chat\_type:ZALO)**

| Trường        | Ghi chú                                                   |
| ------------- | --------------------------------------------------------- |
| oa\_id        | OA ID                                                     |
| active        | Trạng thái kích hoạt: 0: Mất kích hoạt, 1: Đang hoạt động |
| description   | Giới thiệu của trang OA ZALO                              |
| name          | Tên OA                                                    |
| chat\_type    | ZALO                                                      |
| {% endtab %}  |                                                           |
| {% endtabs %} |                                                           |

### Inbox facebook/Instagram

ID loại dịch vụ: 8

{% tabs %}
{% tab title="Dữ liệu mẫu" %}

```json

  {
    "service_id": 6106245,
    "service_name": "CSG Developer (Instagram)",
    "service_type": "Inbox Facebook",
    "type": 8,
    "detail": {
      "page_id": "17841456598879972",
      "active": "1",
      "description": "CSG Developer",
      "created_at": "2022-11-11 17:22:28",
      "platform": "INSTAGRAM"
    }
  },
  {
    "service_id": 6106249,
    "service_name": "Hoa Sơn Gaming",
    "service_type": "Inbox Facebook",
    "type": 8,
    "detail": {
      "page_id": "113006833398415",
      "active": "1",
      "description": "Hoa Sơn Gaming",
      "created_at": "2022-12-07 10:27:23",
      "platform": "MESSENGER"
    }
  }

```

{% endtab %}

{% tab title="Mô tả cấu trúc" %}

| Trường        | Ghi chú                                                   |
| ------------- | --------------------------------------------------------- |
| page\_id      | Page ID                                                   |
| active        | Trạng thái kích hoạt: 0: Mất kích hoạt, 1: Đang hoạt động |
| description   | Tên trang                                                 |
| created\_at   | Ngày tạo                                                  |
| platform      | <p>Nền tảng<br>MESSENGER hoặc INSTAGRAM</p>               |
| {% endtab %}  |                                                           |
| {% endtabs %} |                                                           |

### Zalo

ID loại dịch vụ: 10

{% tabs %}
{% tab title="Dữ liệu mẫu" %}

```json
{
  "service_id": 6205009,
  "service_name": "Dota2",
  "service_type": "Zalo",
  "type": 10,
  "detail": {
    "oa_id": "1881674073797784908",
    "active": 1,
    "description": "Dota2 VN community Share Funny moment",
    "name": "Dota2"
  }
}
```

{% endtab %}

{% tab title="Mô tả cấu truc" %}

| Trường dữ liệu | Ghi chú                                                   |
| -------------- | --------------------------------------------------------- |
| oa\_id         | OA ID                                                     |
| active         | Trạng thái kích hoạt: 0: Mất kích hoạt, 1: Đang hoạt động |
| description    | Giới thiệu của trang OA ZALO                              |
| name           | Tên OA                                                    |
| {% endtab %}   |                                                           |
| {% endtabs %}  |                                                           |

{% hint style="info" %}
Lưu ý. Api gửi SMS  không sử dụng serviceId trong danh sách này để gửi.
{% endhint %}


# Phiếu ghi

Cập nhật, Thêm mới, Danh sách phiếu ghi, chi tiết và các thuộc tính của phiếu ghi.

## Các trường thông tin của phiếu ghi

Phiếu ghi trên hệ thống CareSoft là 1 đối tượng dữ liệu được tạo ra bởi tất cả các kênh tương tác mà hệ thống đa kênh có thể thu nhận được. Mọi tương tác của khách hàng tới hệ thống đều tạo ra phiếu ghi và lưu trữ thông tin của nó.

**Các trường thông tin của phiếu ghi**&#x20;

<table><thead><tr><th width="74" data-type="number">STT</th><th width="205">Tên trường</th><th width="132">Kiểu dữ liệu<select><option value="c1de87f3835849988fba39927355ae11" label="Int" color="blue"></option><option value="58097ed0ba9e42819493eab2984fc5c1" label="Array" color="blue"></option><option value="eb8e153ff4d844788e62f0e80c99ce6a" label="String (255)" color="blue"></option><option value="bd16f1c24b0f4fe1b2a6918a3cef564d" label="String" color="blue"></option><option value="92bb4e6fd2e5421486918f8a8ffdc9fb" label="DateTime" color="blue"></option><option value="e0e0772e6f6a492b8bb350fcfaed9731" label="Object" color="blue"></option></select></th><th>Chú thích</th><th data-hidden>Trạng thái<select></select></th></tr></thead><tbody><tr><td>1</td><td>ticket_no</td><td><span data-option="c1de87f3835849988fba39927355ae11">Int</span></td><td>Số phiếu ghi</td><td></td></tr><tr><td>2</td><td>ticket_status</td><td><span data-option="bd16f1c24b0f4fe1b2a6918a3cef564d">String</span></td><td>Trạng thái phiếu ghi có <a data-footnote-ref href="#user-content-fn-1">5 trạng thái</a> </td><td></td></tr><tr><td>3</td><td>ticket_subject</td><td><span data-option="eb8e153ff4d844788e62f0e80c99ce6a">String (255)</span></td><td>Chủ đề phiếu ghi</td><td></td></tr><tr><td>4</td><td>ticket_priority</td><td><span data-option="bd16f1c24b0f4fe1b2a6918a3cef564d">String</span></td><td>Độ ưu tiên có <a data-footnote-ref href="#user-content-fn-2">3 trạng thái </a></td><td></td></tr><tr><td>5</td><td>ticket_id</td><td><span data-option="c1de87f3835849988fba39927355ae11">Int</span></td><td>Id phiếu ghi, Khóa chính để thực hiện tương tác với phiếu ghi qua API</td><td></td></tr><tr><td>6</td><td>requester_id</td><td><span data-option="c1de87f3835849988fba39927355ae11">Int</span></td><td>Id người yêu cầu, khóa chính để thực hiện tương tác với khách hàng qua API</td><td></td></tr><tr><td>7</td><td>assignee_id</td><td><span data-option="c1de87f3835849988fba39927355ae11">Int</span></td><td>Id người xử lý. Là Id của chuyên viên trong 1 hệ thống</td><td></td></tr><tr><td>8</td><td>created_at</td><td><span data-option="92bb4e6fd2e5421486918f8a8ffdc9fb">DateTime</span></td><td>Ngày tạo phiếu ghi</td><td></td></tr><tr><td>9</td><td>updated_at</td><td><span data-option="92bb4e6fd2e5421486918f8a8ffdc9fb">DateTime</span></td><td>Ngày cập nhật phiếu ghi</td><td></td></tr><tr><td>10</td><td>group_id</td><td><span data-option="c1de87f3835849988fba39927355ae11">Int</span></td><td>Bộ phận của người xử lý (có thể lấy danh sách bộ phận <a href="/danh-muc/restful-api-cua-caresoft/bo-phan">tại đây</a></td><td></td></tr><tr><td>11</td><td>ticket_source</td><td><span data-option="bd16f1c24b0f4fe1b2a6918a3cef564d">String</span></td><td>Nguồn phiếu ghi, <a href="/danh-muc/restful-api-cua-caresoft/phieu-ghi/danh-sach-nguon">xem danh sách </a></td><td></td></tr><tr><td>12</td><td>duedate</td><td><span data-option="92bb4e6fd2e5421486918f8a8ffdc9fb">DateTime</span></td><td>Hạn xử lý</td><td></td></tr><tr><td>13</td><td>satisfaction</td><td><span data-option="c1de87f3835849988fba39927355ae11">Int</span></td><td>Điểm hài lòng</td><td></td></tr><tr><td>14</td><td>satisfaction_at</td><td><span data-option="92bb4e6fd2e5421486918f8a8ffdc9fb">DateTime</span></td><td>Ngày đánh giá sự hài lòng</td><td></td></tr><tr><td>15</td><td>satisfaction_send</td><td><span data-option="92bb4e6fd2e5421486918f8a8ffdc9fb">DateTime</span></td><td>Ngày gửi đánh giá hài lòng</td><td></td></tr><tr><td>16</td><td>satisfaction_content</td><td><span data-option="bd16f1c24b0f4fe1b2a6918a3cef564d">String</span></td><td>Nội dung đánh giá hài lòng</td><td></td></tr><tr><td>17</td><td>campaign_id</td><td><span data-option="c1de87f3835849988fba39927355ae11">Int</span></td><td>ID chiến dịch, xem danh sách chiến dịch</td><td></td></tr><tr><td>18</td><td>automessage_id</td><td><span data-option="c1de87f3835849988fba39927355ae11">Int</span></td><td>ID Chiến dịch tự động </td><td></td></tr><tr><td>19</td><td>is_overdue</td><td><span data-option="c1de87f3835849988fba39927355ae11">Int</span></td><td>Trạng thái quá hạn xử lý </td><td></td></tr><tr><td>20</td><td>incident_id</td><td><span data-option="c1de87f3835849988fba39927355ae11">Int</span></td><td>ID<a data-footnote-ref href="#user-content-fn-3"> phiếu ghi cha </a></td><td></td></tr><tr><td>21</td><td>service_id</td><td><span data-option="c1de87f3835849988fba39927355ae11">Int</span></td><td>ID dịch vụ, xem danh sách dịch vụ</td><td></td></tr><tr><td>22</td><td>ticket_source_detail_id</td><td><span data-option="c1de87f3835849988fba39927355ae11">Int</span></td><td>ID nguồn chi tiết của phiếu ghi </td><td></td></tr><tr><td>23</td><td>comments</td><td><span data-option="58097ed0ba9e42819493eab2984fc5c1">Array</span></td><td>[1] Danh sách bình luận trên phiếu ghi</td><td></td></tr><tr><td>24</td><td>custom_filed</td><td><span data-option="58097ed0ba9e42819493eab2984fc5c1">Array</span></td><td>[2] Danh sách trường động và giá trị được lưu trữ cho phiếu ghi</td><td></td></tr><tr><td>25</td><td>assignee</td><td><span data-option="e0e0772e6f6a492b8bb350fcfaed9731">Object</span></td><td>[3] Đối tượng người xử lý</td><td></td></tr><tr><td>26</td><td>requester</td><td><span data-option="e0e0772e6f6a492b8bb350fcfaed9731">Object</span></td><td>[4] Đối tượng người yêu cầu</td><td></td></tr><tr><td>27</td><td>tags</td><td><span data-option="58097ed0ba9e42819493eab2984fc5c1">Array</span></td><td>Danh sách các thẻ được gắn</td><td></td></tr><tr><td>28</td><td>ccs</td><td><span data-option="58097ed0ba9e42819493eab2984fc5c1">Array</span></td><td>[5] Danh sách các người dùng được cc</td><td></td></tr><tr><td>29</td><td>follows</td><td><span data-option="58097ed0ba9e42819493eab2984fc5c1">Array</span></td><td>[6] Danh sách người dùng theo dõi</td><td></td></tr><tr><td>30</td><td>ticket_type</td><td><span data-option="bd16f1c24b0f4fe1b2a6918a3cef564d">String</span></td><td><h4>Trạng thái phản hồi</h4><p>Khi nhân viên chăm sóc khách hàng nhận được một yêu cầu từ khách hàng, họ sẽ thực hiện phản hồi qua một hoặc nhiều kênh khác nhau, <strong>không phụ thuộc vào kênh mà yêu cầu ban đầu được gửi đến</strong>.</p><p>Hệ thống CareSoft hỗ trợ ghi nhận trạng thái phản hồi dựa trên kênh đã sử dụng để phản hồi cho khách hàng. Các giá trị trạng thái bao gồm:</p><ul><li><code>'COMMENT'</code>: Đã để lại bình luận/phản hồi.</li><li><code>'CALLED'</code>: Đã thực hiện cuộc gọi đến khách hàng.</li><li><code>'ANSWERED_CALL'</code>: Đã tiếp nhận và trả lời cuộc gọi từ khách hàng.</li><li><code>'EMAIL'</code>: Đã gửi email.</li><li><code>'SMS'</code>: Đã gửi tin nhắn SMS.</li><li><code>'CHAT'</code>: Đã gửi tin nhắn qua kênh chat.</li><li><code>'ZNS'</code>: Đã gửi tin nhắn qua Zalo Notification Service (ZNS).</li><li><code>'NULL'</code>: Chưa thực hiện phản hồi nào.</li></ul></td><td></td></tr></tbody></table>

## Thêm mới, cập nhật phiếu ghi

#### Thêm mới phiếu ghi

## Thêm mới phiếu ghi

<mark style="color:green;">`POST`</mark> `{{domain}}/api/v1/tickets`

Sử dụng hàm này để thêm mới 1 phiếu ghi đồng thời thực hiện giao phiếu cho một chuyên viên chỉ định hoặc một phòng ban bất kỳ.&#x20;

#### Headers

| Name                                 | Type | Description                                                        |
| ------------------------------------ | ---- | ------------------------------------------------------------------ |
| \*<mark style="color:red;">\*</mark> |      | [Thông tin xác thực chung ](/thong-tin-chung#phuong-thuc-xac-thuc) |

#### Request Body

| Name                                                  | Type        | Description                                                                                                                                                                                                |
| ----------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ticket                                                | object      | Đối tượng phiếu ghi                                                                                                                                                                                        |
| ticket.username                                       | String      | Tên người yêu cầu                                                                                                                                                                                          |
| ticket.phone<mark style="color:red;">\*</mark>        | Phone       | [(\*) Số điện thoại của người yêu cầu](#user-content-fn-4)[^4]                                                                                                                                             |
| ticket.city\_id                                       | String(4)   | ID của thành phố của người yêu cầu (Xem ở api [Thông tin tỉnh/huyện](/danh-muc/restful-api-cua-caresoft/khach-hang/thong-tin-tinh-huyen-xa)).                                                              |
| ticket.district\_id                                   | String(4)   | ID của quận/huyện người yêu cầu (Xem ở api [Thông tin tỉnh/huyện](/danh-muc/restful-api-cua-caresoft/khach-hang/thong-tin-tinh-huyen-xa))                                                                  |
| ticket.address                                        | String(255) | Địa chỉ của người yêu cầu                                                                                                                                                                                  |
| ticket.email                                          | Email       | (\*) Email người yêu cầu                                                                                                                                                                                   |
| ticket.ticket\_subject                                | String(255) | Tiêu đề phiếu ghi                                                                                                                                                                                          |
| ticket.ticket\_comment                                | String      | Ghi chú của phiếu ghi                                                                                                                                                                                      |
| ticket.assignee\_id<mark style="color:red;">\*</mark> | Int         | [(\*\*) ID của người nhận phiếu ghi](#user-content-fn-5)[^5]                                                                                                                                               |
| ticket.group\_id                                      | Int         | (\*\*) ID của phòng ban được chia phiếu ghi                                                                                                                                                                |
| ticket.service\_id                                    | Int         | [(\*\*) ID của dịch vụ](#user-content-fn-6)[^6]                                                                                                                                                            |
| ticket.custom\_fields                                 | Array\[]    | (?)[^7] Mảng truyền dữ liệu trường động  phiếu ghi                                                                                                                                                         |
| ticket.requester\_id                                  | Int         | Id của người yêu cầu                                                                                                                                                                                       |
| ticket.ref\_url                                       | URL         | [Địa chỉ trang web đánh dấu nguồn phát sinh ticket](#user-content-fn-8)[^8]                                                                                                                                |
| ticket.is\_public                                     | Int         | Trạng thái ghi chú hoặc phản hồi                                                                                                                                                                           |
| ticket.duedate                                        | DateTime    | Thời hạn xử lý                                                                                                                                                                                             |
| tickets.follow\_user                                  | String      | Danh sách ID của chuyên viên theo dõi phiếu ghi, cách nhau bởi dấu phẩy                                                                                                                                    |
| tickets.ticket\_status                                | String      | Trạng thái phiếu ghi. Một trong 4 trạng thái ("new", "open","solved", "pending")                                                                                                                           |
| tickets.ticket\_priority                              | String      | Độ ưu tiên  là một trong 4 giá trị "High","Low","Normal","Urgent"                                                                                                                                          |
| tickets.cc\_user                                      | String      | Danh sách ID của khách hàng CC phiếu ghi, cách nhau bởi dấu phẩy                                                                                                                                           |
| tickets.campaign\_id                                  | Int         | ID chiến dịch                                                                                                                                                                                              |
| tickets.member\_status\_id                            | Int         | Trạng thái chiến dịch của đối tượng (Xem danh sách tại [đây ](/danh-muc/restful-api-cua-caresoft/chien-dich)), trong trường hợp không truyền sẽ lấy giá trị mặc định. Áp dụng cho chiến dịch có v\_type=1. |
| tickets.ref\_url                                      | String      | Địa chỉ nguồn phát sinh dữ liệu ví dụ trang web đặt form                                                                                                                                                   |

{% tabs %}
{% tab title="200: OK Thành công" %}
{% tabs %}
{% tab title="Phản hồi thành công" %}
{% code title="Phiếu ghi tạo thành công " %}

```json
{
    "code": "ok",
    "ticket": {
        "updated_at": "2023-03-28 13:55:23",
        "ticket_subject": "Test create ticket from API",
        "ticket_no": 7016,
        "created_at": "2023-03-28 13:55:23",
        "ticket_id": 381185209,
        "requester_id": 126564055
    }
}

```

{% endcode %}

**Chi tiết các trường dữ liệu**&#x20;

<table><thead><tr><th width="70" data-type="number">STT</th><th width="187">Tên trường</th><th width="110">Kiểu</th><th>Ghi chú</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>string</td><td>"ok": thành công, "nok": thất bại</td></tr><tr><td>2</td><td><em><mark style="color:green;"><code>ticket</code></mark></em></td><td>Object</td><td>Đối tượng phiếu ghi tạo thành công </td></tr><tr><td>3</td><td>ticket.updated_at</td><td>DateTime</td><td>Ngày cập nhật</td></tr><tr><td>4</td><td>ticket.created_at</td><td>DateTime</td><td>Ngày tạo</td></tr><tr><td>5</td><td>ticket.ticket_no</td><td>Int</td><td>Số phiếu ghi </td></tr><tr><td>6</td><td>ticket.ticket_id </td><td>Int</td><td><a data-footnote-ref href="#user-content-fn-9">(*) ID phiếu ghi </a></td></tr><tr><td>7</td><td>requester_id</td><td>Int</td><td><a data-footnote-ref href="#user-content-fn-10">(**) ID khách hàng </a></td></tr></tbody></table>
{% endtab %}

{% tab title="Mẫu json gửi đi" %}
{% code title="JSON body tạo ticket" overflow="wrap" %}

```json
{
    "ticket": {
        "phone": "0900000001",
        "username":"Khách hàng Demo",
        "service_id": 12,
        "ticket_subject": "Test create ticket from API",
        "ticket_comment": "Coment create ticket from Api  ",
        "ref_url":"https://caresoft.vn?utm=xtest",
        "duedate":"2023-06-01 20:00:00",
        "is_public":0        
    }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% endtab %}

{% tab title="400: Bad Request Lỗi sai định dạng (kiểm tra cấu trúc JSON gửi đi sai cú pháp)" %}
{% tabs %}
{% tab title="Sai cú pháp" %}
{% code title="Thông báo lỗi sai cú pháp" %}

```json
{
    "code": "errors",
    "message": "Invalid Format"
}
```

{% endcode %}

{% endtab %}

{% tab title="Sai thông tin" %}
{% code title="Thông báo lỗi sai ID của người xử lý" %}

```json
{
"code": "errors",
"message": "invalid value: assignee_id"
}
```

{% endcode %}

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="500: Internal Server Error " %}

{% endtab %}

{% tab title="401: Unauthorized " %}
{% code title="Sai api token" %}

```json
{
    "code": "errors",
    "message": "Authorization header is incorrect"
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
Nếu bạn đã có ID của người dùng bạn có thể truyền requester\_id mà không cần gửi email, số điện thoại.&#x20;

Hệ thống CareSoft sử dụng số điện thoại và email làm khóa duy nhất do đó sẽ luôn tạo phiếu ghi cho 1 người nếu bạn chỉ thay đổi tên người dùng&#x20;
{% endhint %}

Mẫu code&#x20;

{% tabs %}
{% tab title="curl" %}

```powershell
curl 
--location 'https://api.caresoft.vn/{{domain}}/api/v1/tickets' \
--header 'Authorization: Bearer {{apiToken}}' \
--header 'Content-Type: application/json' \
--data '{
    "ticket": {
        "phone": "0900000001",
        "username": "Khách hàng Demo",
        "service_id": 12,
        "ticket_subject": "Test create ticket from API",
        "ticket_comment": "Coment create ticket from Api  ",
        "ref_url": "https://caresoft.vn?utm=xtest",
        "is_public": 1
    }
}'
```

{% endtab %}

{% tab title="postman" %}

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FNvmbTOTUxY696Ipx0gZT%2FPostmanPostTicket.png?alt=media&amp;token=15631067-4b15-43f5-bde2-cba3644704a4" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Mẫu body json" %}

```json
{
    "ticket": {
        "phone": "0900000001",
        "username": "Khách hàng Demo",
        "service_id": 12,
        "ticket_subject": "Test create ticket from API",
        "ticket_comment": "Coment create ticket from Api  ",
        "ref_url": "https://caresoft.vn?utm=xtest",
        "duedate":"2023-06-01 20:00:00",
        "is_public": 1
    }
}
```

{% endtab %}

{% tab title="Phản hồi thành công" %}

```json
{
    "code": "ok",
    "ticket": {
        "updated_at": "2023-03-28 13:55:23",
        "ticket_subject": "Test create ticket from API",
        "ticket_no": 7016,
        "created_at": "2023-03-28 13:55:23",
        "ticket_id": 381185209,
        "requester_id": 126564055
    }
}
```

{% endtab %}
{% endtabs %}

#### Cập nhật phiếu ghi

{% tabs %}
{% tab title="Mẫu body json" %}

```
{
    "ticket": {
        "ticket_subject": "Test",
        "ticket_comment": {
            "body": "Cập nhật giá trị mua hành thành giao hàng",
            "is_public": 1,
            "author_id": 124734559
        },
        "ticket_priority": "Hight",
        "ticket_source": "Voice",
        "custom_fields": [
            {
                "id": "6068",
                "value": "106902"
            }
        ]
    }
}

```

Biểu mẫu trên sẽ cập nhật phiếu ghi và 1 giá trị trường động&#x20;
{% endtab %}
{% endtabs %}

## Cập nhật phiếu ghi

<mark style="color:orange;">`PUT`</mark> `{{domain}}/api/v1/tickets/{{ticketId}}`

Cập nhật thông tin vào một phiếu ghi hiện hữu  cần ID của phiếu ghi theo biến `{ticketId}`.&#x20;

#### Headers

<table><thead><tr><th width="308">Name</th><th width="123">Type</th><th>Description</th></tr></thead><tbody><tr><td>**<mark style="color:red;">*</mark></td><td>String</td><td><a href="/thong-tin-chung#phuong-thuc-xac-thuc">Thông tin xác thực chung </a></td></tr></tbody></table>

#### Request Body

<table><thead><tr><th>Name</th><th width="124">Type</th><th>Description</th></tr></thead><tbody><tr><td>ticket<mark style="color:red;">*</mark></td><td>Object</td><td>Đối tượng phiếu ghi</td></tr><tr><td>ticket.ticket_subject</td><td>String</td><td>Tiêu đề phiếu ghi (nếu cần sửa)</td></tr><tr><td>ticket.ticket_comment<mark style="color:red;">*</mark></td><td>Object</td><td>Đối tượng ghi chú cho phiếu ghi. </td></tr><tr><td>ticket.ticket_comment.body<mark style="color:red;">*</mark></td><td>String</td><td>Nội dung comment</td></tr><tr><td>ticket.ticket_comment.is_public</td><td>Int</td><td><a data-footnote-ref href="#user-content-fn-11">(*) Trạng thái ghi chú có các giá trị 0 và 1  </a></td></tr><tr><td>ticket.ticket_comment.author_id<mark style="color:red;">*</mark></td><td>Int</td><td>(*)<a data-footnote-ref href="#user-content-fn-12"> ID của tác giả ghi chú</a></td></tr><tr><td>ticket.ticket_priority</td><td>String</td><td>(*) Độ ưu tiên của phiếu ghi có các trạng thái : Low, High, Normal</td></tr><tr><td>ticket.custom_fields</td><td>Array</td><td>Mảng thông tin trường động, xem thêm <a href="#danh-sach-truong-dong-phieu-ghi">ở đây</a></td></tr><tr><td>ticket.assignee_id</td><td>Int</td><td>Id của chuyên viên (trong trường hợp cần đổi chuyên viên của phiếu ghi) </td></tr><tr><td>ticket.solved_incidents </td><td>Boolean</td><td>True/False (Mặc định True) <br>Trong trường hợp truyền vào là False và ticket_status="Solved". Hệ thống sẽ kiểm tra phiếu ghi con liên quan nếu còn phiếu chưa solved sẽ trả về lỗi 400 kèm danh sách phiếu ghi chưa solved unsolved_incidents_ticket_id.</td></tr><tr><td>ticket.ticket_status</td><td>String</td><td>Trạng thái phiếu ghi nếu cần thay đổi, truyền 1 trong 4 giá trị: "new", "open", "pending", "solved".  <br></td></tr><tr><td>ticket.member_status_id</td><td>Int</td><td>Thay đổi trạng thái chiến dịch của đối tượng (Xem danh sách tại <a href="/danh-muc/restful-api-cua-caresoft/chien-dich">đây </a>),  Áp dụng cho chiến dịch có v_type=1. </td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK Thành công" %}
{% tabs %}
{% tab title="Phản hồi thành công" %}

```json
{
    "code": "ok",
    "ticket": {
        "updated_at": "2023-03-29 17:18:40",
        "ticket_subject": "Test",
        "ticket_no": 7043,
        "created_at": "2023-03-29 13:25:31",
        "ticket_id": 381440615
    }
}
```

{% endtab %}

{% tab title="Mẫu param gửi đi" %}

```json
{
    "ticket": {
        "ticket_subject": "Test",
        "ticket_comment": {
            "body": "Comment",
            "is_public": 1,
            "author_id": 124734559
        },
        "ticket_priority": "Hight",
        "ticket_source": "Voice",
        "custom_fields": [
            {
                "id": "6068",
                "value": "106902"
            }
        ]
    }
}

```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="400: Bad Request Thất bại" %}
{% code title="Lỗi sai tác giả" %}

```json
{
    "code": "errors",
    "message": "invalid value: author_id"
}
```

{% endcode %}

{% code title="Lỗi ID phiếu ghi không tồn tai" %}

```json
{
    "code": "errors",
    "message": "Ticket is not exist"
}

```

{% endcode %}
{% endtab %}

{% tab title="401: Unauthorized Sai token" %}

{% endtab %}

{% tab title="400 Lỗi phiếu ghi con chưa solved" %}

```json
{
    "code": "errors",
    "message": "unsolved_incidents_ticket",
    "extraDataJson": {
        "unsolved_incidents_ticket_id": [
            474842751
        ]
    }
}
```

{% endtab %}
{% endtabs %}

## Danh sách trường động phiếu ghi

Trường động được cấu hình trên giao diện CareSoft. Có 7 kiểu dữ liệu cho trường động phiếu ghi.&#x20;

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FVjlgpOd20HZstLX6aJaP%2Fimage.png?alt=media&amp;token=31034842-cf59-4fe5-91a3-ec16595bed13" alt=""><figcaption><p>Cách thức cấu hình trường động phiếu ghi và danh sách các trường động đang có trên giao diện caresoft</p></figcaption></figure>

#### **Chi tiết các kiểu dữ liệu của trường động phiếu ghi.**

<table><thead><tr><th width="73.33333333333331" data-type="number">STT</th><th width="254">Kiểu<select><option value="3b555bec719344f78f8b67c63162bb3f" label="TEXT" color="blue"></option><option value="f07a68d773224b7d8848ad1ad6278e0f" label="NUMBER" color="blue"></option><option value="6a4e190eb3a7468798e53c3b6bd7dd6a" label="DATE" color="blue"></option><option value="fc3026d4d20747eda24902cfd59b765a" label="SINGLE DROP-DOWN LIST" color="blue"></option><option value="8e04f7e4186e4e56a8d593557f7819b7" label="MULTIPLE SELECT DROP-DOWN LIST" color="blue"></option><option value="5fa31b9990694be683f59c9a59f93aac" label="STAGE" color="blue"></option><option value="12f0a7fd99f34c3ea88b6daaf9d79182" label="TEXT AREA" color="blue"></option><option value="2cc2620ad7ad4584b94da1f92e3ce345" label="LINK" color="blue"></option></select></th><th>Ghi chú</th></tr></thead><tbody><tr><td>1</td><td><span data-option="3b555bec719344f78f8b67c63162bb3f">TEXT</span></td><td>Văn bản text (độ dài tối đa 255 ký tự)</td></tr><tr><td>2</td><td><span data-option="f07a68d773224b7d8848ad1ad6278e0f">NUMBER</span></td><td>Kiểu số</td></tr><tr><td>3</td><td><span data-option="6a4e190eb3a7468798e53c3b6bd7dd6a">DATE</span></td><td>Kiểu ngày tháng, định dạng <code>YYYY/MM/DD</code> </td></tr><tr><td>4</td><td><span data-option="fc3026d4d20747eda24902cfd59b765a">SINGLE DROP-DOWN LIST</span></td><td>Kiểu chọn 1 giá trị </td></tr><tr><td>5</td><td><span data-option="8e04f7e4186e4e56a8d593557f7819b7">MULTIPLE SELECT DROP-DOWN LIST</span></td><td>Kiểu chọn nhiều giá trị</td></tr><tr><td>6</td><td><span data-option="12f0a7fd99f34c3ea88b6daaf9d79182">TEXT AREA</span></td><td>Kiểu văn bản với giao diện hiển thị mở rộng</td></tr><tr><td>7</td><td><span data-option="5fa31b9990694be683f59c9a59f93aac">STAGE</span></td><td>Kiểu trạng thái stage, là dạng chọn 1 giá trị tương đương kiểu chọn 1 giá trị </td></tr><tr><td>8</td><td><span data-option="2cc2620ad7ad4584b94da1f92e3ce345">LINK</span></td><td>Kiểu địa chỉ website, định dạng <code>http://</code> hoặc <code>https://</code> </td></tr></tbody></table>

{% hint style="info" %}
L**ưu ý:** Trường động phiếu ghi có thể được bật/ tắt hoặc thay đổi kiểu từ giao diện hệ thống CareSoft,  cần đồng bộ định kỳ hàng ngày để đảm bảo các cấu hình thông tin giữa các hệ thống thông suốt.
{% endhint %}

## Danh sách trường động phiếu ghi

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/tickets/custom_fields`

#### Headers

| Name                                   | Type   | Description                                                        |
| -------------------------------------- | ------ | ------------------------------------------------------------------ |
| \*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung ](/thong-tin-chung#phuong-thuc-xac-thuc) |

{% tabs %}
{% tab title="200: OK " %}
{% tabs %}
{% tab title="Kết quả thành công " %}
{% code title="Mẫu kết quả điển hình" %}

```json
{
  "code": "ok",
  "custom_fields": [
    {
      "custom_field_id": 5159,
      "code":"GHICHU",
      "custom_field_lable": "Ghi chú của",
      "type": "Text Area"
    },
    {
      "custom_field_id": 5160,
      "code":"CHITIETSANPHAM",
      "custom_field_lable": "Chi tiết sản phẩm",
      "type": "Single drop-down list",
      "values": [
        {
          "id": 110725,
          "code":"SachOLY",
          "lable": "Sách ô ly",
          "parent_value_id": 106473
        },
        {
          "id": 110726,
          "lable": "Sách 2",
          "code":null,
          "parent_value_id": 106473
        },
        {
          "id": 110727,
          "code":nul
          "lable": "Bút bi",
          "parent_value_id": 106474
        },
        {
          "id": 110728,
          "code":nul
          "lable": "Bút mực",
          "parent_value_id": 106474
        }
      ]
    }
  ]
}
```

{% endcode %}
{% endtab %}

{% tab title="Mô tả kết quả" %}

<table><thead><tr><th width="84" data-type="number">STT</th><th width="179">Tên trường</th><th width="116">Kiểu</th><th>Ghi chú</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>String</td><td><a data-footnote-ref href="#user-content-fn-13">Trạng thái </a></td></tr><tr><td>2</td><td>custom_fields</td><td>Array</td><td>[1] Mảng dữ liệu trường động </td></tr></tbody></table>

*\[1] Chi tiết dữ liệu trường động*

<table><thead><tr><th width="82" data-type="number">STT</th><th width="185">Tên trường</th><th>Chú thích</th></tr></thead><tbody><tr><td>1</td><td>custom_field_id</td><td>ID của trường động</td></tr><tr><td>2</td><td>custom_field_lable</td><td>Tên của trường động </td></tr><tr><td>3</td><td>type</td><td><a data-mention href="#chi-tiet-cac-kieu-du-lieu-cua-truong-dong-phieu-ghi.">#chi-tiet-cac-kieu-du-lieu-cua-truong-dong-phieu-ghi.</a></td></tr><tr><td>4</td><td>values</td><td>Mảng object giá trị và ID giá trị được cấu hình sẵn trên caresoft. (Đối với loại trường động dạng chọn 1, chọn nhiều và tiến Trình (type=3,4,7) </td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="404: Not Found " %}

{% endtab %}
{% endtabs %}

## Danh sách phiếu ghi&#x20;

Tùy theo từng nghiệp vụ nhà phát triển có thể sử dụng các param CareSoft cung cấp để lọc các phiếu ghi phát sinh trong quá trình hoạt động.&#x20;

### 1. Danh sách phiếu ghi&#x20;

*(Phiên bản V2)*

{% hint style="warning" %}
**Lưu ý:** API Danh sách phiếu ghi bắt buộc  phải có 1 trong hai cặp parameter  \[created\_since/created\_to] Hoặc \[updated\_since/updated\_to] và thời gian không quá 31 ngày.

Trong trường hợp tất cả các  param đều được điền dữ liệu thì cặp \[updated\_since/updated\_to] được ưu tiên. \
Định dạng dữ liệu dạng Năm-Tháng-NgàyTGiờ:Phút:GiâyZ \
Ví dụ: `created_since=2023-06-26T00:00:00Z` \
Các  hệ thống đang tích hợp cần bổ sung điều kiện tìm kiếm để đáp ứng. Thông báo lỗi sẽ trả về mã lỗi "errors" và param đính kèm ( Xem thêm trong phần Response của API phía dưới: Lỗi 400)
{% endhint %}

## V2- Lấy danh sách phiếu ghi&#x20;

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v2/tickets`

Danh sách phiếu ghi và các điều kiện lọc danh sách phiếu ghi qua API

#### Headers

| Name                                   | Type   | Description                                                        |
| -------------------------------------- | ------ | ------------------------------------------------------------------ |
| \*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung ](/thong-tin-chung#phuong-thuc-xac-thuc) |

#### Request Body

| Name                                             | Type               | Description                                                                                                          |
| ------------------------------------------------ | ------------------ | -------------------------------------------------------------------------------------------------------------------- |
| created\_since                                   | DateTime (ISO8601) | Ngày tạo từ lúc, định dạng YYYY-mm-ddTHH:mm:ssZ                                                                      |
| created\_to                                      | DateTime (ISO8601) | Ngày tạo tới, định dạng YYYY-mm-ddTHH:mm:ssZ                                                                         |
| updated\_since<mark style="color:red;">\*</mark> | DateTime (ISO8601) | Ngày cập nhật từ, định dạng YYYY-mm-ddTHH:mm:ssZ                                                                     |
| updated\_to<mark style="color:red;">\*</mark>    | DateTime (ISO8601) | Ngày cập nhật tới, định dạng YYYY-mm-ddTHH:mm:ssZ                                                                    |
| requester\_id                                    | Int                | ID người yêu cầu                                                                                                     |
| assignee\_id                                     | Int                | ID người xử lý                                                                                                       |
| service\_id                                      | Int                | ID dịch vụ                                                                                                           |
| page                                             | Int                | Trang số                                                                                                             |
| count                                            | Int                | Số bản ghi trên trang (tối đa 500)                                                                                   |
| filter\_id                                       | Int                | ID bộ lọc *(Không khả dụng với các bác bộ lọc có tham số người dùng đăng nhập hay bộ phận của người dùng đăng nhập)* |

{% tabs %}
{% tab title="200: OK Kết quả thành công" %}
{% tabs %}
{% tab title="Kết quả điển hình" %}

```json
{
    "code": "ok",
    "numFound": 414,
    "tickets": [
        {
            "ticket_no": 7464,
            "ticket_status": "new",
            "ticket_subject": "Cuộc gọi ra gặp khách hàng tới ****",
            "created_at": "2023-04-24T17:01:35Z",
            "updated_at": "2023-04-24T17:01:52Z",
            "ticket_source_end_status": 0,
            "ticket_source": "Voice Out",
            "ticket_priority": "Normal",
            "service_id": 20043428,
            "ticket_id": 387792628,
            "requester_id": 165802327,
            "assignee_id": 162712234,
            "custom_fields": [              
                {
                    "id": 5163,
                    "lable": "Tiến trình Deal",
                    "type": "Stage",
                    "value": 13332
                },
                {
                    "id": 5164,
                    "lable": "Phân loại phiếu ghi",
                    "type": "Single drop-down list",
                    "value": 1122
                },  
                ....                
                                                              
                 
            ],
            "assignee": {
                "id": 162712234,
                "username": "ltvyy",
                "email": "****m",
                "phone_no": "0****",
                "agent_id": "50027",
                "role_id": 2,
                "group_id": 14181,
                "group_name": "ORV"
            },
            "requester": {
                "id": 165802327,
                "username": "09326****",
                "email": null,
                "phone_no": "0932****",
                "organization_id": null
            },
            "tags": [],
            "ccs": [],
            "follows": []
        },
    ...
  ]
}
```

{% endtab %}

{% tab title="Mô tả kết quả" %}

<table><thead><tr><th width="139">STT</th><th>Tên trường</th><th>Chú thích</th></tr></thead><tbody><tr><td>1</td><td>code</td><td><p>Trạng thái yêu cầu:<br>ok: Thành công</p><p>error: Thất bại</p></td></tr><tr><td>2</td><td>numFound</td><td>Số bản ghi tìm thấy</td></tr><tr><td>3</td><td>tickets [array]</td><td>Mảng dữ liệu phiếu ghi chứa các đối tượng thông tin phiếu ghi</td></tr></tbody></table>

Chi tiết 1 đối tượng phiếu ghi trong mảng tickets

<table><thead><tr><th width="138">STT</th><th>Tên trường</th><th>Chú thích</th></tr></thead><tbody><tr><td>1</td><td>ticket_no</td><td>Số phiếu ghi</td></tr><tr><td>2</td><td>ticket_status</td><td>Trạng thái phiếu ghi là 1 trong trong các giá trị<br>New, Open, Pending, Closed, Solved</td></tr><tr><td>3</td><td>ticket_subject</td><td>Chủ đề phiếu ghi</td></tr><tr><td>4</td><td>created_at</td><td>Ngày tạo</td></tr><tr><td>5</td><td>updated_at</td><td>Ngày cập nhật </td></tr><tr><td>6</td><td>ticket_source_end_status</td><td><a data-footnote-ref href="#user-content-fn-14">Trạng thái kết thúc thoại, chat</a></td></tr><tr><td>7</td><td>ticket_source</td><td>Nguồn phiếu ghi (xem trong danh sách nguồn)</td></tr><tr><td>8</td><td>ticket_priority</td><td>Độ ưu tiên: Gồm các giá trị High, Normal, Low</td></tr><tr><td>9</td><td>service_id</td><td>ID của dịch vụ tạo ra phiếu ghi</td></tr><tr><td>10</td><td>ticket_id</td><td>{{ticketId}} ID của phiếu ghi dùng để giao tiếp qua API </td></tr><tr><td>11</td><td>requester_id</td><td>ID của người yêu cầu, khi lấy thông tin truy xuất chi tiết người yêu cầu thì dùng  ID này</td></tr><tr><td>12</td><td>assignee_id</td><td>ID của chuyên viên xử lý</td></tr><tr><td>13</td><td>custom_fields[array]</td><td>Mảng trường động phiếu ghi và giá trị của nó</td></tr><tr><td>14</td><td>assignee (object)</td><td>Thông tin cơ bản của người xử lý (Tên, ID, Email ..)</td></tr><tr><td>15</td><td>requester (object)</td><td>Thông tin cơ bản của người yêu cầu (Tên, ID, Email ..)</td></tr><tr><td>16</td><td>tags[array]</td><td>Mảng chứa tag của phiếu ghi</td></tr><tr><td>17</td><td>ccs[array]</td><td>Mảng danh sách thông tin người được ccs</td></tr><tr><td>18</td><td>follows [array]</td><td>Mảng danh sách chuyên viên được follow</td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="403: Forbidden " %}

{% endtab %}

{% tab title="500: Internal Server Error " %}

{% endtab %}

{% tab title="400: Bad Request Thông báo lỗi điều kiện đầu vào" %}
1\.  Lỗi chưa có cặp điều kiện bắt buộc\
\
`Request required [updated_since/updated_to] or [created_since/created_to]`\
\
2\. Lỗi thiếu một trong các param hoặc dữ liệu điền trong các param không hợp lệ\
Định dạng phải là "YYYY-MM-DDTHH:mm:ssZ\
\
`Request required [updated_since/updated_to]`\
`Request required [created_since/created_to]`\
\
3\. Lỗi từ ngày/ đến ngày quá 31 ngày  hoặc từ ngày lớn hơn tới ngày \
`created_since must older than created_to and max 31 days`\
\
4\. Lỗi filterID không thể lấy dữ liệu (thường là các filter ID có cấu hình động theo người dùng đăng nhập \
\
`Can't get this filter!`
{% endtab %}
{% endtabs %}

### 2. Danh sách  phiếu ghi &#x20;

*(Phiên bản 1)*

{% hint style="info" %}
**Lưu ý:** Một thuật toán tối ưu lệnh tìm kiếm phiếu ghi sẽ được thực hiện theo mô hình sau

1. Khi gọi API không cung cấp khoảng ngày kết thúc (chỉ truyền ngày bắt đầu:  created\_since hoặc updated\_since). Mà ngày bắt đầu trước  ngày hiện tại hơn 31 ngày thì hệ thống sẽ tự động chọn khoảng ngày kết thúc là ngày hiện tại và trả về kết quả trong 31 ngày tính từ ngày hiện tại.  Nếu ngày bắt đầu nhỏ hơn ngày hiện tại dưới 31 ngày thì hệ thống giữ nguyên ngày bắt đầu và tiến hành lọc dữ liệu theo tham số trên
2. Khi gọi API cung cấp khoảng ngày kết thúc (param: created\_to hoặc updated\_to). Mà ngày kết thúc sau ngày bắt đầu quá 31 ngày thì hệ thống tự chọn lại khoảng ngày bắt đầu bằng ngày kết thúc - 31 ngày
3. Khi gọi API cung cấp cả hai tham số Bắt đầu và Kết thúc cách nhau không quá 31 ngày thì hệ thống lọc phiếu ghi theo giá trị truyền vào này và trả về kết quả tương ứng.
4. Trong trường hợp cặp điều kiện `created_since` và `updated_since` đều được cung cấp hệ thống sẽ ưu tiên xử lý theo điều kiện `updated_since`
   {% endhint %}

## V1- Lấy danh sách phiếu ghi&#x20;

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/tickets`

Danh sách phiếu ghi và các điều kiện lọc danh sách phiếu ghi qua API, Bắt buộc phải có 1 tham số created\_since hoặc updated\_since&#x20;

#### Headers

| Name                                     | Type | Description                                                        |
| ---------------------------------------- | ---- | ------------------------------------------------------------------ |
| \*\*\*<mark style="color:red;">\*</mark> |      | [Thông tin xác thực chung ](/thong-tin-chung#phuong-thuc-xac-thuc) |

#### Request Body

| Name                                             | Type               | Description                                                                                                          |
| ------------------------------------------------ | ------------------ | -------------------------------------------------------------------------------------------------------------------- |
| created\_since<mark style="color:red;">\*</mark> | DateTime (ISO8601) | Ngày tạo từ lúc, định dạng YYYY-mm-ddTHH:mm:ssZ                                                                      |
| created\_to                                      | DateTime (ISO8601) | Ngày tạo đến lúc, định dạng YYYY-mm-ddTHH:mm:ssZ                                                                     |
| updated\_since<mark style="color:red;">\*</mark> | DateTime (ISO8601) | Ngày cập nhật từ lúc, định dạng YYYY-mm-ddTHH:mm:ssZ                                                                 |
| updated\_to                                      | DateTime (ISO8601) | Ngày cập nhật đến lúc, định dạng YYYY-mm-ddTHH:mm:ssZ                                                                |
| assignee\_id                                     | Int                | ID người xử lý                                                                                                       |
| service\_id                                      | Int                | ID dịch vụ                                                                                                           |
| page                                             | Int                | Trang số (Mặc định 1)                                                                                                |
| count                                            | Int                | Số bản ghi trên trang (Mặc định 50 tối đa 500)                                                                       |
| filter\_id                                       | Int                | ID bộ lọc *(Không khả dụng với các bác bộ lọc có tham số người dùng đăng nhập hay bộ phận của người dùng đăng nhập)* |
| requester\_id                                    | Int                | ID người yêu cầu                                                                                                     |

{% tabs %}
{% tab title="200: OK Thành công" %}

```json
{
    "code": "ok",
    "numFound": 414,
    "tickets": [
        {
            "ticket_no": 7464,
            "ticket_status": "new",
            "ticket_subject": "Cuộc gọi ra gặp khách hàng tới ****",
            "created_at": "2023-04-24T17:01:35Z",
            "updated_at": "2023-04-24T17:01:52Z",
            "ticket_source_end_status": 0,
            "ticket_source": "Voice Out",
            "ticket_priority": "Normal",
            "service_id": 20043428,
            "ticket_id": 387792628,
            "requester_id": 165802327,
            "assignee_id": 162712234,
            "custom_fields": [              
                {
                    "id": 5163,
                    "lable": "Tiến trình Deal",
                    "type": "Stage",
                    "value": 13332
                },
                {
                    "id": 5164,
                    "lable": "Phân loại phiếu ghi",
                    "type": "Single drop-down list",
                    "value": 1122
                },  
                ....                
                                                              
                 
            ],
            "assignee": {
                "id": 162712234,
                "username": "ltvyy",
                "email": "****m",
                "phone_no": "0****",
                "agent_id": "50027",
                "role_id": 2,
                "group_id": 14181,
                "group_name": "ORV"
            },
            "requester": {
                "id": 165802327,
                "username": "09326****",
                "email": null,
                "phone_no": "0932****",
                "organization_id": null
            },
            "tags": [],
            "ccs": [],
            "follows": []
        },
    ...
  ]
}
```

{% endtab %}

{% tab title="400: Bad Request Lỗi thông tin đầu vào" %}

{% endtab %}

{% tab title="403: Forbidden Lỗi xác thực" %}

{% endtab %}

{% tab title="500: Internal Server Error Lỗi máy chủ" %}

{% endtab %}
{% endtabs %}

## Chi tiết phiếu ghi

Dựa trên danh sách phiếu ghi, hoặc việc tạo, cập nhật các phiếu ghi, nhà phát triển có được ID của phiếu ghi. được định danh là "ticketId"

## Lấy chi tiết thông tin phiếu ghi

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/tickets/{{ticketId}}`

Lấy về thông tin chi tiết 1 phiếu ghi theo <mark style="color:green;">`{{ticketId}}`</mark>

#### Headers

| Name                                   | Type   | Description                                                        |
| -------------------------------------- | ------ | ------------------------------------------------------------------ |
| \*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung ](/thong-tin-chung#phuong-thuc-xac-thuc) |

{% tabs %}
{% tab title="200: OK Thông tin thành công" %}
{% tabs %}
{% tab title="Kết quả điển hình " %}
{% code overflow="wrap" %}

```json
{
    "ticket": {
        "account_id": 8187,
        "ticket_id": 387792628,
        "sla_id": 8113,
        "ticket_no": 7464,
        "requester_id": 165802327,
        "group_id": 14181,
        "ticket_source_end_status": 0,
        "assignee_id": 162712234,
        "ticket_priority": "Normal",
        "ticket_source": "Voice Out",
        "ticket_status": "new",
        "ticket_subject": "Cuộc gọi ra gặp khách hàng tới 0932****",
        "created_at": "2023-04-24 17:01:35",
        "updated_at": "2023-04-24 17:01:52",
        "solved": "2023-04-24 17:01:52",
        "duedate": null,
        "satisfaction": null,
        "satisfaction_at": null,
        "satisfaction_send": null,
        "satisfaction_content": null,
        "campaign_id": null,
        "automessage_id": null,
        "feedback_status": "ANSWERED_CALL",
        "is_overdue": null,
        "incident_id": null,
        "service_id": 20043428,
        "ticket_source_detail_id": 85041,
        "qa_agent": 126642807,
        "qa_script_id": 341,
        "current_agent": 124733804,
        "comments": [
            {
                "id": 933864241,
                "comment": "<b>Cuộc gọi ra</b><br/>Người gọi ra: ltvyy (156@gmail.com)<br/>ID cuộc gọi: 20230424170134-OUTOLTHV-935954<br/>Số điện thoại gọi tới: 093xxx<br/>Đầu số gọi ra: xxxx<br/>Thời gian bắt đầu: 2023-04-24 17:01:34<br/>Khách hàng trả lời cuộc gọi<br/>Thời gian trả lời: 2023-04-24 17:01:37<br/>Agent kết thúc cuộc gọi<br/>Thời gian kết thúc: 2023-04-24 17:01:52<br/>Thời lượng cuộc gọi: 00:00:15",
                "commentator_id": 162712234,
                "commentator_name": "ltvyy",
                "comment_source": "Voice Out",
                "call_id": "20230424170134-OUTOLTHV-935954",
                "created_at": "2023-04-24 17:01:35",
                "is_public": 1,
                "addition_details": null,
                "call_info": {
                    "start_time": "2023-04-24 17:01:34",
                    "end_time": "2023-04-24 17:01:51",
                    "called": "842871****",
                    "caller": "09326***",
                    "call_id": "20230424170134-OUTOLTHV-935954"
                }
            }
        ],
        "custom_filed": [
            
                {
                    "id": 5163,
                    "lable": "Tiến trình Deal",
                    "type": "Stage",
                    "value": 13332
                },
                {
                    "id": 5164,
                    "lable": "Phân loại phiếu ghi",
                    "type": "Single drop-down list",
                    "value": 1122
                },  
                ....  
        ],
        "assignee": {
            "id": 162712234,
            "username": "ltvyy",
            "email": "1****",
            "phone_no": "01****",
            "agent_id": "50027",
            "role_id": 1,
            "group_id": 14181,
            "group_name": "ORV"
        },
        "requester": {
            "id": 165802327,
            "username": "09326****",
            "email": null,
            "phone_no": "09326*****",
            "organization_id": null
        },
        "tags": [],
        "ccs": [],
        "follows": [],
        "sla": "2d 06:23",     
        "qa_script": {
            "id": 481,
            "name": "Điểm âm đúng sai",
            "description": "Điểm âm đúng sai",
            "created_at": "2023-05-27 00:10:32",
            "updated_at": "2023-05-27 00:10:32"
        },
        "qa_result": {
            "updated_at": "2023-06-24 02:55:45",
            "is_agree": null,
            "agent_comment": null,
            "agent_comment_time": null,
            "is_lead_agree": null,
            "qa_lead_id": null,
            "qa_lead_name": null,
            "qa_lead_comment": null,
            "qa_comment_time": null,
            "rate": -27,
            "lstQuestions": [
                {
                    "field": "qa_field1",
                    "info": "kí tự",
                    "type": 0,
                    "rate_type": 1,
                    "rate_point": 0,
                    "comment": ""
                },
                {
                    "field": "qa_field2",
                    "info": "số",
                    "type": 1,
                    "rate_type": 1,
                    "rate_point": -1,
                    "comment": ""
                },
                {
                    "field": "qa_field3",
                    "info": "nt",
                    "type": 2,
                    "rate_type": 1,
                    "rate_point": 10,
                    "comment": null
                },
                {
                    "field": "qa_field4",
                    "info": "chọn1pa",
                    "type": 3,
                    "rate_type": -1,
                    "lstOptions": [
                        {
                            "id": 6901,
                            "description": "a1",
                            "point": -100
                        },
                        {
                            "id": 6902,
                            "description": "a1",
                            "point": -50
                        }
                    ],
                    "rate_point": -50
                },
                {
                    "field": "qa_field5",
                    "info": "chon n",
                    "type": 4,
                    "rate_type": -1,
                    "lstOptions": [
                        {
                            "id": 6903,
                            "description": "n1",
                            "point": -4
                        },
                        {
                            "id": 6904,
                            "description": "n2",
                            "point": -10
                        },
                        {
                            "id": 6905,
                            "description": "n3",
                            "point": 5
                        },
                        {
                            "id": 6906,
                            "description": "n4",
                            "point": 8
                        }
                    ],
                    "rate_point": 4
                },
                {
                    "field": "qa_field6",
                    "info": "vban",
                    "type": 6,
                    "rate_type": 1,
                    "rate_point": 10,
                    "comment": ""
                }
            ]
        },
        "qa_agent_name": {
            "username": "QA Test",
            "id": 126642807
        },
        "qa_current_agent": {
            "username": "Admin",
            "id": 124734559
        }


    }
}

```

{% endcode %}
{% endtab %}

{% tab title="Mô tả kết quả" %}

| STT           | Tên trường                  | Chú thích                                                                                                                                                              |
| ------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1             | ticket\_no                  | Số phiếu ghi                                                                                                                                                           |
| 2             | ticket\_status              | Trạng thái phiếu ghi là 1 trong trong các giá trị New, Open, Pending, Closed, Solved                                                                                   |
| 3             | ticket\_subject             | Chủ đề phiếu ghi                                                                                                                                                       |
| 4             | created\_at                 | Ngày tạo                                                                                                                                                               |
| 5             | updated\_at                 | Ngày cập nhật                                                                                                                                                          |
| 6             | ticket\_source\_end\_status | Trạng thái kết thúc thoại, chat                                                                                                                                        |
| 7             | ticket\_source              | Nguồn phiếu ghi (xem trong danh sách nguồn)                                                                                                                            |
| 8             | ticket\_priority            | Độ ưu tiên: Gồm các giá trị High, Normal, Low                                                                                                                          |
| 9             | service\_id                 | ID của dịch vụ tạo ra phiếu ghi                                                                                                                                        |
| 10            | ticket\_id                  | {{ticketId}} ID của phiếu ghi dùng để giao tiếp qua API                                                                                                                |
| 11            | requester\_id               | ID của người yêu cầu, khi lấy thông tin truy xuất chi tiết người yêu cầu thì dùng ID này                                                                               |
| 12            | assignee\_id                | ID của chuyên viên xử lý                                                                                                                                               |
| 13            | custom\_fields\[array]      | Mảng trường động phiếu ghi và giá trị của nó                                                                                                                           |
| 14            | assignee (object)           | Thông tin cơ bản của người xử lý (Tên, ID, Email ..)                                                                                                                   |
| 15            | requester (object)          | Thông tin cơ bản của người yêu cầu (Tên, ID, Email ..)                                                                                                                 |
| 16            | tags\[array]                | Mảng chứa tag của phiếu ghi                                                                                                                                            |
| 17            | ccs\[array]                 | Mảng danh sách thông tin người được ccs                                                                                                                                |
| 18            | follows \[array]            | Mảng danh sách chuyên viên được follow                                                                                                                                 |
| 19            | duedate                     | Thời hạn xử lý                                                                                                                                                         |
| 20            | satisfaction                | Đánh giá của khách hàng                                                                                                                                                |
| 21            | satisfaction\_at            | Thời điểm đánh giá                                                                                                                                                     |
| 22            | satisfaction\_send          | Thời điểm gửi đánh giá                                                                                                                                                 |
| 23            | satisfaction\_content       | Nội dung đánh giá                                                                                                                                                      |
| 24            | campaign\_id                | ID chiến dịch                                                                                                                                                          |
| 25            | automessage\_id             | ID Tin nhắn tự động                                                                                                                                                    |
| 26            | feedback\_status            | Trạng thái phản hồi                                                                                                                                                    |
| 27            | is\_overdue                 | Trạng thái quá hạn xử lý                                                                                                                                               |
| 28            | incident\_id                | ID phiếu ghi cha (nếu có)                                                                                                                                              |
| 29            | ticket\_source\_detail\_id  | ID nguồn chi tiết                                                                                                                                                      |
| 30            | comments \[Array]           | Mảng các ghi chú và tương tác với phiếu ghi                                                                                                                            |
| 31            | sla\_id                     | ID thỏa thuận dịch vụ                                                                                                                                                  |
| 32            | qa\_agent                   | ID Chuyên viên QA                                                                                                                                                      |
| 33            | qa\_script\_id              | ID Kịch bản QA                                                                                                                                                         |
| 34            | current\_agent              | ID Chuyên viên                                                                                                                                                         |
| 35            | qa\_result                  | <p>Object kết quả QA</p><p>Trong đó<br>- info: Tên câu hỏi</p><p>-rate\_point: Điểm được chấm<br>- rate: Tổng điểm<br>- comment: ý kiến bổ sung trong câu trả lời </p> |
| 36            | qa\_script                  | Object thông tin Kịch bản QA                                                                                                                                           |
| 37            | sla                         | Thời hạn còn lại của thỏa thuận dịch vụ (phiên bản 1)                                                                                                                  |
| 38            | solved                      | Thời điểm solved phiếu                                                                                                                                                 |
| {% endtab %}  |                             |                                                                                                                                                                        |
| {% endtabs %} |                             |                                                                                                                                                                        |
| {% endtab %}  |                             |                                                                                                                                                                        |

{% tab title="404: Not Found " %}

{% endtab %}

{% tab title="403: Forbidden Lỗi xác thực" %}

{% endtab %}

{% tab title="500: Internal Server Error Lỗi máy chủ" %}

{% endtab %}

{% tab title="400: Bad Request Lỗi thông tin đầu vào" %}

{% endtab %}
{% endtabs %}

[^1]: **Các trạng thái gồm**&#x20;

    * <mark style="color:blue;">New</mark>
    * <mark style="color:red;">Open</mark>
    * Closed
    * Solved
    * <mark style="color:green;">Pending</mark>

[^2]: Độ ưu tiên gồm&#x20;

    * <mark style="color:red;">High</mark>
    * <mark style="color:green;">Normal</mark>
    * Low

[^3]: 1 Phiếu ghi có phiếu ghi cha nếu `incident_id` khác -1 hoặc null, trong trường hợp `incident_id` =-1 hoặc null&#x20;

[^4]: Bắt buộc một trong các trường Phone\_no hoặc Email

[^5]: Bắt buộc một trong các trường Assignee\_id, Group\_id hoặc service\_id. Để lấy assignee\_id xem trong api [Danh sách chuyên viên](/danh-muc/restful-api-cua-caresoft/chuyen-vien)

[^6]: Có thể tạo 1 dịch vụ và cấu hình cho 1 nhóm chuyên viên xử lý các phiếu ghi phát sinh từ dịch vụ này

[^7]: Vui lòng xem thêm API [danh sách trường động ticket](#danh-sach-truong-dong-phieu-ghi)

[^8]: Khi gửi kèm tham số ref\_url, hệ thống sẽ tự tạo 1 nguồn chi tiết dựa trên tên miền, các mã utm kèm trong link để gom nhóm các phiếu ghi từ một bộ UTM tracking, Giúp cho việc báo cáo  và định lượng hiện quả thuận tiện hơn.&#x20;

[^9]: ID này dùng để lấy thông tin chi tiết hoặc cập nhật một phiếu ghi hiện hữu

[^10]: Sử dụng ID này để lấy thông tin khách hàng đang lưu trữ trên caresoft hoặc các tương tác khác

[^11]: **Các giá trị tương ứng**

    1: Gửi  ra ngoài tới người yêu cầu,&#x20;

    0: Ghi chú nội bộ

[^12]: Tác giả ghi chú có thể là ID Chuyên viên hoặc  Khách hàng.&#x20;

[^13]:

[^14]: Nếu nguồn phiếu ghi là thoại thì: Giá trị 2 là cuộc gọi nhỡ\
    Nếu nguồn phiếu ghi là chat thì giá trị =1 là chat nhỡ


# Danh sách nguồn

Danh sách các nguồn chính của phiếu ghi /kênh thu thập tương tác trên hệ thống CareSoft.

CareSoft hiện xử lý dữ liệu từ rất nhiều nguồn tương tác khác nhau. Các kênh dữ liệu được thể hiện qua các biểu tượng giúp chuyên viên có thể nhanh chóng nhận diện thông tin.\
Các nguồn phát sinh trong tương lai sẽ tiếp tục được bổ sung.

\
**Danh sách nguồn dữ liệu và biểu tượng hiển thị**

<table><thead><tr><th width="92">Stt</th><th width="198">Tên nguồn</th><th width="111">Source ID</th><th width="121">Biểu tượng</th><th>Ghi chú</th></tr></thead><tbody><tr><td>1</td><td>Voice</td><td>1</td><td><img src="https://lh6.googleusercontent.com/egtBu20udOu-hf5VJWHfXBMMY-0d1GC7cQthGuUBjrVpswgOvRYz-JqswV5FKxsyxB1IWFcUiKL4k-j3z01GNky7RSP6GFhh3r0KgbN3BrDPKxxoj2jrowhorZZXqMCWWgmq_vE5OO393j1XOh8KD7s" alt=""></td><td>Gọi vào</td></tr><tr><td>2</td><td>Voice Out</td><td>7</td><td><img src="https://lh3.googleusercontent.com/x0XlWbLGnZT9W982Xp0es2uR96oE1xulT0Zug3YpDp3u1BqYSFyZGBbhWY48eO4t_Ih9YAcivVBl2RqMDKVi5ox4k7i3gC-gYYo0HM2TB5iu_NDdiFQlNvTS5aV98sNMyvI3C0xhquWTJXtRnizrF0Y" alt=""></td><td>Gọi ra</td></tr><tr><td>3</td><td>Chat</td><td>2</td><td><img src="https://lh3.googleusercontent.com/X3ijdvmevCHobHVvCPw2_r-y7xzZONAVaZqhP2mG30oy3Bi5buqpppPES2Nj2tKL3ARie8fCQdkt-1INdnyWZxYiIWHoKs9YohXzc7qhthIB34V2idFdrGvlyAJ-H1FiGNiDbPXiICOZQNNjZyWo4jc" alt=""></td><td>Live chat</td></tr><tr><td>4</td><td>Email</td><td>3</td><td><img src="https://lh4.googleusercontent.com/HQ343PRtQdrrefYB17Pz0aeqZR7o9sQ-uMlgxgsr26VLF35pgQ4xcSkM5mJBdJP6FBRfJPB5CVR-M4DiUfsm1krr7SHQNN-a0_D_9u4g32pvQEYyBr-Vu-HievyXE2RjytRE4gZgM26pKAA5CGU2yug" alt=""></td><td>Email nhận</td></tr><tr><td>5</td><td>Email Out</td><td>8</td><td><img src="https://lh4.googleusercontent.com/HQ343PRtQdrrefYB17Pz0aeqZR7o9sQ-uMlgxgsr26VLF35pgQ4xcSkM5mJBdJP6FBRfJPB5CVR-M4DiUfsm1krr7SHQNN-a0_D_9u4g32pvQEYyBr-Vu-HievyXE2RjytRE4gZgM26pKAA5CGU2yug" alt=""></td><td>Email gửi</td></tr><tr><td>6</td><td>Instagram</td><td>27</td><td><img src="https://lh6.googleusercontent.com/k1vQ5T3HEnyVJsK-0Z3jf_LHH9rk-sCHaPJU5HDhbGJKdx6AQKx9FcOoHGUzT_-hU4Lymt9onLrjNPN1H_aOMIB50E_4VTo1rbt5O_FbOe2fq4W9pBOMeaEjiT4hyJGPZGBSUXCpRPAxLbfs2F8kZ4I" alt=""></td><td>Instagram</td></tr><tr><td>7</td><td>Chat Instagram</td><td>28</td><td><img src="https://lh6.googleusercontent.com/k1vQ5T3HEnyVJsK-0Z3jf_LHH9rk-sCHaPJU5HDhbGJKdx6AQKx9FcOoHGUzT_-hU4Lymt9onLrjNPN1H_aOMIB50E_4VTo1rbt5O_FbOe2fq4W9pBOMeaEjiT4hyJGPZGBSUXCpRPAxLbfs2F8kZ4I" alt=""></td><td>Chat Instagram</td></tr><tr><td>8</td><td>Inbox Zalo ZNS</td><td>25</td><td><img src="https://lh3.googleusercontent.com/EaETtdI7uQDNmgKufD4Cl2BcPvRMGNTZBLSzlZB5YOHbqUm90OsawkkC6GQh9qC5A1eUsHEmklscnZzRi2zK3ZqT4a8qzC83wahDwRxvTDAkREfGpD_hHsN9nCZvl8iE10SU2lYuTD_mK-laDkZvGTQ" alt=""></td><td>Tin nhắn Zalo ZNS</td></tr><tr><td>9</td><td>Zalo Lead Form</td><td>26</td><td><img src="https://lh3.googleusercontent.com/EaETtdI7uQDNmgKufD4Cl2BcPvRMGNTZBLSzlZB5YOHbqUm90OsawkkC6GQh9qC5A1eUsHEmklscnZzRi2zK3ZqT4a8qzC83wahDwRxvTDAkREfGpD_hHsN9nCZvl8iE10SU2lYuTD_mK-laDkZvGTQ" alt=""></td><td>Đăng ký form Zalo</td></tr><tr><td>10</td><td>Inbox Zalo</td><td>11</td><td><img src="https://lh3.googleusercontent.com/EaETtdI7uQDNmgKufD4Cl2BcPvRMGNTZBLSzlZB5YOHbqUm90OsawkkC6GQh9qC5A1eUsHEmklscnZzRi2zK3ZqT4a8qzC83wahDwRxvTDAkREfGpD_hHsN9nCZvl8iE10SU2lYuTD_mK-laDkZvGTQ" alt=""></td><td>Tin nhắn Zalo (nhận)</td></tr><tr><td>11</td><td>Inbox Zalo Out</td><td>24</td><td><img src="https://lh3.googleusercontent.com/EaETtdI7uQDNmgKufD4Cl2BcPvRMGNTZBLSzlZB5YOHbqUm90OsawkkC6GQh9qC5A1eUsHEmklscnZzRi2zK3ZqT4a8qzC83wahDwRxvTDAkREfGpD_hHsN9nCZvl8iE10SU2lYuTD_mK-laDkZvGTQ" alt=""></td><td>Tin nhắn Zalo gửi ra</td></tr><tr><td>12</td><td>Api</td><td>16</td><td><img src="https://lh6.googleusercontent.com/kcHdIMp_Rd4BGFxIEV6y-FmdraXN_YcJ-d7Nwnsn5kRS8WBaO9KHN1tgWuG-XZDxKvCsoiq-yieya4JFpDFhbEvZsnLSCt4wqApC0vqTqbf6Qmtw3D827sBS5fWL-3SZNvoTcsitd03Z-hovpDWtV5s" alt=""></td><td>Nguồn tích hợp API </td></tr><tr><td>13</td><td>Ticket Form</td><td>21</td><td><img src="https://lh6.googleusercontent.com/kcHdIMp_Rd4BGFxIEV6y-FmdraXN_YcJ-d7Nwnsn5kRS8WBaO9KHN1tgWuG-XZDxKvCsoiq-yieya4JFpDFhbEvZsnLSCt4wqApC0vqTqbf6Qmtw3D827sBS5fWL-3SZNvoTcsitd03Z-hovpDWtV5s" alt=""></td><td>Tích hợp Ticket Form Caresoft</td></tr><tr><td>14</td><td>Inbox Facebook</td><td>10</td><td><img src="https://lh3.googleusercontent.com/zqchN-0VNYNrgQk_vIx5z3ii4ZMs3KiXhGiWiwLrBF4vil47ZzQVRqt_1_fLk5no3qbSElK8-gcROD9RrATJI4rQSAg8TdK07gtLlXN5AUTFFvTNK-oSoyIeKGz9tTzh0iaaKZmAFcHMiZQy1t92OzQ" alt=""></td><td>Tin nhắn Facebook</td></tr><tr><td>15</td><td>Inbox Facebook Out</td><td>23</td><td><img src="https://lh3.googleusercontent.com/zqchN-0VNYNrgQk_vIx5z3ii4ZMs3KiXhGiWiwLrBF4vil47ZzQVRqt_1_fLk5no3qbSElK8-gcROD9RrATJI4rQSAg8TdK07gtLlXN5AUTFFvTNK-oSoyIeKGz9tTzh0iaaKZmAFcHMiZQy1t92OzQ" alt=""></td><td>Tin nhắn Facebook gửi ra</td></tr><tr><td>16</td><td>Facebook</td><td>4</td><td><img src="https://lh4.googleusercontent.com/thVIOqJbIXDUaFb5jvOmk5Slb4HQ-4XjoQyPCWP5iUpZOrXlSgalkTUxMKupkWQ9XuEdI2nZrGjhZGRsEZd84VdrLZNa9jB6yfs18EBivi_SkuiNv09KYjBosEadSWv5UkIE8mpf9FvgkuqkAeSSGW0" alt=""></td><td>Bình luận từ Facebook</td></tr><tr><td>17</td><td>Facebook Lead Ads</td><td>18</td><td><img src="https://lh4.googleusercontent.com/thVIOqJbIXDUaFb5jvOmk5Slb4HQ-4XjoQyPCWP5iUpZOrXlSgalkTUxMKupkWQ9XuEdI2nZrGjhZGRsEZd84VdrLZNa9jB6yfs18EBivi_SkuiNv09KYjBosEadSWv5UkIE8mpf9FvgkuqkAeSSGW0" alt=""></td><td>Facebook lead Ads</td></tr><tr><td>18 (*)</td><td>Tiktok</td><td></td><td><img src="https://lh5.googleusercontent.com/SzQv4zYfbDQ53M8YRcH9obIH6zQNi0J1zxPYnt5e7waKyJPxvhphV2BIeHvtgB8J7gx3OJhwzyc2JrLkef_ARGPB-JHhCfBlm5vAgKvN3UUT9CZ82dfMtlkKadaxfjejzElXfvHh_F5FUNp7uDhWwOk" alt=""></td><td>Tiktok.</td></tr><tr><td>19</td><td>Web</td><td>6</td><td><img src="https://lh5.googleusercontent.com/ttefq19KhdjHyIzqSoOCfbENEuGBVko7m02YXOnI7l2bSJJ-MBYNi65utFeviNlkn9j4k3KitJTJEyrJDg9nM_YpLzsb-QjunFB6riuV3dctDMPhpmpXfLvTTLNmjh5kLOuBF1XKbVeNw0o2Ej4Om_w" alt=""></td><td>Các phiếu ghi tự tạo hoặc nguồn chưa cập nhật biểu tượng sẽ được thay thế bằng biểu tượng này<br></td></tr><tr><td>20</td><td>Ticket Sharing</td><td>22</td><td></td><td>Chia sẻ phiếu ghi cho một domain khác </td></tr><tr><td>21</td><td>IVR</td><td>20</td><td></td><td>Từ nhánh IVR của hotline</td></tr><tr><td>22</td><td>Voice Campaign</td><td>19</td><td></td><td>Chiến dịch Voice Campaign</td></tr><tr><td>23</td><td>Facebook Rating</td><td>17</td><td></td><td>Facebook Rating</td></tr><tr><td>24</td><td>Sms Out</td><td>9</td><td></td><td>Gửi SMS ra ngoài</td></tr><tr><td>25</td><td>Voicemail</td><td>5</td><td></td><td>Voicemail</td></tr></tbody></table>

\
\
(\*) Đang phát triển


# Nguồn chi tiết

Nguồn chi tiết là một thuộc tính của phiếu ghi nó chỉ rõ hơn nguồn phát sinh của phiếu ghi. Ví dụ: Từ một nhánh cụ thể  của số hotline, các comment của một bài viết trên trang Facebook hoặc phiếu ghi tạo qua API có các `ref_url` khác nhau ...

**Bảng thông tin của nguồn chi tiết**

<table><thead><tr><th width="88">STT</th><th width="218">Trường dữ liệu</th><th>Mô tả</th></tr></thead><tbody><tr><td>1</td><td>label</td><td>Tên nguồn</td></tr><tr><td>2</td><td>utm_campaign</td><td>UTM campaign</td></tr><tr><td>3</td><td>utm_source</td><td>UTM Source</td></tr><tr><td>4</td><td>utm_medium</td><td>UTM Medium</td></tr><tr><td>5</td><td>utm_term</td><td>UTM Term</td></tr><tr><td>6</td><td>utm_content</td><td>UTM Content</td></tr><tr><td>7</td><td>ad_id</td><td>Facebook ad Id</td></tr><tr><td>8</td><td>ad_campaign_id</td><td>Facebook ad Campaign Id</td></tr><tr><td>9</td><td>ad_name</td><td>Facebook ad name</td></tr><tr><td>10</td><td>ad_campaign_name</td><td>Facebook ad Campaign Name</td></tr><tr><td>11</td><td>adset_id</td><td>Adset Id </td></tr><tr><td>12</td><td>adset_name</td><td>Adset Name</td></tr></tbody></table>

## Lấy thông tin nguồn chi tiết qua API

Trong API  chi tiết phiếu ghi, tham số "`ticket_source_detail_id`" là ID của 1 nguồn chi tiết phát sinh ra phiếu ghi đó.  Để biết thông tin của nguồn này gọi theo API dưới đây

## Thông tin chi tiết của nguồn phiếu ghi

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/tickets/source/details/{{ticket_source_detail_id}}`

{{ticket\_source\_detail\_id}} là ID nguồn chi tiết lấy được từ API chi tiết ticket.&#x20;

#### Headers

| Name | Type   | Description                                                        |
| ---- | ------ | ------------------------------------------------------------------ |
| \*\* | String | [Thông tin xác thực chung ](/thong-tin-chung#phuong-thuc-xac-thuc) |

{% tabs %}
{% tab title="200: OK Kết quả điển hình" %}
{% tabs %}
{% tab title="Kết quả điển hình" %}

```json
{
    "status": true,
    "source_detail": {
        "label": "Web caresoft.vn",
        "utm_campaign": "SPRING_SALE_2023",
        "utm_source": "home_caresoft",
        "utm_medium": "banner",
        "utm_term": null,
        "utm_content": null,
        "ad_id": null,
        "ad_account_id": null,
        "ad_campaign_id": null,
        "adgroup_id": null,
        "ad_name": null,
        "ad_campaign_name": null,
        "ad_ref": null,
        "created_at": "2023-02-21 14:54:16",
        "updated_at": "2023-02-21 14:54:16",
        "channel": 6      
    },
    "code": "ok"
}
```

{% endtab %}

{% tab title="Mô tả" %}

{% endtab %}
{% endtabs %}

{% endtab %}
{% endtabs %}

<table><thead><tr><th width="88">STT</th><th width="218">Trường dữ liệu</th><th>Mô tả</th></tr></thead><tbody><tr><td>1</td><td>label</td><td>Tên nguồn</td></tr><tr><td>2</td><td>utm_campaign</td><td>UTM campaign</td></tr><tr><td>3</td><td>utm_source</td><td>UTM Source</td></tr><tr><td>4</td><td>utm_medium</td><td>UTM Medium</td></tr><tr><td>5</td><td>utm_term</td><td>UTM Term</td></tr><tr><td>6</td><td>utm_content</td><td>UTM Content</td></tr><tr><td>7</td><td>ad_id</td><td>Facebook ad Id</td></tr><tr><td>8</td><td>ad_campaign_id</td><td>Facebook ad Campaign Id</td></tr><tr><td>9</td><td>ad_name</td><td>Facebook ad name</td></tr><tr><td>10</td><td>ad_campaign_name</td><td>Facebook ad Campaign Name</td></tr><tr><td>11</td><td>adset_id</td><td>Adset Id </td></tr><tr><td>12</td><td>adset_name</td><td>Adset Name</td></tr></tbody></table>


# Lead

Các API liên quan đến đối tượng Leads

## 1. Tạo mới Lead

<mark style="color:green;">`POST`</mark> `/{domain}/api/v1/lead`

Tạo mới Lead

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Body**

<table data-full-width="false"><thead><tr><th width="82">STT</th><th>Param</th><th width="113">Kiểu</th><th width="92">Độ dài</th><th>Ghi chú</th></tr></thead><tbody><tr><td>1*</td><td>lead</td><td>object</td><td><br></td><td>Đối tượng chứa thông tin lead</td></tr><tr><td>….</td><td>Các trường trong object lead<br></td><td><br></td><td><br></td><td><br></td></tr><tr><td>1</td><td>username</td><td>text</td><td>250</td><td>Họ tên khách hàng (Trong trường hợp số điện thoại hoặc email của khách đã tồn tại sẽ không sử dụng tham số này) </td></tr><tr><td>2</td><td>subject (*)</td><td>text</td><td>250</td><td>Tiêu đề</td></tr><tr><td>3</td><td>phone (*)</td><td>tel</td><td>50</td><td>Số điện thoại của khách hàng</td></tr><tr><td>4</td><td>email (*)</td><td>email</td><td>50</td><td>Email của khách hàng</td></tr><tr><td>5</td><td>service_id (**)</td><td>Int</td><td>10</td><td>Dịch vụ tiếp nhận Lead</td></tr><tr><td>6</td><td>group_id (**)</td><td>Int</td><td>10</td><td>ID bộ phận tiếp nhận</td></tr><tr><td>7</td><td>assignee_id (**)</td><td>Int</td><td>10</td><td>ID chuyên viên tiếp nhận</td></tr><tr><td>8</td><td>lead_status_id</td><td>Int</td><td>10 </td><td>ID trạng thái lead (Mặc định không điền sẽ lấy trạng thái đầu</td></tr><tr><td>9</td><td>estimated_closed_date</td><td>DateTime</td><td><br></td><td>Dự kiến hoàn thành (Định dạng YYYY-MM-DD HH:mm:ss) </td></tr><tr><td>10</td><td>lead_label</td><td>Array</td><td><br></td><td>Mảng ID label của lead Dạng [1,2,3]</td></tr><tr><td>11</td><td>custom_fields</td><td>Array</td><td><br></td><td>Mảng custom_fields tương tự tạo ticket</td></tr><tr><td>12</td><td>comment</td><td>Text</td><td>5000</td><td>Nội dung ghi chú</td></tr><tr><td>13</td><td>unqualify_reason</td><td>Int</td><td>10</td><td>ID của lý do không đạt (Chỉ áp dụng nếu lead_status_id ở trạng thái cuối)</td></tr></tbody></table>

Mẫu body JSON  tạo lead

```json
{
    "lead": {
        "phone": "0983980148",
        "service_id": 1244,
        "subject": "Test lead",
        "comment": "Helo world",
        "estimated_closed_date": "2024/03/21 23:59:59",
        "lead_status": 558,
        "lead_label_id": [
            10,
            11
        ],
        "ref_url": "https://gooogle.com?utm_content=TestREFERURL&utm_source=GANEW"
    }
}
```

**Kết quả phản hồi**\
Trong đối tượng lead trả về có chứa ID chính là Lead Id dùng để cập nhật hoặc thực thi các tác vụ khác liên quan

{% tabs %}
{% tab title="200" %}

```json
{
    "code": "ok",
    "lead": {
        "updated_at": "2024-03-21 15:11:06",
        "subject": "Test referer lead",
        "created_at": "2024-03-21 15:11:06",
        "id": 414856017,
        "requester_id": 63215969
    }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## 2. Cập nhật Lead

<mark style="color:green;">`PUT`</mark> `/{domain}/api/v1/lead/{leadId}`

Cập nhật 1 lead với {leadId} là ID từ quá trình tạo mới hoặc quét dữ liệu đồng bộ từ trước

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Body**

| STT | Param                   | Type        | Length      | Description                                                                               |
| --- | ----------------------- | ----------- | ----------- | ----------------------------------------------------------------------------------------- |
| 1\* | lead                    | object      | <p><br></p> | Đối tượng chứa thông tin lead                                                             |
| ….  | <p><br></p>             | <p><br></p> | <p><br></p> | <p><br></p>                                                                               |
| 2   | subject                 | text        | 250         | Tiêu đề                                                                                   |
| 3   | assignee\_id            | Int         | 10          | ID chuyên viên tiếp nhận                                                                  |
| 4   | lead\_status\_id        | Int         | 10          | ID trạng thái lead (Mặc định không điền sẽ lấy trạng thái đầu                             |
| 5   | estimated\_closed\_date | DateTime    | <p><br></p> | Dự kiến hoàn thành (Định dạng YYYY-MM-DD HH:mm:ss)                                        |
| 6   | lead\_label             | Array       | <p><br></p> | Mảng ID label của lead Dạng \[1,2,3]                                                      |
| 7   | custom\_fields          | Array       | <p><br></p> | Mảng custom\_fields tương tự tạo ticket                                                   |
| 8   | comment (\*)            | OBJECT      | <p><br></p> | Object đối tượng comment                                                                  |
| 9   | comment.body            | Text        | 5000        | Nội dung comment                                                                          |
| 10  | comment.is\_public      | Int         | 1           | <p>Trạng thái comment<br>0: Ghi chú<br>1: Public (VD: Gửi email cho người yêu cầu …) </p> |
| 11  | comment.author\_id      | Int         | 10          | ID của người bình luận                                                                    |
| 12  | unqualify\_reason       | Int         | 10          | ID của lý do không đạt (Chỉ áp dụng nếu lead\_status\_id ở trạng thái cuối)               |

Mẫu ví dụ body Json cập nhật LeadID: 414856017

**PUT**: `/{domain}/api/v1/lead/414856017`

```json
{
    "lead": {
        "subject": "Tesst",
        "comment": {
            "body": "Cập nhật giá trị mua hành thành giao hàng",
            "is_public": 1,
            "author_id": 124734559
        },
        "lead_status_id": 1,
        "estimated_closed_date": "2024-04-11 00:00:00",
        "lead_label": [
            11,
            22
        ],
        "custom_fields": [
            {
                "id": "6068",
                "value": "106902"
            }
        ]
    }
}

```

**Kết quả phản hồi**

{% tabs %}
{% tab title="200" %}

```json
{
    "code": "ok",
    "lead": {
        "updated_at": "2024-03-21 15:11:06",
        "subject": "Test referer lead",
        "created_at": "2024-03-21 15:11:06",
        "id": 414856017,
        "requester_id": 63215969
    }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## 3. Chi tiết Lead

<mark style="color:green;">`GET`</mark>`/{domain}/api/v1/lead/{leadId}`

\<Description of the endpoint>

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "lead": {
        "account_id": 8187,
        "id": 512534181,
        "lead_no": 16843,
        "requester_id": 207642682,
        "group_id": 12945,
        "ticket_source_end_status": null,
        "assignee_id": 124734559,
        "ticket_source": "Voice Out",
        "merge_status": null,
        "merge_to": null,
        "clone_from": null,
        "subject": "Cuộc gọi ra cho khách hàng  theo chiến dịch: Mơ Sample",
        "created_at": "2024-08-07 14:17:11",
        "updated_at": "2024-09-30 12:04:38",
        "duedate": null,
        "satisfaction": null,
        "satisfaction_content": null,
        "satisfaction_at": null,
        "satisfaction_send": null,
        "campaign_id": 78830,
        "campaign_action_id": -1,
        "campaign_status": 0,
        "automessage_id": null,
        "manualmessage_id": null,
        "incident_id": -1,
        "service_id": null,
        "qa_script_id": null,
        "qa_agent": null,
        "current_agent": null,
        "ticket_source_detail_id": 1154135,
        "convert_by": 124734559,
        "convert_at": "2024-08-07 14:24:12",
        "convert_type": 1,
        "unqualified_reasons": null,
        "last_lead_status_id": 25,
        "estimated_closed_date": null,
        "lead_status_id": 26,
        "comments": [
            {
                "ticket_comments_id": 1211536855,
                "ticket_id": 512534181,
                "comment": "aa",
                "commentator_id": 124734559,
                "username": "Admin1",
                "facebook": null,
                "facebook_name": null,
                "comment_source": null,
                "created_at": "2024-09-30 12:04:38",
                "attack_file_id": null,
                "file_name": null,
                "file_id": null,
                "download_connection_string": null,
                "call_id": null,
                "email_receive_id": null,
                "addition_details": null,
                "is_public": 0,
                "can_hide": null,
                "can_remove": null,
                "can_reply_privately": null,
                "facebook_comment_state": 0,
                "role_id": 1,
                "avatar": "https://3.bp.blogspot.com/-qCI9fu4I2SE/Y7UkNAM4jhI/AAAAAAAENjs/YWNtRIeDGjghZbiZmu9aduswuxvmuTYSACNcBGAsYHQ/photo.png?imgmax=3000"
            }  
        ],
        "custom_fields": [
            {
                "id": 5159,
                "label": "Kí tự 19",
                "type": "Text",
                "value": null
            },
            {
                "id": 9579,
                "label": "Phân loại ticket cha(2602)",
                "type": "Single drop-down list",
                "value": null
            }
        ],
        "tags": [],
        "ccs": [],
        "follows": [],
        "labels": [],
        "campaign": {
            "id": 78830,
            "campaign_name": "Mơ Sample",
            "status": 0
        },
        "campaign_action": null,
        "assignee": {
            "id": 124734559,
            "username": "Admin1",
            "email": "**@gmail.com",
            "phone_no": "***",
            "agent_id": "50024",
            "role_id": 1,
            "group_id": 12153,
            "group_name": "Default Group"
        },
        "requester": {
            "id": 207642682,
            "username": "cfsdcf",
            "email": null,
            "phone_no": null,
            "organization_id": null
        }
    }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## 4. Danh sách lead

<mark style="color:green;">`GET`</mark> `/{domain}/api/v1/leads`

Lấy danh sách các leads

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Parameter**

| Param          | Ghi chú                                                                                              |
| -------------- | ---------------------------------------------------------------------------------------------------- |
| requester\_id  | ID Người yêu cầu                                                                                     |
| assignee\_id   | ID Chuyên viên                                                                                       |
| service\_id    | ID dịch vụ                                                                                           |
| page           | Trang số (mặc định 1)                                                                                |
| count          | Số bản ghi /trang (mặc định 50, max 500)                                                             |
| created\_since | <p>Ngày tạo từ (Kiểu Time TZ)<br>Vd: 2024-06-01T00:00:00Z</p>                                        |
| created\_to    | <p>Ngày tạo tới (Kiểu Time TZ)<br>Vd: 2024-06-01T00:00:00Z</p>                                       |
| updated\_since | <p>Ngày cập nhật từ (Kiểu Time TZ)<br>Vd: 2024-06-01T00:00:00Z</p><p><br></p>                        |
| updated\_to    | <p>Ngày cập nhật tới (Kiểu Time TZ)<br>Vd: 2024-06-01T00:00:00Z</p><p><br></p>                       |
| convert\_since | <p>Ngày chuyển đổi thành deal (từ lead) (Kiểu Time TZ)<br>Vd: 2024-06-01T00:00:00Z</p><p><br></p>    |
| convert\_to    | <p>Ngày chuyển đổi thành deal tới (Kiểu Time TZ)<br>Vd: 2024-06-01T00:00:00Z</p><p><br></p>          |
| status\_ids    | <p>Trạng thái leads, chọn nhiều cách nhau bởi dấu phẩy<br>VD: 12 hoặc 12,34,56</p>                   |
| convert\_type  | <p>Trạng thái chuyển đổi từ lead sang deal</p><p>1: Chuyển thành Lead, 2: Chuyển thành Không đạt</p> |

**Mẫu dữ liệu phản hồi**

{% tabs %}
{% tab title="200" %}

```json
{
  "code": "ok",
  "numFound": 1,
  "leads": [
    {
      "id": 414857091,
      "lead_no": 273763,
      "requester_id": 63216680,
      "ticket_source_end_status": 1,
      "assignee_id": 1,
      "ticket_priority": "Normal",
      "ticket_source": "Voice Out",
      "is_overdue": null,
      "subject": "Cuộc gọi ra cho khách hàng loi.tranquang",
      "created_at": "2024-05-03T15:28:40Z",
      "updated_at": "2024-05-03T15:28:40Z",
      "duedate": null,
      "service_id": 2005289,
      "incident_id": null,
      "satisfaction": null,
      "satisfaction_at": null,
      "satisfaction_content": null,
      "campaign_id": null,
      "automessage_id": null,
      "source_detail_id": 127,
      "convert_by": null,
      "convert_at": null,
      "convert_type": null,
      "unqualified_reasons": null,
      "last_lead_status_id": null,
      "lead_status_id": 525,
      "estimated_closed_date": null
    }
  ]
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## 5. Các thành phần khác của Lead

Các API bổ sung cho lead&#x20;

## 5.1 Danh sách trạng thái lead

<mark style="color:green;">`GET`</mark> `/{domain}/api/v1/lead/status`

Danh sách các trạng thái lead đã cấu hình trên hệ thống

Trong đó:

1. label: Tên trạng thái
2. id: ID trạng thái
3. status\_type: Kiểu trạng thái. 1: Đầu tiên, ,0 Giữa (đổi vị trí thoải mái-- index các loại), 2: Converted (index to nhất), 3: Unqualify

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Kết quả minh họa**&#x20;

{% tabs %}
{% tab title="200" %}

```json
{
  "code": "ok",
  "data": [
    {"id": 525, "label": "Tương tác mới"   , "status_type": 1},
    {"id": 557, "label": "Đang liên hệ"    , "status_type": 0},
    {"id": 558, "label": "Comming"         , "status_type": 0},
    {"id": 643, "label": "Trạng thái demo" , "status_type": 0},
    {"id": 527, "label": "Lead Converted1" , "status_type": 2},
    {"id": 528, "label": "Lead Unqualified", "status_type": 3}
  ]
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## 5.2 Danh sách lý do không đạt Lead

<mark style="color:green;">`GET`</mark> `/{domain}/api/v1/lead/unqualified-reason`

Danh sách id các lý do không đạt đã được cấu hình cho lead

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "code": "ok",
  "data": [
    {
      "id": 176,
      "label": "No need"
    },
    {
      "id": 177,
      "label": "Not the decision maker"
    },
    {
      "id": 182,
      "label": "No budget"
    },
    {
      "id": 217,
      "label": "Lead unqualified"
    }
  ]
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## 5.3 Danh sách lead labels

<mark style="color:green;">`GET`</mark> `/{domain}/lead/labels`

\<Description of the endpoint>

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "code": "ok",
  "data": [
    {
      "id": 17,
      "label": "5",
      "created_at": "2023-10-03 17:11:01",
      "updated_at": "2023-10-03 17:11:01"
    },
    {
      "id": 11,
      "label": "Cold",
      "created_at": "2023-10-02 11:13:17",
      "updated_at": "2023-10-02 11:13:17"
    },
    {
      "id": 22,
      "label": "Freezing@2",
      "created_at": "2023-10-25 14:22:14",
      "updated_at": "2023-10-25 14:22:14"
    }
  ]
}

```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}


# Deal

Các API Liên quan đến deals

## 1. Tạo mới deal

<mark style="color:green;">`POST`</mark> `/{domain}/api/v1/deal`

Tạo mới deal

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**JSON body payload**

| STT | Param                                   | Kiểu dữ liệu | Độ dài      | Ghi chú                                                                                                                                       |
| --- | --------------------------------------- | ------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| 1\* | deal                                    | object       | <p><br></p> | Đối tượng chứa thông tin lead                                                                                                                 |
| ..  | <p><br>Các trường trong object deal</p> | <p><br></p>  | <p><br></p> | <p><br></p>                                                                                                                                   |
| 1   | username                                | Text         | 250         | Họ tên khách hàng (Trong trường hợp số điện thoại hoặc email của khách đã tồn tại sẽ không sử dụng tham số này)                               |
| 2   | subject (\*)                            | text         | 250         | Tiêu đề                                                                                                                                       |
| 3   | phone (\*)                              | tel          | 50          | Số điện thoại của khách hàng                                                                                                                  |
| 4   | email (\*)                              | email        | 50          | Email của khách hàng                                                                                                                          |
| 5   | service\_id  (\*\*)                     | Int          | 10          | Dịch vụ tiếp nhận Lead                                                                                                                        |
| 6   | group\_id (\*\*)                        | Int          | 10          | ID bộ phận tiếp nhận                                                                                                                          |
| 7   | assignee\_id (\*\*)                     | Int          | 10          | ID chuyên viên tiếp nhận                                                                                                                      |
| 8   | pipeline\_id                            | Int          | 10          | [ID tiến trình ](#id-5.1-danh-sach-cac-tien-trinh-va-giai-doan)(Mặc định theo cấu hình)                                                       |
| 9   | estimated\_closed\_date                 | DateTime     | <p><br></p> | Dự kiến hoàn thành (Định dạng YYYY-MM-DD HH:mm:ss)                                                                                            |
| 10  | deal\_label                             | Array        | <p><br></p> | <p>Mảng ID label của deal dạng \[1,2,3]</p><p><br></p>                                                                                        |
| 11  | pipeline\_stage\_id                     | Int          | <p><br></p> | I[D giai đoạn của tiến trình](#id-5.1-danh-sach-cac-tien-trinh-va-giai-doan) (mặc định là đầu giai đoạn)                                      |
| 12  | custom\_fields                          | Array        | <p><br></p> | Mảng custom\_fields tương tự tạo ticket                                                                                                       |
| 13  | probability                             | Int          | 10          | Tỉ lệ thành công (từ 0-100)                                                                                                                   |
| 14  | value                                   | Int          | 10          | Giá trị đơn hàng (Số)                                                                                                                         |
| 15  | comment                                 | Text         | 5000        | Nội dung ghi chú                                                                                                                              |
| 9   | comment.body                            | Text         | 5000        | Nội dung comment                                                                                                                              |
| 10  | comment.is\_public                      | Int          | 1           | <p>Trạng thái comment<br>0: Ghi chú<br>1: Public (VD: Gửi email cho người yêu cầu …) </p>                                                     |
| 11  | comment.author\_id                      | Int          | 10          | ID của người bình luận                                                                                                                        |
| 12  | order\_address\_detail                  | String       | 255         | Địa chỉ chi tiết                                                                                                                              |
| 13  | order\_buyer\_note                      | String       | 500         | Ghi chú của người mua                                                                                                                         |
| 14  | order\_city\_id                         | String       | 10          | ID của tỉnh (Theo danh sách [Tỉnh thành](/danh-muc/restful-api-cua-caresoft/khach-hang/thong-tin-tinh-huyen-xa#lay-danh-sach-tinh-thanh-pho)) |
| 15  | order\_district\_id                     | String       | 10          | ID của huyện/quận (Theo danh sách  quận huyện)                                                                                                |
| 16  | order\_ward\_id                         | String       | 10          | ID của Xã/phường (Theo danh sách xã phường)                                                                                                   |
| 17  | order\_receiver\_name                   | String       | 200         | Người nhận                                                                                                                                    |
| 18  | order\_receiver\_phone                  | String       | 20          | Số ĐT người nhận                                                                                                                              |
| 19  | order\_shipping\_fee                    | Float        |             | Cước vận chuyển                                                                                                                               |
| 20  | order\_status                           | String       | 50          | Là một trong danh sách sau - [Danh sách trạng thái](#user-content-fn-1)[^1]                                                                   |
| 21  | order\_tracking\_code                   | String       | 50          | Mã vận chuyển                                                                                                                                 |
| 22  | order\_tracking\_url                    |              | 500         | Đường dẫn kiểm tra trạng thái vận chuyển                                                                                                      |
| 23  | order\_products                         | Array        |             | <p>Mảng sản phẩm (<a data-footnote-ref href="#user-content-fn-2">Xem chi tiết trong mẫu</a>) <br></p>                                         |

**Mẫu Payload**

```json
{
  "deal": {
    "phone": "0983980148",
    "subject": "Test referer url",
    "value": "233333",
    "probability": 23,
    "estimated_closed_date": "2024/03/21 23:59:59",
    "deal_label": [
      10,
      11
    ],
    "pipeline_id": 56,
    "pipeline_stage_id": "377",
    "custom_fields": [
      {
        "id": "6068",
        "value": "106902"
      }
    ]
  }
}
```

**Mẫu phản hồi**

{% tabs %}
{% tab title="200" %}

```json
{
    "code": "ok",
    "deal": {
        "updated_at": "2024-03-21 15:04:04",
        "subject": "Test referer url",
        "created_at": "2024-03-21 15:04:04",
        "id": 414856013,
        "requester_id": 63215969
    }
}

```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## 2. Cập nhật deal

<mark style="color:green;">`PUT`</mark> `/{domain}/api/v1/deal/{dealId}`

Cập nhật deal cần ID được lấy từ giá trị deal.id ở tiến trình tạo deal hoặc từ các nguồn khai thác đã tạo deal từ trước.

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**JSON body payload**

| STT | Param                   | Kiểu dữ liệu | Độ dài      | Ghi chú                                                                                                     |
| --- | ----------------------- | ------------ | ----------- | ----------------------------------------------------------------------------------------------------------- |
| 1\* | deal                    | object       | <p><br></p> | Đối tượng chứa thông tin lead                                                                               |
| ….  | <p><br></p>             | <p><br></p>  | <p><br></p> | <p><br></p>                                                                                                 |
| 2   | subject                 | text         | 250         | Tiêu đề                                                                                                     |
| 7   | assignee\_id            | Int          | 10          | ID chuyên viên tiếp nhận                                                                                    |
| 8   | pipeline\_id            | Int          | 10          | ID tiến trình (Mặc định theo cấu hình)                                                                      |
| 9   | estimated\_closed\_date | DateTime     | <p><br></p> | Dự kiến hoàn thành (Định dạng YYYY-MM-DD HH:mm:ss)                                                          |
| 10  | deal\_label             | Array        | <p><br></p> | <p>Mảng ID label của deal dạng \[1,2,3]</p><p><br></p>                                                      |
| 11  | pipeline\_stage\_id     | Int          | <p><br></p> | ID giai đoạn của tiến trình (mặc định là đầu giai đoạn)                                                     |
| 12  | custom\_fields          | Array        | <p><br></p> | Mảng custom\_fields tương tự tạo ticket                                                                     |
| 13  | probability             | Int          | 10          | Tỉ lệ thành công (từ 0-100)                                                                                 |
| 14  | value                   | INt          | 10          | Giá trị đơn hàng (Số)                                                                                       |
| 15  | comment (\*)            | Object       | <p><br></p> | Nội dung ghi chú                                                                                            |
| 16  | order\_address\_detail  | String       | 255         | Địa chỉ chi tiết                                                                                            |
| 17  | order\_buyer\_note      | String       | 20          | Ghi chú của người mua                                                                                       |
| 18  | order\_city\_id         | String       | 10          | ID tỉnh thành trên CareSoft                                                                                 |
| 19  | order\_district\_id     | String       | 10          | ID huyện trên CareSoft                                                                                      |
| 20  | order\_ward\_id         | String       | 10          | ID xã trên CareSoft                                                                                         |
| 21  | order\_receiver\_name   | String       | 299         | Người nhận                                                                                                  |
| 22  | order\_receiver\_phone  | String       | 29          | SDT người nhận                                                                                              |
| 23  | order\_shipping\_fee    | Float        |             | Giá cước                                                                                                    |
| 24  | order\_status           | String       | 50          | Trạng thái đơn hàng, Là một trong[  (Danh sách )](#user-content-fn-3)[^3]                                   |
| 25  | order\_tracking\_code   | String       | 59          | Mã vận chuyển                                                                                               |
| 26  | order\_tracking\_url    | String       | 500         | <p>Đường dẫn kiểm tra trạng thái vận chuyển</p><p><br></p>                                                  |
| 27  | order\_products         | Array        |             | <p>Mảng sản phẩm (Xem <a data-footnote-ref href="#user-content-fn-4">chi tiết trong mẫu</a>)</p><p><br></p> |

**Mẫu JSON BODY**

```json
{
  "deal": {
    "subject": "Tesst",
    "comment": {
      "body": "Cập nhật giá trị mua hành thành giao hàng",
      "is_public": 1,
      "author_id": 124734559
    },
    "pipeline_stage_id": 1,
    "pipeline_id": 122,
    "probability": "70",
    "value": "200000",
    "estimated_closed_date": "2024-04-11 00:00:00",
    "deal_label": [
      11,
      22
    ],
    "custom_fields": [
      {
        "id": "6068",
        "value": "106902"
      }
    ]
  }
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "code": "ok",
    "deal": {
        "updated_at": "2024-03-21 15:04:04",
        "subject": "Test referer url",
        "created_at": "2024-03-21 15:04:04",
        "id": 414856013,
        "requester_id": 63215969
    }
}

```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## 3. Chi tiết deal

<mark style="color:green;">`GET`</mark> `/{domain}/api/v1/deal/{dealId}`

Lấy chi tiết 1 deal theo tham số dealID được tạo từ bước 1 hoặc được khai thác từ quá trình đồng bộ

&#x20;Các tham số của Deal gồm

* converted\_at: Ngày chuyển đổi
* converted\_by: ID chuyên viên chuyển đổi
* converted\_type: Kiểu chuyển đổi ( 1: Chuyển thành deal, 2: Chuyển thành không đạt
* lead\_status\_id: Id của trạng thái lead ( mục I.2)
* last\_lead\_status\_id: ID trạng thái trước khi chuyển đổi
* unqualified\_reasons: [Id Lý do không đạt](#id-5.2-ly-do-khong-dat) (Xem mục I.4)
* labels : nhãn của Lead  (Xem mục I.3)
* estimated\_closed\_date: thời gian dự kiến hoàn thành&#x20;
* closed\_at: Thời gian đóng deal&#x20;
* closed\_by: Người đóng deal&#x20;
* closed\_type: Kiểu đóng deal( kiểu Won/ Lost/ Unqualified)
* pipeline\_id: ID tiến trình của deal&#x20;
* pipeline\_stage\_id: ID giai đoạn của deal
* value: Giá trị của deal
* probability: Tỷ lệ thành công của deal&#x20;
* last\_deal\_stage\_id: ID giai đoạn cuối trước khi đóng của deal&#x20;
* lost\_reasons: [Lý do mất của deal ](#id-5.3-ly-do-mat-don)
* order\_address\_detail: Chi tiết địa chỉ giao hàng
* order\_buyer\_note: Ghi chú của người mua
* order\_city\_id: ID City (Theo danh sách [thành phố](/danh-muc/restful-api-cua-caresoft/khach-hang/thong-tin-tinh-huyen-xa#lay-danh-sach-tinh-thanh-pho))
* order\_district\_id: ID quận huyện (Theo danh sách [quận huyện](/danh-muc/restful-api-cua-caresoft/khach-hang/thong-tin-tinh-huyen-xa#lay-danh-sach-tinh-thanh-pho-1))
* order\_ward\_id: ID phường xã  (Theo danh sách[ phường xã](/danh-muc/restful-api-cua-caresoft/khach-hang/thong-tin-tinh-huyen-xa#lay-danh-sach-tinh-thanh-pho-1) )
* order\_receiver\_name: Tên người nhận
* order\_receiver\_phone: Số điện thoại người nhận đơn
* order\_shipping\_fee: Giá cước vận chuyển
* order\_payment: Phương thức thanh toán
* order\_status:  Trạng thái đặt hàng, ORDER\_STARTED&#x20;
* order\_tracking\_code: Mã vận chuyển
* order\_tracking\_url: Đường dẫn tra cứu vận chuyển của nhà cung cấp dịch vụ
* order\_products: \[...]. Mảng sản phẩm đặt mua
  * name:Tên sản phẩm
  * sku: SKU sản phẩm,&#x20;
  * is\_free: Là sản phẩm tặng kèm (1) hoặc bình thường (0)&#x20;
  * unit\_price: Đơn giá&#x20;
  * quantity: Số lượng
  * discount\_markup:Giảm giá bằng %
  * discount\_value: Giảm giá bằng tiền
  * total\_amount: Tổng tiền của sản phẩm&#x20;

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "deal": {
    "account_id": 8187,
    "id": 474845380,
    "deal_no": 13241,
    "requester_id": 156011012,
    "group_id": 14181,
    "ticket_source_end_status": null,
    "assignee_id": 124733804,
    "ticket_source": "Facebook",
    "merge_status": null,
    "merge_to": null,
    "clone_from": null,
    "subject": "Test Deal",
    "created_at": "2024-03-16 02:22:55",
    "updated_at": "2024-10-21 13:58:39",
    "duedate": null,
    "satisfaction": null,
    "satisfaction_content": null,
    "satisfaction_at": null,
    "satisfaction_send": null,
    "campaign_id": null,
    "campaign_action_id": null,
    "campaign_status": null,
    "automessage_id": null,
    "manualmessage_id": null,
    "incident_id": -1,
    "service_id": 91047363,
    "qa_script_id": null,
    "qa_agent": null,
    "current_agent": null,
    "ticket_source_detail_id": 290025,
    "convert_by": null,
    "convert_at": null,
    "convert_type": null,
    "unqualified_reasons": 0,
    "last_lead_status_id": null,
    "lead_status_id": null,
    "estimated_closed_date": "2024-10-23 23:59:59",
    "closed_at": "2024-10-12 01:48:54",
    "closed_by": 124733804,
    "closed_type": 3,
    "pipeline_id": 17,
    "pipeline_stage_id": 129,
    "value": 1000,
    "probability": 40,
    "last_deal_stage_id": 125,
    "lost_reasons": null,
    "order_address_detail": "Đơn hàng từ Khách lẻ",
    "order_buyer_note": "Giao giờ hành chính",
    "order_city_id": "01",
    "order_district_id": "021",
    "order_receiver_name": "windy",
    "order_receiver_phone": "03466****66",
    "order_shipping_fee": 30000,
    "order_payment": null,
    "order_status": "ORDER_STARTED",
    "order_tracking_code": "122xxx",
    "order_tracking_url": "https://shippingprovider..../?trackingId=",
    "order_ward_id": "00617",
    "order_products": [
      {
        "name": "Boots",
        "sku": "2",
        "is_free": 0,
        "unit_price": 50000,
        "quantity": 1,
        "discount_markup": 10,
        "discount_value": 0,
        "total_amount": 45000
      },
      {
        "name": "Harpic White and Shine Disinfectant Toilet Cleaner Bleach - 500 ml | India's # 1 Toilet Cleaner",
        "sku": "11",
        "is_free": 0,
        "unit_price": 6245,
        "quantity": 1,
        "discount_markup": 0,
        "discount_value": 2000,
        "total_amount": 4245
      }
    ],
    "comments": [
      {
        "ticket_comments_id": 1224857808,
        "ticket_id": 474845380,
        "comment": "1",
        "commentator_id": 124734559,
        "username": "Admin1",
        "facebook": null,
        "facebook_name": null,
        "comment_source": null,
        "created_at": "2024-10-21 13:58:39",
        "attack_file_id": null,
        "file_name": null,
        "file_id": null,
        "download_connection_string": null,
        "call_id": null,
        "email_receive_id": null,
        "addition_details": null,
        "is_public": 0,
        "can_hide": null,
        "can_remove": null,
        "can_reply_privately": null,
        "facebook_comment_state": 0,
        "role_id": 1,
        "avatar": "https://3.bp.blogspot.com/-qCI9fu4I2SE/Y7UkNAM4jhI/AAAAAAAENjs/YWNtRIeDGjghZbiZmu9aduswuxvmuTYSACNcBGAsYHQ/photo.png?imgmax=3000"
      }
    ],
    "custom_fields": [
      {
        "id": 5159,
        "label": "Kí tự 19",
        "type": "Text",
        "value": null
      },
      {
        "id": 6055,
        "label": "Địa chỉ link 19",
        "type": "Link",
        "value": null
      },
      {
        "id": 9579,
        "label": "Phân loại ticket cha(2602)",
        "type": "Single drop-down list",
        "value": null
      }
    ],
    "tags": [],
    "ccs": [
      {
        "id": 156011012,
        "username": "Hùng Nguyễn",
        "email": "Nj@hj.vn"
      }
    ],
    "follows": [],
    "labels": [
      {
        "id": 32,
        "label": "New letter",
        "updated_at": "2024-10-21 13:58:39"
      },
      {
        "id": 31,
        "label": "No Label",
        "updated_at": "2024-10-21 13:58:39"
      }
    ],
    "assignee": {
      "id": 124733804,
      "username": "Hùng zx",
      "email": "hungnx1@caresoft.vn",
      "phone_no": "0334992975",
      "agent_id": "50000",
      "role_id": 1,
      "group_id": 14181,
      "group_name": "ORV"
    },
    "requester": {
      "id": 156011012,
      "username": "Sample",
      "email": "abc@gamil.com",
      "phone_no": "09***12009",
      "organization_id": 245826,
      "organization": {
        "organization_id": 245826,
        "organization_domain": "",
        "organization_name": "Sample org"
      }
    }
  }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## 4. Danh sách deals

<mark style="color:green;">`GET`</mark> `/{domain}/api/v1/deals`

Danh sách deal đang có trên hệ thống

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Parameters**

| Param          | Ghi chú                                                                                                    |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| requester\_id  | ID Người yêu cầu                                                                                           |
| assignee\_id   | ID Chuyên viên                                                                                             |
| service\_id    | ID dịch vụ                                                                                                 |
| page           | Trang số (mặc định 1)                                                                                      |
| count          | Số bản ghi /trang (mặc định 50, max 500)                                                                   |
| created\_since | <p>Ngày tạo từ (Kiểu Time TZ)<br>Vd: 2024-06-01T00:00:00Z</p>                                              |
| created\_to    | <p>Ngày tạo tới (Kiểu Time TZ)<br>Vd: 2024-06-01T00:00:00Z</p>                                             |
| updated\_since | <p>Ngày cập nhật từ (Kiểu Time TZ)<br>Vd: 2024-06-01T00:00:00Z</p><p><br></p>                              |
| updated\_to    | <p>Ngày cập nhật tới (Kiểu Time TZ)<br>Vd: 2024-06-01T00:00:00Z</p><p><br></p>                             |
| convert\_since | <p>Ngày chuyển đổi thành deal (từ lead) (Kiểu Time TZ)<br>Vd: 2024-06-01T00:00:00Z</p><p><br></p>          |
| convert\_to    | <p>Ngày chuyển đổi thành deal tới (Kiểu Time TZ)<br>Vd: 2024-06-01T00:00:00Z</p><p><br></p>                |
| closed\_since  | <p>Ngày đóng Deal  từ  (Kiểu Time TZ)<br>Vd: 2024-06-01T00:00:00Z</p><p><br></p>                           |
| closed\_to     | <p>Ngày đóng Deal  tới (Kiểu Time TZ)<br>Vd: 2024-06-01T00:00:00Z</p>                                      |
| pipeline\_ids  | <p>ID Tiến trình  chọn nhiều  cách nhau bởi dấu phẩy<br>VD: 12 hoặc 12,34,56</p>                           |
| stage\_ids     | <p>ID  chọn nhiều cách nhau bởi dấu phẩy<br>VD: 12 hoặc 12,34,56</p>                                       |
| closed\_type   | <p>Trạng thái đóng:<br>1:  Thành công, 2: Mất Deal , 3: Không đạt </p>                                     |
| convert\_type  | <p>Trạng thái chuyển đổi từ lead sang deal</p><p>1:Chuyển thành Deal , 2:  Chuyển thành unqualified.  </p> |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "code": "ok",
    "numFound": 2,
    "deals": [
        {
            "id": 414858584,
            "deal_no": 275062,
            "requester_id": 63203703,
            "ticket_source_end_status": null,
            "assignee_id": 63203703,
            "ticket_priority": "Normal",
            "ticket_source": "Web",
            "is_overdue": null,
            "subject": "csxcsxdv",
            "created_at": "2024-05-24T17:22:21Z",
            "updated_at": "2024-05-27T11:32:17Z",
            "duedate": null,
            "service_id": null,
            "incident_id": -1,
            "satisfaction": null,
            "satisfaction_at": null,
            "satisfaction_content": null,
            "campaign_id": null,
            "automessage_id": null,
            "ticket_source_detail_id": null,
            "convert_by": null,
            "convert_at": null,
            "convert_type": null,
            "unqualified_reasons": null,
            "last_lead_status_id": null,
            "lead_status_id": null,
            "estimated_closed_date": "2024-05-24 23:59:59",
            "closed_at": "2024-05-27 11:06:02",
            "closed_by": 63203703,
            "closed_type": 2,
            "pipeline_id": 56,
            "pipeline_stage_id": 382,
            "value": 0,
            "probability": 20,
            "last_deal_stage_id": 377,
            "lost_reasons": 79
        },
        {
            "id": 414857144,
            "deal_no": 273806,
            "requester_id": 1,
            "ticket_source_end_status": null,
            "assignee_id": 1,
            "ticket_priority": "Normal",
            "ticket_source": "Web",
            "is_overdue": null,
            "subject": "xxxx",
            "created_at": "2024-05-07T13:46:14Z",
            "updated_at": "2024-05-07T17:48:36Z",
            "duedate": null,
            "service_id": null,
            "incident_id": -1,
            "satisfaction": null,
            "satisfaction_at": null,
            "satisfaction_content": null,
            "campaign_id": null,
            "automessage_id": null,
            "ticket_source_detail_id": null,
            "convert_by": null,
            "convert_at": null,
            "convert_type": null,
            "unqualified_reasons": null,
            "last_lead_status_id": null,
            "lead_status_id": null,
            "estimated_closed_date": null,
            "closed_at": "2024-05-07 17:48:36",
            "closed_by": 29370874,
            "closed_type": 2,
            "pipeline_id": 56,
            "pipeline_stage_id": 382,
            "value": 0,
            "probability": 5,
            "last_deal_stage_id": 376,
            "lost_reasons": 85
        }
    ]
}

```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## 5. Các API liên quan khác

## 5.1 Danh sách Các tiến trình và giai đoạn

<mark style="color:green;">`GET`</mark> `/{domain}/api/v1/deal/pipelines`

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Response**

{% tabs %}
{% tab title="200" %}

```json

{
    "code": "ok",
    "data": [
        {
            "id": 41,
            "label": "Sale pipeline",
            "created_at": "2024-03-01 09:43:10",
            "updated_at": "2024-03-30 00:40:06",
            "default": 0,
            "stages": [
                {
                    "id": 296,
                    "pipeline_id": 41,
                    "stage_name": "Tư vấn triển khai ",
                    "stage_type": 1,
                    "probability": 50
                },
                {
                    "id": 298,
                    "pipeline_id": 41,
                    "stage_name": "Hợp đồng báo giá",
                    "stage_type": 0,
                    "probability": 20
                },
                {
                    "id": 299,
                    "pipeline_id": 41,
                    "stage_name": "Vận đơn Logistic",
                    "stage_type": 0,
                    "probability": 70
                },
                {
                    "id": 300,
                    "pipeline_id": 41,
                    "stage_name": "Thanh toán thành công",
                    "stage_type": 2,
                    "probability": 0
                },
                {
                    "id": 301,
                    "pipeline_id": 41,
                    "stage_name": "Hoàn hàng ",
                    "stage_type": 3,
                    "probability": 0
                },
                {
                    "id": 302,
                    "pipeline_id": 41,
                    "stage_name": "Đổi trả ",
                    "stage_type": 4,
                    "probability": 0
                }
            ]
        } 
        
      
    ]
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## 5.2 Lý do không đạt&#x20;

<mark style="color:green;">`GET`</mark>`/{domain}/api/v1/deal/unqualified-reasons`

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "code": "ok",
    "data": [
        {
            "id": 193,
            "label": "No need"
        },
        {
            "id": 194,
            "label": "Not the decision maker"
        },
        {
            "id": 195,
            "label": "No budget"
        },
        {
            "id": 196,
            "label": "Not the right timing"
        },
        {
            "id": 197,
            "label": "Other"
        }
    ]
}

```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## 5.3 Lý do mất đơn

<mark style="color:green;">`POST`</mark> `/{domain}/api/v1/deal/lost-reasons`

\<Description of the endpoint>

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Body**

| Name   | Type   | Description      |
| ------ | ------ | ---------------- |
| `name` | string | Name of the user |
| `age`  | number | Age of the user  |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "code": "ok",
    "data": [
        {
            "id": 20,
            "label": "Lost to competiton"
        },
        {
            "id": 21,
            "label": "Poor follow up"
        },
        {
            "id": 22,
            "label": "We are too expensive"
        },
        {
            "id": 23,
            "label": "Timing Gap"
        }
    ]
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## 5.4 Deal labels&#x20;

<mark style="color:green;">`GET`</mark> `/{domain}/api/v1/deal/labels`

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Body**

| Name   | Type   | Description      |
| ------ | ------ | ---------------- |
| `name` | string | Name of the user |
| `age`  | number | Age of the user  |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "code": "ok",
    "data": [
        {
            "id": 37,
            "label": "Automation",
            "created_at": "2023-10-27 23:18:55",
            "updated_at": "2023-10-27 23:18:55"
        },
        {
            "id": 29,
            "label": "Cold Deal",
            "created_at": "2023-10-27 23:16:34",
            "updated_at": "2023-10-27 23:16:34"
        }, 
        {
            "id": 30,
            "label": "Web Form",
            "created_at": "2023-10-27 23:16:45",
            "updated_at": "2023-10-27 23:16:45"
        }
    ]
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

[^1]: "ORDER\_STARTED":  Khởi tạo đơn hàng

    "BUYER\_CONFIRMED": Người mua xác nhận

    "SELLER\_CONFIRMED:  Nhà bán xác nhận

    "SHIPPING": Đang vận chuyển

    "RETURNED": Hoàn

    "CANCELED": Hủy

    "RECEIVED"": Đã nhận

[^2]: &#x20;"sku": Mã sản phẩm

    &#x20;"is\_free": Hàng tặng "1", Mặc định 0

    &#x20;"unit\_price": Giá tiền

    &#x20;"quantity":  Số lượng

    &#x20;"discount\_markup": Tỉ lệ giảm giá,  "discount\_value":  Giảm giá bằng  tiền&#x20;

[^3]: "ORDER\_STARTED": Khởi tạo đơn hàng&#x20;

    "BUYER\_CONFIRMED": Người mua xác nhận&#x20;

    "SELLER\_CONFIRMED: Nhà bán xác nhận

    "SHIPPING": Đang vận chuyển

    "RETURNED": Hoàn

    "CANCELED": Hủy

    "RECEIVED"": Đã nhận

[^4]: "sku": Mã sản phẩm

    "is\_free": Hàng tặng "1", Mặc định 0

    "unit\_price": Giá tiền

    "quantity": Số lượng

    "discount\_markup": Tỉ lệ giảm giá, "discount\_value": Giảm giá bằng tiền


# Khách hàng

Các API liên quan đến người dùng, khách hàng

&#x20;Trên hệ thống CareSoft. Mỗi người dùng/Khách hàng được định nghĩa bằng số điện thoại hoặc email. Một người dùng có tối đa ba (03) số điện thoại và hai (02) email làm định danh. &#x20;

### Các trường thông tin của người dùng

<table><thead><tr><th width="64.33333333333331" data-type="number">STT</th><th width="193">Tên trường</th><th width="162">Kiểu dữ liệu<select><option value="2a353d3434774486ae86a359db22b0cc" label="TEXT(255)" color="blue"></option><option value="96eaa0bd08df4a6e82b19c30e681dd5a" label="INT" color="blue"></option><option value="8180e1a9201c46a6be4a6d9a0da2c4a3" label="SELECTONE" color="blue"></option><option value="fa06aa625469464899e2e5b3afa5ee5a" label="MULTIPLE SELECT" color="blue"></option><option value="01483ea447a642b28b8da91ad3260825" label="EMAIL" color="blue"></option><option value="f677b4cb982e427f8c0b1c017a4700bf" label="TELEPHONE" color="blue"></option><option value="68546980a4954142891f7a23a85a929d" label="DATETIME" color="blue"></option><option value="198ea03807404ef2b9bfce7b672fb269" label="DATE" color="blue"></option><option value="111c0ebfeb3b4edca5e073d8570cec43" label="ARRAY" color="blue"></option><option value="83a62d80fef041869490d60ef9fc3b17" label="OBJECT" color="blue"></option></select></th><th>Ghi chú</th></tr></thead><tbody><tr><td>1</td><td>id</td><td><span data-option="96eaa0bd08df4a6e82b19c30e681dd5a">INT</span></td><td>ID của người dùng</td></tr><tr><td>2</td><td>username</td><td><span data-option="2a353d3434774486ae86a359db22b0cc">TEXT(255)</span></td><td>Họ tên</td></tr><tr><td>3</td><td>email</td><td><span data-option="01483ea447a642b28b8da91ad3260825">EMAIL</span></td><td>Email người dùng</td></tr><tr><td>4</td><td>email2</td><td><span data-option="01483ea447a642b28b8da91ad3260825">EMAIL</span></td><td>Email thứ 2</td></tr><tr><td>5</td><td>phone_no</td><td><span data-option="f677b4cb982e427f8c0b1c017a4700bf">TELEPHONE</span></td><td>Số điện thoại của người dùng</td></tr><tr><td>6</td><td>phone_no2</td><td><span data-option="f677b4cb982e427f8c0b1c017a4700bf">TELEPHONE</span></td><td>Số điện thoại thứ 2</td></tr><tr><td>7</td><td>phone_no3</td><td><span data-option="f677b4cb982e427f8c0b1c017a4700bf">TELEPHONE</span></td><td>Số điện thoại thứ 3</td></tr><tr><td>8</td><td>created_at</td><td><span data-option="68546980a4954142891f7a23a85a929d">DATETIME</span></td><td>Ngày tạo</td></tr><tr><td>9</td><td>updated_at</td><td><span data-option="68546980a4954142891f7a23a85a929d">DATETIME</span></td><td>Ngày cập nhật.</td></tr><tr><td>10</td><td>created_from</td><td><span data-option="96eaa0bd08df4a6e82b19c30e681dd5a">INT</span></td><td>Nguồn tạo (<a href="/danh-muc/restful-api-cua-caresoft/phieu-ghi/danh-sach-nguon">Xem danh sách nguồn</a>) Cột Source ID</td></tr><tr><td>11</td><td>organization_id</td><td><span data-option="96eaa0bd08df4a6e82b19c30e681dd5a">INT</span></td><td>ID tổ chức</td></tr><tr><td>12</td><td>organization</td><td><span data-option="2a353d3434774486ae86a359db22b0cc">TEXT(255)</span></td><td>Tên tổ chức</td></tr><tr><td>13</td><td>city_id</td><td><span data-option="96eaa0bd08df4a6e82b19c30e681dd5a">INT</span></td><td>ID thành phố (Tham khảo danh sách tỉnh thành)</td></tr><tr><td>14</td><td>district_id</td><td><span data-option="96eaa0bd08df4a6e82b19c30e681dd5a">INT</span></td><td>ID huyện/quận </td></tr><tr><td>15</td><td>address</td><td><span data-option="2a353d3434774486ae86a359db22b0cc">TEXT(255)</span></td><td>Địa chỉ</td></tr><tr><td>16</td><td>gender</td><td><span data-option="96eaa0bd08df4a6e82b19c30e681dd5a">INT</span></td><td>Giới tính: 0. Nam, 1 Nữ, 2 Không xác định </td></tr><tr><td>17</td><td>facebook</td><td><span data-option="96eaa0bd08df4a6e82b19c30e681dd5a">INT</span></td><td>ID facebook (De-precade) </td></tr><tr><td>18</td><td>campaign_handler_id</td><td><span data-option="96eaa0bd08df4a6e82b19c30e681dd5a">INT</span></td><td>ID chiến dịch xử lý</td></tr><tr><td>19</td><td>custom_fields</td><td><span data-option="111c0ebfeb3b4edca5e073d8570cec43">ARRAY</span></td><td>Danh sách trường động </td></tr><tr><td>20</td><td>follower_id</td><td><span data-option="96eaa0bd08df4a6e82b19c30e681dd5a">INT</span></td><td>Id của chuyên viên quản lý (xem <a data-mention href="/danh-muc/restful-api-cua-caresoft/chuyen-vien">Chuyên viên</a> Trường ID </td></tr><tr><td>21</td><td>take_phone_at</td><td><span data-option="68546980a4954142891f7a23a85a929d">DATETIME</span></td><td>Thời điểm thu thập được số điện thoại (Null hoặc Ngày tháng)</td></tr><tr><td>22</td><td>take_email_at</td><td><span data-option="68546980a4954142891f7a23a85a929d">DATETIME</span></td><td>Thời điểm thu thập được email(Null hoặc Ngày tháng)</td></tr></tbody></table>

## Thêm mới khách hàng

Để thêm mới khách hàng. Lập trình viên cần tạo 1 đối tượng contact kiểu Json Object có cấu trúc sau. Các trường dữ liệu

{% code title="Mẫu body request tạo khách hàng" %}

```json
{
    "contact": {
        "email": "{{Email khách hàng}}",
        "phone_no": "{{Số điện thoại khách hàng}}",
        "username": "{{Họ tên của khách hàng",
        "address":"{{Địa chỉ khách hàng}}",
        "gender":"{{Giới tính của khách hàng}}"
        "custom_fields": [
            {
                "id": {{ID trường động khách hàng}},
                "value": "{{Giá trị trường động}}"
            }
        ]
    }
}
```

{% endcode %}

Ví dụ tham khảo mẫu POSTMAN tạo mới khách hàng

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FPiuz2I6Te9ptO8LcqaOR%2FcreateContact.png?alt=media&amp;token=6e5ceaad-7f1a-41ba-97be-52d5916a13b5" alt=""><figcaption></figcaption></figure>

## Thêm mới khách hàng

<mark style="color:green;">`POST`</mark> `{{domain}/api/v1/contacts`

#### Headers

| Name | Type   | Description                                                        |
| ---- | ------ | ------------------------------------------------------------------ |
| \*\* | String | [Thông tin xác thực chung ](/thong-tin-chung#phuong-thuc-xac-thuc) |

#### Request Body

| Name    | Type   | Description            |
| ------- | ------ | ---------------------- |
| contact | Object | Cấu trúc object ở trên |

{% tabs %}
{% tab title="200: OK " %}
{% tabs %}
{% tab title="Kết quả điển hình" %}

```json
{
    "code": "ok",
    "contact": {
        "phone_no": "024***22",
        "updated_at": "2023-04-12 14:54:24",
        "created_at": "2023-04-12 14:54:24",
        "id": 63216006,
        "email": "uyel**@**l.com",
        "username": "Le ***yen"
    }
}
```

{% endtab %}

{% tab title="Mô tả trường thông tin điển hình" %}

<table><thead><tr><th width="72">STT</th><th width="171">Tên trường</th><th width="97">Kiểu</th><th>Ý nghĩa</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>String</td><td>"ok": Thành công, "errors": Thất bại</td></tr><tr><td>2</td><td>contact</td><td>Object</td><td>Đối tượng thông tin khách hàng được tạo mới </td></tr><tr><td>3</td><td><strong>contact.id</strong></td><td>Int</td><td><a data-footnote-ref href="#user-content-fn-1">ID khách hàng (?)</a></td></tr><tr><td>4</td><td>contact.phone_no</td><td>String</td><td>Số điện thoại</td></tr><tr><td>5</td><td>contact.email</td><td>Email</td><td>Email</td></tr><tr><td>6</td><td>contact.username</td><td>String</td><td>Họ tên khách hàng</td></tr><tr><td>7</td><td>contact.created_at</td><td></td><td>Ngày tạo</td></tr><tr><td>8</td><td>contact.updated_at</td><td></td><td>Ngày cập nhật</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

{% endtab %}

{% tab title="400: Bad Request " %}
Thông tin trùng lặp hoặc thiếu sẽ thể hiện qua thông báo lỗi này

{% tabs %}
{% tab title="Trùng email" %}

<pre class="language-json"><code class="lang-json">{
    "code": "errors",
    "message": "email already exist",
    "extra_data": {
        "duplicate_id": "<a data-footnote-ref href="#user-content-fn-2">63216006</a>"
    }
}
</code></pre>

{% endtab %}

{% tab title="Trùng số điện thoại" %}

```json
{
    "code": "errors",
    "message": "phone_no already exist",
    "extra_data": {
        "duplicate_id": "63216007"
    }
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="500: Internal Server Error " %}

{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}
{% endtabs %}

## Cập nhật khách hàng

Trong trường hợp có thay đổi thông tin khách hàng, VD: Thay đổi số điện thoại, email hay thông tin người phụ trách hoặc các thông tin phân loại được tùy biến. Lập trình viên sử dụng hàm này để cập nhật dữ liệu lên hệ thống

{% hint style="info" %}
Gợi ý: Trong một số trường hợp không lưu contactId của khách hoặc khách phát sinh trước khi tích hợp, thì sử dụng hàm tạo mới khách hàng sau đó dựa trên `dublicated_id` phát sinh (nếu trùng) để thực hiện cập nhật&#x20;
{% endhint %}

## Cập nhật người dùng

<mark style="color:orange;">`PUT`</mark> `{{domain}/api/v1/contacts/{{contactId}}`

#### Headers

| Name                                   | Type   | Description                                                        |
| -------------------------------------- | ------ | ------------------------------------------------------------------ |
| \*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung ](/thong-tin-chung#phuong-thuc-xac-thuc) |

#### Request Body

| Name    | Type   | Description                        |
| ------- | ------ | ---------------------------------- |
| contact | Object | Cấu trúc object như ví dụ minh họa |

{% tabs %}
{% tab title="200: OK " %}
{% tabs %}
{% tab title="Kết quả điển hình" %}

```
{
    "code": "ok",
    "contact": {
        "phone_no": "024***22",
        "updated_at": "2023-04-12 14:54:24",
        "created_at": "2023-04-12 14:54:24",
        "id": 63216006,
        "email": "uyel**@**l.com",
        "username": "Le ***yen"
    }
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="400: Bad Request " %}

{% endtab %}

{% tab title="500: Internal Server Error " %}

{% endtab %}
{% endtabs %}

## Danh sách khách hàng

Là dữ liệu biến thiên theo ngày tháng. Sẽ tăng dần theo thời gian, Danh sách này có kết quả gồm số ít trường thông tin mang tính chất điển hình gồm ID, số điện thoại, họ tên, email ngày tạo.  Dựa vào danh sách này có thể lấy thông tin đầy đủ và chi tiết cho 1 khách hàng bằng api Chi tiết khách hàng phía dưới&#x20;

Mẫu tham khảo cấu hình POSTMAN lấy danh sách khách hàng

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FIcsVRKLvyNoiMS82oeie%2FkhachhangDanhsach.png?alt=media&amp;token=aff6a1b9-ec34-4f4d-8f9e-bfcce8a92af8" alt=""><figcaption></figcaption></figure>

## Danh sách khách hàng V2 <a href="#cap-nhat-tai-lieu-api-khach-hang-v2" id="cap-nhat-tai-lieu-api-khach-hang-v2"></a>

> ### Thông báo chuyển đổi API <a href="#thong-bao-chuyen-doi-api" id="thong-bao-chuyen-doi-api"></a>
>
> API GET {{domain}}/api/v1/contacts sẽ kết thúc vào ngày 02/09/2026. Sau thời điểm này, hệ thống sẽ tự động chuyển sang endpoint V2 tương ứng:
>
> Để tránh gián đoạn tích hợp, bạn nên chuyển sang V2 trước thời điểm trên. Trong giai đoạn chuyển đổi, API V1 vẫn có thể hoạt động nhưng sẽ được đánh dấu là deprecated.

Dữ liệu được cập nhật theo thời gian. Danh sách trả về một số trường thông tin cơ bản, điển hình như Phiên bản V2 vẫn giữ cấu trúc response gần tương tự V1 để thuận tiện chuyển đổi, đồng thời bổ sung các mốc thời gian thực tế sau khi hệ thống chuẩn hóa khoảng thời gian truy vấn.

### Danh sách khách hàng V2 <a href="#danh-sach-khach-hang-1" id="danh-sach-khach-hang-1"></a>

`GET` `{{domain}}/api/v2/contacts`

**Query Parameters**

| Name            | Type               | Description                                                                                                                                                                                                |
| --------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `updated_since` | DateTime (ISO8601) | Thời điểm bắt đầu cập nhật. Định dạng: YYYY-MM-DDTHH:mm:ssZ                                                                                                                                                |
| `updated_to`    | DateTime (ISO8601) | Thời điểm kết thúc cập nhật. Định dạng: YYYY-MM-DDTHH:mm:ssZ                                                                                                                                               |
| `created_since` | DateTime (ISO8601) | Thời điểm bắt đầu tạo. Định dạng: YYYY-MM-DDTHH:mm:ssZ                                                                                                                                                     |
| `created_to`    | DateTime (ISO8601) | Thời điểm kết thúc tạo. Định dạng: YYYY-MM-DDTHH:mm:ssZ                                                                                                                                                    |
| `page`          | Int                | Trang số. Mặc định `1`                                                                                                                                                                                     |
| `count`         | Int                | Số bản ghi trên trang. Mặc định `50`, tối đa theo cấu hình hệ thống                                                                                                                                        |
| `order_by`      | String             | Sắp xếp theo trường dữ liệu. Hỗ trợ: `id`, `username`, `email`, `email2`, `phone_no`, `phone_no2`, `phone_no3`, `facebook`, `gender`, `organization_id`, `created_at`, `updated_at`. Mặc định `created_at` |
| `order_type`    | String             | Kiểu sắp xếp `DESC` hoặc `ASC`. Mặc định `DESC`                                                                                                                                                            |

**Headers**

| Name  | Type   | Description              |
| ----- | ------ | ------------------------ |
| `***` | String | Thông tin xác thực chung |

**Lưu ý khi sử dụng**

* Chỉ chấp nhận các query parameter nằm trong danh sách trên. Nếu truyền parameter ngoài whitelist, hệ thống trả về HTTP `400`.
* Nếu không có bất kỳ điều kiện ngày hợp lệ nào thuộc nhóm `created_*` hoặc `updated_*`, hệ thống sẽ trả về danh sách rỗng để tránh quét toàn bộ dữ liệu khách hàng.
* Mỗi cặp điều kiện thời gian `created_since/created_to` hoặc `updated_since/updated_to` chỉ được xử lý trong phạm vi tối đa `31 ngày`.

**Quy tắc xử lý thời gian**

* Nếu truyền đủ `created_since` và `created_to`:
  * Nếu khoảng thời gian không quá `31 ngày` thì giữ nguyên.
  * Nếu quá `31 ngày` hoặc `created_since >= created_to` thì hệ thống tự chuẩn hóa thành `created_since = created_to - 31 days`.
* Nếu chỉ truyền `created_since`, hệ thống tự bổ sung `created_to = created_since + 31 days`.
* Nếu chỉ truyền `created_to`, hệ thống tự bổ sung `created_since = created_to - 31 days`.
* Cặp `updated_since/updated_to` áp dụng quy tắc tương tự.
* Giá trị ngày không đúng định dạng hoặc nằm ngoài phạm vi hợp lệ sẽ được hiểu như chưa truyền.

**Kết quả điển hình**

```json
{
  "code": "ok",
  "numFound": 123,
  "created_since": "2026-07-01T00:00:00Z",
  "created_to": "2026-08-01T00:00:00Z",
  "updated_since": null,
  "updated_to": null,
  "contacts": [
    {
      "id": 1001,
      "username": "Nguyen Van A",
      "email": "a@example.com",
      "email2": null,
      "phone_no": "0900000000",
      "phone_no2": null,
      "phone_no3": null,
      "facebook": null,
      "gender": 0,
      "organization_id": null,
      "created_at": "2026-07-15 09:30:00",
      "updated_at": "2026-07-20 10:00:00"
    }
  ]
}
```

#### Mô tả kết quả

| STT | Tên trường      | Chú thích                                                                    |
| --- | --------------- | ---------------------------------------------------------------------------- |
| 1   | `code`          | Trạng thái thành công. `ok`: Thành công, `errors`: Thất bại                  |
| 2   | `numFound`      | Số bản ghi tìm thấy theo điều kiện lọc                                       |
| 3   | `created_since` | Thời điểm bắt đầu thực tế của điều kiện tạo sau khi hệ thống chuẩn hóa       |
| 4   | `created_to`    | Thời điểm kết thúc thực tế của điều kiện tạo sau khi hệ thống chuẩn hóa      |
| 5   | `updated_since` | Thời điểm bắt đầu thực tế của điều kiện cập nhật sau khi hệ thống chuẩn hóa  |
| 6   | `updated_to`    | Thời điểm kết thúc thực tế của điều kiện cập nhật sau khi hệ thống chuẩn hóa |
| 7   | `contacts[]`    | Mảng dữ liệu danh sách khách hàng                                            |

Cấu trúc từng phần tử trong `contacts[]` gồm các trường điển hình sau:

* `id`: ID khách hàng
* `username`: Họ tên khách hàng
* `email`: Email chính
* `email2`: Email thứ 2
* `phone_no`: Số điện thoại thứ nhất
* `phone_no2`: Số điện thoại thứ 2
* `phone_no3`: Số điện thoại thứ 3
* `facebook`: Facebook ID
* `gender`: Giới tính
* `organization_id`: ID tổ chức
* `created_at`: Ngày tạo
* `updated_at`: Ngày cập nhật

**Ví dụ truy vấn**

```http
GET /api/v2/contacts?created_to=2026-07-31T00:00:00Z&page=1&count=50&order_by=created_at&order_type=DESC
```

Trong ví dụ trên, hệ thống sẽ tự chuẩn hóa khoảng thời gian và có thể trả về thêm các trường:

```json
{
  "created_since": "2026-06-30T00:00:00Z",
  }
  
Trước ngày 02/09/2026, endpoint GET {{domain}}/api/v1/contacts vẫn có thể hoạt động 
để hỗ trợ quá trình chuyển đổi. Tuy nhiên, endpoint này đã được đánh dấu là deprecated.
 Khuyến nghị chuyển sang GET {{domain}}/api/v2/contacts sớm nhất có thể. 
 Sau ngày 02/09/2026, API V1 sẽ ngừng hoạt động. Nếu tiếp tục gửi yêu cầu đến V1, 
 hệ thống sẽ tự động chuyển sang V2.
```

## Danh sách khách hàng (V1)

<mark style="color:blue;">`GET`</mark> `{{domain}/api/v1/contacts`

API này sẽ ngừng hoạt động sau ngày 02/09/2026. Vui lòng chuyển sang V2 để tiếp tục sử dụng.

#### Query Parameters

| Name           | Type               | Description                                                                      |
| -------------- | ------------------ | -------------------------------------------------------------------------------- |
| updated\_since | DateTime (ISO8601) | Thời điểm bắt đầu cập nhật. Định dạng: YYYY-MM-DDTHH:mm:ssZ                      |
| updated\_to    | DateTime (ISO8601) | Thời điểm kết thúc cập nhật. Định dạng: YYYY-MM-DDTHH:mm:ssZ                     |
| created\_since | DateTime (ISO8601) | Thời điểm bắt đầu tạo. Định dạng: YYYY-MM-DDTHH:mm:ssZ                           |
| created\_to    | DateTime (ISO8601) | Thời điểm kết thúc tạo. Định dạng: YYYY-MM-DDTHH:mm:ssZ                          |
| page           | Int                | Trang số                                                                         |
| count          | Int                | Số bản ghi trên trang (Tối đa 500)                                               |
| order\_by      | String             | Sắp xếp theo trường dữ liệu (mặc định created\_at)                               |
| order\_type    | String             | <p>Kiểu sắp xếp <br>DESC hoặc ASC (Giảm dần hoặc tăng dần) <br>Mặc định DESC</p> |

#### Headers

| Name                                   | Type   | Description                                                        |
| -------------------------------------- | ------ | ------------------------------------------------------------------ |
| \*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung ](/thong-tin-chung#phuong-thuc-xac-thuc) |

{% tabs %}
{% tab title="200: OK Kết quả thành công" %}
{% tabs %}
{% tab title="Kết quả điển hình" %}

```json
{
    "code": "ok",
    "numFound": 3,
    "contacts": [
        {
            "id": 165027003,
            "created_at": "2023-04-14T09:43:24Z",
            "updated_at": "2023-04-14T09:43:24Z",
            "phone_no": "0334992975",
            "username": "0334992975"
        }, 
    ...
  ]
}

```

{% endtab %}

{% tab title="Second Tab" %}

<table><thead><tr><th width="120">Stt</th><th width="159">Tên trường</th><th>Chú thích</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>Trạng thái thành công:<br>ok: Thành công<br>errors: Thất bại</td></tr><tr><td>2</td><td>numFound</td><td>Số bản ghi tìm thấy theo điều kiện lọc</td></tr><tr><td>3</td><td>contacts []</td><td><p>Mảng dữ liệu danh sách khách hàng. Gồm các object có cấu trúc như sau</p><ul><li><code>id</code>:  Id của khách hàng - Dùng ID này để truy xuất thông tin chi tiết, tham số    <code>{{contactId}}</code></li><li><code>username</code>: Họ tên khách hàng</li><li><code>created_at</code>: Ngày tạo</li><li><code>updated_at</code>: Ngày cập nhật</li><li><code>phone_no</code>: Số điện thoại thứ nhất của khách hàng</li></ul></td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## Chi tiết khách hàng

Dựa vào các hàm tạo mới hay cập nhật khách hàng hoặc danh sách khách hàng,  trả về các **{{contactId}}**. Nhà phát triển sử dụng hàm này để lấy thông tin chi tiết 1 khách hàng. API này bắt buộc phải có contactID mới thực hiện được

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2F9HisoB5s7CgEv2cgB93h%2FChitietLienhe.png?alt=media&amp;token=773080e3-cbd4-427e-a365-8e8cf10f6b6c" alt=""><figcaption></figcaption></figure>

## Chi tiết khách hàng

<mark style="color:blue;">`GET`</mark> `{{domain}/api/v1/contacts/{{contactId}}`

#### Headers

| Name                                   | Type   | Description                                                        |
| -------------------------------------- | ------ | ------------------------------------------------------------------ |
| \*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung ](/thong-tin-chung#phuong-thuc-xac-thuc) |

{% tabs %}
{% tab title="200: OK Thành công" %}
{% tabs %}
{% tab title="Kết quả điển hình" %}

```
{
    "code": "ok",
    "contact": {
        "id": 124921946,
        "username": "Nguyễn Văn Nam",
        "email": "demoapi@gmail.com",
        "email2": null,
        "phone_no": "0646546546546",
        "phone_no2": "09887456123",
        "phone_no3": null,
        "facebook": null,
        "gender": 1,
        "organization_id": 246080,
        "address": null,
        "city_id": null,
        "district_id": null,
        "created_at": "2021-10-30 00:16:04",
        "updated_at": "2023-04-24 17:56:13",
        "role_id": 3,
        "campaign_handler_id": null,
        "take_phone_at": "2022-04-12 14:30:00",
        "take_email_at": "2023-04-24 17:55:56",
        "custom_fields": [
                      {
                "id": 7492,
                "lable": "GIỚI TÍNH",
                "type": "Single drop-down list",
                "value": "33213"
            },
            {
                "id": 7584,
                "lable": "Tên trên QLBH",
                "type": "Text",
                "value": "AB"
            }
            ....           
          
        ],
        "organization": {
            "organization_id": 246080,
            "organization_domain": "323232",
            "organization_name": "sấ"
        }
    }
}
ta
```

{% endtab %}

{% tab title="Cấu trúc dữ liệu" %}

<table><thead><tr><th width="94">STT</th><th width="172">Tên trường</th><th>Ý nghĩa</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>Trạng thái <br>ok: Thành công<br>error: Lỗi</td></tr><tr><td>2</td><td>contact</td><td>Đối tượng thông tin khách hàng khách hàng  <br>(xem chi tiết ở bảng dưới) </td></tr></tbody></table>

Chi tiết đối tượng thông tin khách hàng (object)&#x20;

<table><thead><tr><th width="86">STT</th><th width="157">Tên trường</th><th>Ý nghĩa</th></tr></thead><tbody><tr><td>1</td><td>id</td><td>ID khách hàng</td></tr><tr><td>2</td><td>username</td><td>Họ tên khách hàng</td></tr><tr><td>3</td><td>email</td><td>Email </td></tr><tr><td>4</td><td>email2</td><td>Email 2</td></tr><tr><td>5</td><td>phone_no</td><td>Số điện thoại</td></tr><tr><td>6</td><td>phone_no2</td><td>Số điện thoại thứ 2</td></tr><tr><td>7</td><td>phone_no3</td><td>Số điện thoại 3</td></tr><tr><td>8</td><td>gender</td><td>Giới tính (0: Nam, 1 Nữ, 2: Không xác định)</td></tr><tr><td>9</td><td>organization_id</td><td>ID tổ chức </td></tr><tr><td>10</td><td>address</td><td>Địa chỉ</td></tr><tr><td>11</td><td>city_id</td><td>ID tỉnh/thành phố</td></tr><tr><td>12</td><td>district_id</td><td>ID huyện/Quận</td></tr><tr><td>13</td><td>created_at</td><td>Ngày tạo</td></tr><tr><td>14</td><td>updated_at</td><td>Ngày cập nhật</td></tr><tr><td>15</td><td>take_phone_at</td><td>Thời điểm thu thập số điện thoại</td></tr><tr><td>16</td><td>take_email_at</td><td>Thời điểm thu thập được email</td></tr><tr><td>17</td><td>custom_fields</td><td>Thông tin trường động (xem thêm ở <a data-mention href="/thong-tin-chung/truong-dong-custom-fields">Trường động (Custom fields)</a>)</td></tr><tr><td>18</td><td>organization</td><td>Tổ chức </td></tr><tr><td>19</td><td>zalo_id</td><td>Zalo ID</td></tr><tr><td>20</td><td>zalo_followers</td><td>Mảng dữ liệu object các Zalo Oa mà khách đang theo dõi nếu Zalo_id có giá trị.<br>Trong đó: <br>- oa_name: Tên Zalo OA <br>- oa_id:  ID OA,<br>- active: Trạng thái tích hợp của OA (1: Đang kích hoạt, 0. Ngừng kích hoạt)<br>- follow_status: Trạng thái follow của khách ( 1: Đang follow, null / 0: Không follow hoặc đã hủy) <br>-  updated_at: Ngày cập nhật mới nhất  </td></tr><tr><td>21</td><td>facebook</td><td>ID facebook </td></tr><tr><td>22</td><td>psid</td><td>Mảng dữ liệu object các Facebook Page khách hàng đang theo dõi nếu trường facebook có giá trị. Trong đó<br>- page_id: ID của page<br>- psid: ID của khách trên page </td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## Tìm khách hàng theo số điện thoại

Trong trường hợp cần tìm 1 khách hàng đã tồn tại hay chưa sử dụng API dưới đây, hệ thống sẽ trả về thông tin cơ bản của khách hàng.

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2Fbwf1BpPxTsfey2aKilAy%2Fpho.png?alt=media&amp;token=d49ba920-e227-4ec1-9a1e-698f8b701821" alt=""><figcaption><p>(Mẫu Postman tham khảo)</p></figcaption></figure>

## Tìm khách hàng theo số điện thoại

<mark style="color:blue;">`GET`</mark> `{{domain}/api/v1/api/v1/contactsByPhone`

Sử dụng parametter phoneNo để tìm khách hàng (Xem ảnh mô tả)

#### Query Parameters

| Name                                      | Type   | Description                                |
| ----------------------------------------- | ------ | ------------------------------------------ |
| phoneNo<mark style="color:red;">\*</mark> | String | Số điện thoại của khách hàng (Dạng 0XXXXX) |

{% tabs %}
{% tab title="200: OK Kết quả thành công" %}
{% tabs %}
{% tab title="Kết quả điển hình" %}

<pre class="language-json"><code class="lang-json">{
    "code": "ok",
    "contact": {
        "username": "A **",
        "id": <a data-footnote-ref href="#user-content-fn-3">63150747</a>,
        "email": "abc123@gmail.com",
        "phone_no": "09839**",
        "phone_no2": "0555****",
        "phone_no3": null,
        "email2": "****",
        "facebook": "546869858829726_2012787322172363",
        "gender": null,
        "organization_id": null,
        "created_at": "2020-01-17 10:12:18",
        "updated_at": "2023-06-24 16:54:10"
    }
}
</code></pre>

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="404: Not Found Không tìm thấy dữ liệu" %}
{% tabs %}
{% tab title="Kết quả điển hình" %}

```
{ "code": "errors", "message": "Not found user" }
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

[^1]: ID này dùng để thực hiện các tác vụ liên quan đến khách hàng này.\
    Vd: Cập nhật thông tin cá nhân, Tạo phiếu ghi cho khách hàng

[^2]: ID khách hàng có email trùng khớp đang hiện hữu trên hệ thống

[^3]:


# Thông tin tỉnh/huyện/xã

Api cung cấp ID tỉnh/thành phố, Quận/Huyện, Phường Xã hỗ trợ cập nhật thông tin khách hàng và phân loại theo tỉnh thành. Đối với phần Phường/Xã sẽ áp dụng thông tin theo chính quyền 2 cấp (Tỉnh/Xã)

Trong trường hợp cần gán địa chỉ khách hàng và phân cấp Tỉnh/Huyện thì sử dụng các api dưới đây để đồng bộ danh bạ tỉnh/thành, quận/huyện về ứng dụng.

{% hint style="info" %}
Dữ liệu tỉnh/thành phố, quận/huyện, xã/phường chỉ áp dụng cho các địa phương ở Việt Nam&#x20;
{% endhint %}

## Lấy danh sách tỉnh/thành phố

Dữ liệu đã được cập nhật trạng thái chính quyền 2 cấp đối với các tỉnh được giữ nguyên tên và tỉnh được sát nhập sẽ có thêm trạng thái chỉ thị.

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FOVbRgqwTxCvAnwvVCRjn%2Fcity_all.png?alt=media&amp;token=0ae65752-62c2-418d-8650-35d7be477eae" alt=""><figcaption><p>Mô phỏng dữ liệu tỉnh thành từ POSTMAN</p></figcaption></figure>

## Lấy danh sách tỉnh/thành phố&#x20;

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/cities`

#### Headers

| Name                                     | Type   | Description                                                        |
| ---------------------------------------- | ------ | ------------------------------------------------------------------ |
| \*\*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung ](/thong-tin-chung#phuong-thuc-xac-thuc) |

{% tabs %}
{% tab title="200: OK Thành công" %}
{% tabs %}
{% tab title="Kết quả điển hình" %}

```json
{
    "code": "ok",
    "data": [
        {
            "id": "01",
            "name": "Thành phố Hà Nội",
            "type": "Thành phố Trung ương",
            "status": 1
        },
        {
            "id": "02",
            "name": "Tỉnh Hà Giang",
            "type": "Tỉnh",
            "status": 0
        },
....
```

{% endtab %}

{% tab title="Cấu trúc thông tin" %}

<table><thead><tr><th width="83">STT</th><th width="140">Trường dữ liệu</th><th>Chú thích</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>Trạng thái yêu cầu</td></tr><tr><td>2</td><td>numFound</td><td>Số lượng bản ghi tìm thấy</td></tr><tr><td>3</td><td>data</td><td><p>Mảng dữ liệu chứa các đối tượng thông tin từng tỉnh thành có cấu trúc<br>- <code>id</code>: ID tỉnh thành, tương ứng với <strong><code>city_id</code></strong> khi tạo mới/cập nhật khách hàng hoặc lấy chi tiết các huyện/quận của 1 tỉnh<br>- <code>name</code>: Tên thành phố/Tỉnh<br>- <code>type</code>: Phân loại cấp thành phố/tỉnh</p><p>- <code>status</code>: Trạng thái sử dụng trong chính quyền 2 cấp: 0 ngưng sử dụng, 1: Đang sử dụng </p><p></p></td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="400: Bad Request " %}

{% endtab %}
{% endtabs %}

## Lấy danh sách quận/huyện&#x20;

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FqH9H6O1SYqw75siHNE1v%2Fcity_district.png?alt=media&amp;token=aaa78dbf-e377-4956-a793-ad4c67ee9bde" alt=""><figcaption><p>Chi tiết các quận/huyện theo city_id</p></figcaption></figure>

## Danh sách quận/huyện theo ID của tỉnh/thành phố

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/districts`

#### Query Parameters

| Name                                       | Type   | Description                                       |
| ------------------------------------------ | ------ | ------------------------------------------------- |
| city\_id<mark style="color:red;">\*</mark> | String | ID của tỉnh/thành phố dựa theo api Danh sách tỉnh |

#### Headers

| Name                                   | Type   | Description                                                        |
| -------------------------------------- | ------ | ------------------------------------------------------------------ |
| \*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung ](/thong-tin-chung#phuong-thuc-xac-thuc) |
|                                        |        |                                                                    |

{% tabs %}
{% tab title="200: OK Thành công" %}
{% tabs %}
{% tab title="Kết quả điển hình" %}

```
{
    "code": "ok",
    "numFound": 30,
    "data": [
        {
            "id": "001",
            "name": "Quận Ba Đình",
            "type": "Quận",
            "city_id": "01"
        },
        {
            "id": "002",
            "name": "Quận Hoàn Kiếm",
            "type": "Quận",
            "city_id": "01"
        },
        ....
        ]
}

```

{% endtab %}

{% tab title="Mô tả kết quả" %}

<table><thead><tr><th width="106">STT</th><th width="179">Trường thông tin</th><th>Chú thích</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>Trạng thái yêu cầu</td></tr><tr><td>2</td><td>numFound</td><td>Số lượng bản ghi tìm thấy </td></tr><tr><td>3</td><td>data</td><td><p>Mảng dữ liệu quận huyện  có cấu trúc</p><ul><li><code>id</code>: ID huyện/quận sẽ tương ứng với <strong><code>district_id</code></strong> khi tạo/cập nhật khách hàng và lấy thông tin khách hàng về</li><li><code>name</code>: Tên huyện/quận</li><li><code>type</code>: Kiểu quận hoặc huyện</li><li><code>city_id</code>: ID của thành phố</li></ul></td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="422: Unprocessable Entity Lỗi không cung cấp param city\_id" %}

```
{
    "code": "errors",
    "message": "Invalid city_id params"
}
```

{% endtab %}
{% endtabs %}

## Danh sách xã theo tỉnh (Xã theo cơ chế chính quyền 2 cấp)

Danh sách các xã theo city\_id  của tỉnh/thành phố có status=1 (Tỉnh sau sát nhập) dựa trên API Tỉnh/thành phố ở trên

&#x20;<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/wards`

| Name                                       | Type   | Description                                       |
| ------------------------------------------ | ------ | ------------------------------------------------- |
| city\_id<mark style="color:red;">\*</mark> | String | ID của tỉnh/thành phố dựa theo api Danh sách tỉnh |

#### Headers

| Name                                   | Type   | Description                                                        |
| -------------------------------------- | ------ | ------------------------------------------------------------------ |
| \*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung ](/thong-tin-chung#phuong-thuc-xac-thuc) |
|                                        |        |                                                                    |

Response:&#x20;

{% tabs %}
{% tab title="200: Thành công" %}
Kết quả điển hình ( payload là:  city\_id=34)&#x20;

{% tabs %}
{% tab title="Kết quả điển hình" %}

```json
{
    "code": "ok",
    "numFound": 104,
    "data": [
        {
            "id": "13279",
            "name": "Xã Vũ Tiên",
            "city_id": "33"
        },
        {
            "id": "13264",
            "name": "Xã Thư Vũ",
            "city_id": "33"
        },
        {
            "id": "13246",
            "name": "Xã Tân Thuận",
            "city_id": "33"
        },
...
```

{% endtab %}

{% tab title="Mô tả kết quả" %}

<table><thead><tr><th width="106">STT</th><th width="179">Trường thông tin</th><th>Chú thích</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>Trạng thái yêu cầu</td></tr><tr><td>2</td><td>numFound</td><td>Số lượng bản ghi tìm thấy </td></tr><tr><td>3</td><td>data</td><td><p>Mảng dữ liệu xã phường  có cấu trúc</p><ul><li><code>id</code>: ID Xã/phường sẽ tương ứng với <code>ward_id</code>  khi tạo/cập nhật khách hàng và lấy thông tin khách hàng về</li><li><code>name</code>: Tên xã phường</li><li><code>city_id</code>: ID của thành phố/Tỉnh</li></ul></td></tr></tbody></table>
{% endtab %}
{% endtabs %}

{% endtab %}

{% tab title="422: Lỗi thiếu thông tin" %}
Kết quả điển hình:

```json
{
    "code": "errors",
    "message": "Invalid city_id params"
}
```

{% endtab %}
{% endtabs %}


# Chat

Api lịch sử LiveChat, Messenger, Zalo

Tài liệu lấy dữ liệu lịch sử chat trên hệ thống CareSoft

{% hint style="info" %}
Lưu ý: Trong trường hợp không truyền tham số `conversation_type` thì hệ thống chỉ lọc lịch sử Livechat &#x20;
{% endhint %}

<table><thead><tr><th width="82.33333333333331">STT</th><th width="213">Tên trường</th><th>Chú thích</th></tr></thead><tbody><tr><td>1</td><td>ticket_id</td><td>ID phiếu ghi</td></tr><tr><td>2</td><td>ticket_no</td><td>Số phiếu ghi</td></tr><tr><td>3</td><td>customer_id</td><td>ID khách hàng, tương ứng với {{contactId}} khi cần truy xuất thông tin chi tiết của khách</td></tr><tr><td>4</td><td>cus_email</td><td>Email của khách</td></tr><tr><td>5</td><td>cus_name</td><td>Họ tên khách hàng</td></tr><tr><td>6</td><td>cus_phone</td><td>Số điện thoại của khách</td></tr><tr><td>7</td><td>meet_time</td><td>Thời điểm khết nối</td></tr><tr><td>8</td><td>waitTime</td><td>Thời gian chờ</td></tr><tr><td>9</td><td>answer_time</td><td>Thời gian trả lời</td></tr><tr><td>10</td><td>ring_time</td><td>Thời gian chờ rung chuông</td></tr><tr><td>11</td><td>chat_status</td><td>Trạng thái chat LBL_CHAT_STATUS_MISS: Nhỡ<br><br>LBL_CHAT_STATUS_MEET: Gặp</td></tr><tr><td>12</td><td>conversation_id</td><td>ID phiên chat</td></tr><tr><td>13</td><td>landing_page</td><td>Trang web chứa chat widget (Đối với live chate)</td></tr><tr><td>14</td><td>referrer</td><td>Trang web trước đó link tới landing page</td></tr><tr><td>15</td><td>is_trigger</td><td>Trạng thái kích hoạt trigger: LBL_CHAT_CUSTOMER_REQUEST_TRIGGER LBL_CHAT_CUSTOMER_REQUEST_NORMAL</td></tr><tr><td>16</td><td>facebook_page_id</td><td>Facebook page ID</td></tr><tr><td>17</td><td>start_time</td><td>Thời điểm bắt đầu</td></tr><tr><td>18</td><td>end_time</td><td>Thời điểm kết thúc</td></tr><tr><td>19</td><td>chat_duration</td><td>Thời lượng chat</td></tr><tr><td>20</td><td>agent_email</td><td>Email của chuyên viên</td></tr><tr><td>21</td><td>agent_name</td><td>Tên chuyên viên</td></tr><tr><td>22</td><td>group_name</td><td>Bộ phận của chuyên viên</td></tr><tr><td>23</td><td>service_id</td><td>ID Dịch vụ</td></tr></tbody></table>

## Lịch sử chat

## Danh sách lịch sử chat

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/chats`

#### Query Parameters

| Name               | Type               | Description                                                                                       |
| ------------------ | ------------------ | ------------------------------------------------------------------------------------------------- |
| start\_time\_since | DateTime (ISO8601) | <p>Thời gian bắt đầu cuộc gọi từ <br>Kiểu dữ liệu (yyyy-MM-ddTHH:mm:ssZ)</p>                      |
| start\_time\_to    | DateTime (ISO8601) | <p>Thời gian bắt đầu cuộc gọi từ <br>Kiểu dữ liệu (yyyy-MM-ddTHH:mm:ssZ)</p>                      |
| assignees          | array\[int]        | Mảng ID nhân viên xử lý, xem thêm ở [Chuyên viên](/danh-muc/restful-api-cua-caresoft/chuyen-vien) |
| groups             | array\[int]        | Mảng ID bộ phận xem thêm ở [Bộ phận](/danh-muc/restful-api-cua-caresoft/bo-phan)                  |
| ticket\_id         | Int                | ID phiếu ghi                                                                                      |
| conversation\_type | Int                | <p>Loại chat có 3 tham số<br>0: Livechat<br>1:  Inbox Facebook<br>3: Zalo<br>Mặc định: 0</p>      |
| chat\_status       | Int                | <p>Tình trạng hội thoại: <br>0: Nhỡ<br>1: Gặp</p>                                                 |
| chat\_type         | Int                | <p>Loại hội thoại Có 2 giá trị<br>0: Hội thoại đến<br>1: Hội thoại chủ động ra</p>                |
| end\_time\_to      | DateTime (ISO8601) | <p>Thời gian bắt đầu cuộc gọi từ <br>Kiểu dữ liệu (yyyy-MM-ddTHH:mm:ssZ)</p>                      |
| end\_time\_since   | DateTime (ISO8601) | <p>Thời gian bắt đầu cuộc gọi từ <br>Kiểu dữ liệu (yyyy-MM-ddTHH:mm:ssZ)</p>                      |
| customers          | array\[int]        | Mảng ID danh sách khách hàng                                                                      |
| services           | Int                | ID dịch vụ                                                                                        |
| page               | Int                | Trang                                                                                             |
| count              | Int                | Số bản ghi trên /trang (Luôn kèm theo param `page`) Tối đa 500                                    |

#### Headers

| Name                                   | Type   | Description                                  |
| -------------------------------------- | ------ | -------------------------------------------- |
| \*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung](/thong-tin-chung) |

{% tabs %}
{% tab title="200: OK Thành công" %}
{% tabs %}
{% tab title="Kết quả điển hình" %}

```json

{
    "code": "OK",
    "numFound": 34,
    "chats": [
        {
            "ticket_id": 387229101,
            "ticket_no": 7415,
            "customer_id": 165644057,
            "group_name": "AGENT",
            "conversation_id": "20230422094830-AIVGTIVI-503996",
            "cus_email": "",
            "cus_name": "cstest",
            "cus_phone": "",
            "start_time": "2023-04-22 09:48:30",
            "end_time": "2023-04-22 09:49:10",
            "chat_duration": 39,
            "agent_email": "dungntt1110@gmail.com",
            "agent_name": "dungntt",
            "ring_time": "2023-04-22 09:48:30",
            "meet_time": "2023-04-22 09:48:39",
            "waitTime": "00:00:08",
            "answer_time": "00:00:31",
            "chat_status": "LBL_CHAT_STATUS_MEET",
            "landing_page": null,
            "referrer": null,
            "is_trigger": "LBL_CHAT_CUSTOMER_REQUEST_NORMAL",
            "facebook_page_id": null,
            "service_id": 60047005
        },
        ...
        ]
}

```

{% endtab %}

{% tab title="Mô tả kết quả" %}

<table><thead><tr><th width="87">Stt</th><th width="153">Tên trường</th><th>Chú thích</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>Trạng thái thành công: <br>ok: Thành công errors: Thất bại</td></tr><tr><td>2</td><td>numFound</td><td>Số bản ghi tìm thấy theo điều kiện lọc</td></tr><tr><td>3</td><td>chats []</td><td>Mảng dữ liệu danh sách lịch sử chat (xem phía dưới)</td></tr></tbody></table>

Chi tiết 1 đối tượng Chat trong mảng `chats`

<table><thead><tr><th width="77">STT</th><th width="163">Tên trường</th><th>Chú thích</th></tr></thead><tbody><tr><td>1</td><td>ticket_id</td><td>ID phiếu ghi</td></tr><tr><td>2</td><td>ticket_no</td><td>Số phiếu ghi</td></tr><tr><td>3</td><td>customer_id</td><td>ID khách hàng, tương ứng với {{contactId}} khi cần truy xuất  thông tin chi tiết của khách</td></tr><tr><td>4</td><td>cus_email</td><td>Email của khách</td></tr><tr><td>5</td><td>cus_name</td><td>Họ tên khách hàng</td></tr><tr><td>6</td><td>cus_phone</td><td>Số điện thoại của khách</td></tr><tr><td>7</td><td>meet_time</td><td>Thời điểm khết nối</td></tr><tr><td>8</td><td>waitTime</td><td>Thời gian chờ</td></tr><tr><td>9</td><td>answer_time</td><td>Thời gian trả lời</td></tr><tr><td>10</td><td>ring_time</td><td>Thời gian chờ rung chuông</td></tr><tr><td>11</td><td>chat_status</td><td><p>Trạng thái chat<br>LBL_CHAT_STATUS_MISS:  Nhỡ</p><p>LBL_CHAT_STATUS_MEET: Gặp</p></td></tr><tr><td>12</td><td>conversation_id</td><td>ID phiên chat</td></tr><tr><td>13</td><td>landing_page</td><td>Trang web chứa chat widget (Đối với live chate)</td></tr><tr><td>14</td><td>referrer</td><td>Trang web trước đó link tới landing page</td></tr><tr><td>15</td><td>is_trigger</td><td>Trạng thái kích hoạt trigger:<br>LBL_CHAT_CUSTOMER_REQUEST_TRIGGER LBL_CHAT_CUSTOMER_REQUEST_NORMAL</td></tr><tr><td>16</td><td>facebook_page_id</td><td>Facebook page ID</td></tr><tr><td>17</td><td>start_time</td><td>Thời điểm bắt đầu</td></tr><tr><td>18</td><td>end_time</td><td>Thời điểm kết thúc</td></tr><tr><td>19</td><td>chat_duration</td><td>Thời lượng chat</td></tr><tr><td>20</td><td>agent_email</td><td>Email của chuyên viên</td></tr><tr><td>21</td><td>agent_name</td><td>Tên chuyên viên</td></tr><tr><td>22</td><td>group_name</td><td>Bộ phận của chuyên viên</td></tr><tr><td>23</td><td>service_id</td><td>ID  Dịch vụ</td></tr></tbody></table>

Để lấy nội dung chat vui lòng truy xuất Chi tiết phiếu ghi đi kèm để lấy thông tin&#x20;
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="403: Forbidden " %}

{% endtab %}

{% tab title="400: Bad Request " %}

{% endtab %}

{% tab title="500: Internal Server Error " %}

{% endtab %}
{% endtabs %}


# Danh sách tin nhắn chat

API lấy danh sách tin nhắn chat theo từng kênh

## Lấy chi tiết danh sách tin nhắn chat

Từ lịch sử Chat nhà phát triển có thể lấy thêm nội dung chat chi tiết theo API dưới đây.&#x20;

{% hint style="info" %}
Lưu ý: API bị giới hạn lọc trong khoảng thời gian 31 ngày, tham số `start_time_since` là tham số bắt buộc, `start_time_to` không truyền  sẽ lấy ngày hiện tại. `start_time_since` và `start_time_to` không quá 30 ngày.&#x20;

Trường hợp không truyền tham số `conversation_type`. Hệ thống mặc định là lịch sử tin nhắn live chat (tương đương conversation\_type=0)
{% endhint %}

**Bảng mô tả các tham số trả về từ CareSoft**&#x20;

<table><thead><tr><th width="106.33333333333331">Stt</th><th>Trường dữ liệu</th><th>Mô tả</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>Trạng thái <br>ok: Thành công<br>errors: Thất bại</td></tr><tr><td>2</td><td>numFound</td><td>Số lượng bản ghi tìm thấy</td></tr><tr><td>3</td><td>chats</td><td>Mảng danh sách các tin nhắn trao đổi thỏa mãn điều kiện tìm kiếm</td></tr></tbody></table>

Bảng mô tả chi tiết dữ liệu trong mảng "**chats**"

<table><thead><tr><th width="106">Stt</th><th width="207">Trường dữ liệu</th><th>Mô tả</th></tr></thead><tbody><tr><td>1</td><td>conversation_id</td><td>ID phiên chat</td></tr><tr><td>2</td><td>conversation_type</td><td>Loại chat <br>0: Live Chat<br>1: Messenger và Instagram<br>3: Zalo</td></tr><tr><td>3</td><td>msg_id</td><td>Message ID</td></tr><tr><td>4</td><td>content</td><td>Nội dung chat. Nội dung này là dạng text thuần hoặc object JSON phụ thuộc vào trường "type" phía dưới</td></tr><tr><td>5</td><td>type</td><td><strong>Kiểu nội dung</strong><br>1. Văn bản<br>2. Object json file đính kèm<br>3. Văn bản do hệ thống sinh ra<br>4. Object Json template (template_type: buttons, generic, reply_to, transaction_order, promotion)<br><strong>Lưu ý:</strong> <em>Kiểu nội dung sẽ quyết định phần content là JSON OBJECT hoặc text thuần</em> </td></tr><tr><td>6</td><td>time</td><td>Thời điểm phát sinh đoạn tin chat</td></tr><tr><td>7</td><td>message_index</td><td>Thứ tự đoạn chat trong hội thoại. Một phiên chat (conversation) có nhiều mẩu tin chat qua lại các mẩu tin này sẽ đánh index với tham số message_index từ nhỏ đến lớn để biết được time_line của phiên chat và trình tự các mẩu tin chat) </td></tr><tr><td>8</td><td>service_id</td><td>ID dịch vụ của phiên chat</td></tr><tr><td>9</td><td>start_time</td><td>Thời điểm bắt đầu phiên chat </td></tr><tr><td>10</td><td>sender_agent_name</td><td>Tên chuyên viên gửi tin (Null là khách gửi hoặc hệ thống gửi / Cần ghép với type để loại bỏ tin hệ thống)</td></tr><tr><td>11</td><td>sender_agent_id</td><td>ID chuyên viên gửi tin (Null là khách gửi hoặc hệ thống gửi / Cần ghép với type để loại bỏ tin hệ thống)</td></tr><tr><td>12</td><td>sender_visitor_name</td><td>Tên khách gửi tin (Null là chuyên viên hoặc hệ thống gửi / Cần ghép với type để loại bỏ tin hệ thống) </td></tr><tr><td>13</td><td>sender_visitor_id</td><td>Id  khách gửi tin (Null là chuyên viên hoặc hệ thống gửi / Cần ghép với type để loại bỏ tin hệ thống) </td></tr><tr><td>14</td><td>last_agent_user_id</td><td>ID của chuyên viên xử lý phiên chat</td></tr><tr><td>15</td><td>ticket_id</td><td>ID phiếu ghi liên quan</td></tr><tr><td>16</td><td>requester_id</td><td>ID Khách hàng hình thành trên hệ thống CareSoft</td></tr><tr><td>17</td><td>oa_name (*)</td><td>Zalo OA của tin nhắn. Chỉ có khi conversation_type=3</td></tr><tr><td>18</td><td>oa_id (*)</td><td>Zalo OA ID của tin nhắn  Chỉ có khi conversation_type=3</td></tr><tr><td>19</td><td>page_name (**)</td><td>Tên trang Facebook/Instagram khách chat vào. Chỉ có khi conversation_type=1</td></tr><tr><td>20</td><td>page_id  (**)</td><td>ID trang Facebook/Instagram khách chat vào. Chỉ có khi conversation_type=1</td></tr><tr><td>21</td><td>platform  (**)</td><td>Nền tảng chat vào. Chỉ có khi conversation_type=1<br>Có các giá trị:<br>- MESSENGER: Tin nhắn Inbox Facebook<br>- INSTAGRAM: Tin nhắn Instagram </td></tr></tbody></table>

*(\*)   Chỉ có khi conversation\_type=3*\
*(\*\*) Chỉ có khi conversation\_type=1*

**Cấu hình postman mô phỏng ví dụ**

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FZjsbD5Ee0ag23gmNhpgB%2Fimage.png?alt=media&amp;token=594a8427-fb51-4468-ae2e-79e573c5e7a0" alt=""><figcaption></figcaption></figure>

Mẫu dữ liệu trả về

```json
{
    "code": "ok",
    "numFound": 18,
    "chats": [
        {   "conversation_id": "20230822134203-ZGDMRWGB-77677",
            "id": 799734999,
            "msg_id": "20230822134203-ZGDMRWGB-77677;1692686523409",
            "message_index": 2,
            "content": "Admin đã thoát hội thoại",
            "time": "2023-08-22 13:55:19",
            "service_id": 62062484,
            "start_time": "2023-08-22 13:54:51",
            "sender_agent_name": null,
            "sender_agent_id": null,
            "sender_visitor_name": null,
            "sender_visitor_id": null,
            "last_agent_user_id": 124734559,
            "ticket_id": 421360514,
            "type": 3,
            "conversation_type": 3,
            "requester_id": 174137179,
            "oa_name": "CareSoft Test",
            "oa_id": "1600195475413752846"
            ...
        },
        ....
        ]
}
```

## API lấy danh sách chi tiết chat

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/chats/messages`

API lấy danh sách các đoạn tin chat chi tiết&#x20;

#### Query Parameters

| Name                                                 | Type               | Description                                                                                           |
| ---------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------- |
| start\_time\_since<mark style="color:red;">\*</mark> | DateTime (ISO8601) | <p>Thời gian bắt đầu phiên chat từ <br>Kiểu dữ liệu (yyyy-MM-ddTHH:mm:ssZ)</p>                        |
| start\_time\_to                                      | DateTime (ISO8601) | <p>Thời gian bắt đầu phiên chat tới <br>Kiểu dữ liệu (yyyy-MM-ddTHH:mm:ssZ)</p>                       |
| conversation\_type                                   | Int                | <p>Loại tin nhắn.<br>0: Live Chat (Mặc định) <br>1: Messenger/Instagram<br>3: Zalo<br></p>            |
| conversation\_id                                     | String             | Id phiên chat. Trong trường hợp trường này có giá trị thì hệ thống sẽ bỏ qua param conversation\_type |
| requester\_id                                        | Int                | ID khách hàng                                                                                         |
| last\_agent\_user\_id                                | Int                | Id chuyên viên xử lý phiên chat                                                                       |
| services                                             | Int                | ID dịch vụ                                                                                            |
| count                                                | Int                | Số bản ghi trên 1 lần request (tối đa 500), Mặc định 50                                               |
| page                                                 | Int                | Số trang dữ liệu request (Mặc định 1)                                                                 |

#### Headers

| Name                                   | Type   | Description                                                        |
| -------------------------------------- | ------ | ------------------------------------------------------------------ |
| \*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung ](/thong-tin-chung#phuong-thuc-xac-thuc) |

{% tabs %}
{% tab title="200: OK Thành công " %}
{% code title="Mẫu phản hồi loại Facebook" %}

```
{
    "code": "ok",
    "numFound": 31,
    "chats": [
        {
            "conversation_id": "20230822091139-ZGDMRWGB-54470",
            "id": 800076376,
            "msg_id": "20230822091139-ZGDMRWGB-54470;1692705699685",
            "message_index": 1000,
            "content": "Vui lòng đánh giá chúng tôi nhé",
            "time": "2023-08-22 19:01:40",
            "service_id": 61050371,
            "start_time": "2023-08-22 09:11:39",
            "sender_agent_name": "Facebook Survey: Mời bạn đáng giá",
            "sender_agent_id": -2,
            "sender_visitor_name": null,
            "sender_visitor_id": null,
            "last_agent_user_id": 139409084,
            "ticket_id": 421299776,
            "type": 1,
            "conversation_type": 1,
            "requester_id": 175278174,
            "page_name": "Lien xinh",
            "page_id": "100244086089719",
            "platform": "MESSENGER"
        },
        ....
        ]
    }
```

{% endcode %}

Mẫu phản hồi Live chat

```json
{
    "code": "ok",
    "numFound": 11,
    "chats": [
        {
            "conversation_id": "20230822165535-ZGDMRWGB-96844",
            "id": 799984961,
            "msg_id": "20230822165535-ZGDMRWGB-96844;1692698135525",
            "message_index": 3,
            "content": "đâsd đã thoát hội thoại",
            "time": "2023-08-22 17:30:19",
            "service_id": 60043410,
            "start_time": "2023-08-22 16:55:36",
            "sender_agent_name": null,
            "sender_agent_id": null,
            "sender_visitor_name": null,
            "sender_visitor_id": null,
            "last_agent_user_id": 124734559,
            "ticket_id": 421443464,
            "type": 3,
            "conversation_type": 0,
            "requester_id": 176584437
        },
        ....
        ]
    }
```

Mẫu phản hồi Zalo

```json
{
    "code": "ok",
    "numFound": 18,
    "chats": [
        {
            "conversation_id": "20230822134203-ZGDMRWGB-77677",
            "id": 799734999,
            "msg_id": "20230822134203-ZGDMRWGB-77677;1692686523409",
            "message_index": 2,
            "content": "Admin đã thoát hội thoại",
            "time": "2023-08-22 13:55:19",
            "service_id": 62062484,
            "start_time": "2023-08-22 13:54:51",
            "sender_agent_name": null,
            "sender_agent_id": null,
            "sender_visitor_name": null,
            "sender_visitor_id": null,
            "last_agent_user_id": 124734559,
            "ticket_id": 421360514,
            "type": 3,
            "conversation_type": 3,
            "requester_id": 174137179,
            "oa_name": "CareSoft Test",
            "oa_id": "1600195475413752846"
        },
        ....
        ]
    }
```

{% endtab %}

{% tab title="400: Bad Request Lỗi" %}
Lỗi ngày tháng truyền vào quá 31 ngày

{% code overflow="wrap" %}

```json
{
    "code": "errors",
    "message": "Request required [start_time_since/start_time_to] between 30 days "
}
```

{% endcode %}

Lỗi không tìm thấy  last\_agent\_user\_id từ param truyền vào&#x20;

```json
{
    "code": "errors",
    "message": "Not found last_agent_user_id: 1121212 "
}
```

Lỗi không tìm thấy khách hàng từ param truyền vào&#x20;

```json
{
    "code": "errors",
    "message": "Not found requester_id: 1 "
}
```

{% endtab %}
{% endtabs %}


# Cuộc gọi

API lấy lịch sử cuộc gọi  điện thoại trên nền tảng CareSoft.

## Lịch sử cuộc gọi

Api  truy xuất lịch sử cuộc gọi  điện thoại trên nền tảng CareSoft.&#x20;

### Thông tin trường dữ liệu của cuộc gọi

<table><thead><tr><th width="102.33333333333331" data-type="number">Stt</th><th width="169">Tên trường</th><th width="142">Kiểu <select><option value="677a1bddfdbf41dc93c2e98d54dc768c" label="INT" color="blue"></option><option value="09e2cd7cb62c4ebb837ee7ace4f1365d" label="TEXT" color="blue"></option><option value="48baa45513d54325a42fd2d6bcb3d73b" label="DATETIME" color="blue"></option><option value="e9405356d62e428eaeda5e19696c5821" label="STRING" color="blue"></option><option value="5ed04b5dec8d48058d7a13b82608e28b" label="TIME" color="blue"></option><option value="423df29d3c0c40aaaa2e4e19994c90bd" label="URL" color="blue"></option></select></th><th></th></tr></thead><tbody><tr><td>1</td><td>call_id</td><td><span data-option="e9405356d62e428eaeda5e19696c5821">STRING</span></td><td>ID cuộc gọi, duy nhất trên toàn hệ thống</td></tr><tr><td>2</td><td>caller</td><td><span data-option="e9405356d62e428eaeda5e19696c5821">STRING</span></td><td>Người gọi</td></tr><tr><td>3</td><td>called</td><td><span data-option="e9405356d62e428eaeda5e19696c5821">STRING</span></td><td>Người nghe</td></tr><tr><td>4</td><td>user_id</td><td><span data-option="677a1bddfdbf41dc93c2e98d54dc768c">INT</span></td><td>ID chuyên viên</td></tr><tr><td>5</td><td>agent_id</td><td><span data-option="09e2cd7cb62c4ebb837ee7ace4f1365d">TEXT</span></td><td>Số IP phone của chuyên viên</td></tr><tr><td>6</td><td>group_id</td><td><span data-option="677a1bddfdbf41dc93c2e98d54dc768c">INT</span></td><td>Id của bộ phận của chuyên viên</td></tr><tr><td>7</td><td>call_type</td><td><span data-option="677a1bddfdbf41dc93c2e98d54dc768c">INT</span></td><td>Kiểu cuộc gọi có 2 giá trị 0 hoặc 1 <a data-footnote-ref href="#user-content-fn-1"> (?)</a></td></tr><tr><td>8</td><td>start_time</td><td><span data-option="48baa45513d54325a42fd2d6bcb3d73b">DATETIME</span></td><td>Thời điểm bắt đầu </td></tr><tr><td>9</td><td>end_time</td><td><span data-option="48baa45513d54325a42fd2d6bcb3d73b">DATETIME</span></td><td>Thời điểm kết thúc</td></tr><tr><td>10</td><td>call_status</td><td><span data-option="e9405356d62e428eaeda5e19696c5821">STRING</span></td><td><p>Tình trạng cuộc gọi  có 2 giá trị</p><p>miss, metAgent <a data-footnote-ref href="#user-content-fn-2"> (?)</a></p></td></tr><tr><td>11</td><td>wait_time</td><td><span data-option="5ed04b5dec8d48058d7a13b82608e28b">TIME</span></td><td>Thời gian chờ nhận cuộc gọi</td></tr><tr><td>12</td><td>hold_time</td><td><span data-option="5ed04b5dec8d48058d7a13b82608e28b">TIME</span></td><td>Thời gian giữ máy (khi chuyên viên bấm Hold) </td></tr><tr><td>13</td><td>talk_time</td><td><span data-option="5ed04b5dec8d48058d7a13b82608e28b">TIME</span></td><td>Thời giam đàm thoại </td></tr><tr><td>14</td><td>end_status</td><td><span data-option="677a1bddfdbf41dc93c2e98d54dc768c">INT</span></td><td>Trạng thái kết thúc, có 2 giá trị "cus", system" <a data-footnote-ref href="#user-content-fn-3">(?)</a></td></tr><tr><td>15</td><td>ticket_id</td><td><span data-option="677a1bddfdbf41dc93c2e98d54dc768c">INT</span></td><td>ID phiếu ghi</td></tr><tr><td>16</td><td>missed_reason</td><td><span data-option="e9405356d62e428eaeda5e19696c5821">STRING</span></td><td>Trạng thái nhỡ có 4 trạng thái (missed_customer , missed_agent_device , missed_agent_reject , missed_agent_timeout )  <a data-footnote-ref href="#user-content-fn-4">(?)</a><br>Khai thác trường dữ liệu này nếu trường "call_status" có giá trị là "miss"</td></tr><tr><td>17</td><td>last_agent_id</td><td><span data-option="677a1bddfdbf41dc93c2e98d54dc768c">INT</span></td><td>Chuyên viên cuối cùng nhận cuộc gọi <a data-footnote-ref href="#user-content-fn-5">(?)</a></td></tr><tr><td>18</td><td>path</td><td><span data-option="423df29d3c0c40aaaa2e4e19994c90bd">URL</span></td><td>Đường dẫn file ghi âm (streaming) <br><a data-footnote-ref href="#user-content-fn-6">(*) </a></td></tr><tr><td>19</td><td>path_download</td><td><span data-option="423df29d3c0c40aaaa2e4e19994c90bd">URL</span></td><td>Đường dẫn file ghi âm (dùng để tải về) <a data-footnote-ref href="#user-content-fn-6">(*) </a></td></tr><tr><td>20</td><td>service_id</td><td><span data-option="677a1bddfdbf41dc93c2e98d54dc768c">INT</span></td><td>Id <a href="/danh-muc/restful-api-cua-caresoft/dich-vu">dịch vụ</a> thoại trên CareSoft</td></tr><tr><td>21</td><td>last_user_id</td><td><span data-option="677a1bddfdbf41dc93c2e98d54dc768c">INT</span></td><td>ID chuyên viên cuối cùng nhận cuộc gọi</td></tr><tr><td>22</td><td>dtmf</td><td><span data-option="09e2cd7cb62c4ebb837ee7ace4f1365d">TEXT</span></td><td>Dữ liệu phím bấm của khách hàng</td></tr><tr><td>23</td><td>call_survey</td><td><span data-option="09e2cd7cb62c4ebb837ee7ace4f1365d">TEXT</span></td><td>Khảo sát khách hàng thông qua kênh thoại. Khi cấu hình theo khảo sát sau cuộc gọi thì sẽ phát ghi âm để khảo sát, KH đánh giá theo nội dung ghi âm bằng cách bấm phím. </td></tr><tr><td>24</td><td>call_survey_result</td><td><span data-option="09e2cd7cb62c4ebb837ee7ace4f1365d">TEXT</span></td><td>Dữ liệu kết quả khảo sát</td></tr></tbody></table>

#### Ví dụ minh họa lấy lịch sử cuộc gọi theo ID cuộc gọi.

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2F7uChdD5T2ytRSiYp3oiD%2FPostMan_ApiCall.png?alt=media&amp;token=8751994e-4da1-41ee-be51-2dba32ae31dd" alt=""><figcaption><p>Mẫu Postman điển hình  trong trường hợp này đang tìm lịch sử cuộc gọi có id "20221008233814-LSKMQKWP-43"</p></figcaption></figure>

#### Ví dụ minh họa lấy lịch sử cuộc gọi theo số điện thoại của khách của 1 chuyên viên

{% code title="Mẫu curl minh họa" %}

```powershell
curl --location \
--globoff 'https://api.caresoft.vn/{{domain}}/api/v1/calls?start_time_to=2022-10-11T10%3A00%3A00Z&phone=0868887835&agent_id=5000&start_time_since=2022-9-11T10%3A00%3A00Z' \
--header 'Authorization: Bearer {{apiToken}}'
```

{% endcode %}

{% hint style="info" %}
Mẫu curl trên tìm danh sách cuộc gọi  cho số máy 0868887835  của chuyên viên có iphone= 5000,  Có thời điểm bắt đầu gọi trong khoảng thời gian từ 2022-08-11 tới 2022-10-11
{% endhint %}

{% hint style="warning" %}
**Lưu ý:** Một thuật toán tối ưu lệnh tìm kiếm phiếu ghi sẽ được thực hiện theo mô hình sau

1. Khi gọi API không cung cấp khoảng ngày kết thúc (chỉ truyền ngày bắt đầu:  start\_time\_since hoặc end\_time\_since). Mà ngày bắt đầu trước  ngày hiện tại hơn 31 ngày thì hệ thống sẽ tự động chọn khoảng ngày kết thúc là ngày hiện tại và trả về kết quả trong 31 ngày tính từ ngày hiện tại.  Nếu ngày bắt đầu nhỏ hơn ngày hiện tại dưới 31 ngày thì hệ thống giữ nguyên ngày bắt đầu và tiến hành lọc dữ liệu theo tham số trên
2. Khi gọi API cung cấp khoảng ngày kết thúc (param: start\_time\_to hoặc end\_time\_to). Mà ngày kết thúc sau ngày bắt đầu quá 31 ngày thì hệ thống tự chọn lại khoảng ngày bắt đầu bằng ngày kết thúc - 31 ngày
3. Khi gọi API cung cấp cả hai tham số Bắt đầu và Kết thúc cách nhau không quá 31 ngày thì hệ thống lọc phiếu ghi theo giá trị truyền vào này và trả về kết quả tương ứng.
4. Trong trường hợp cặp điều kiện start\_time\_since  và end\_time\_since đều được cung cấp hệ thống sẽ ưu tiên xử lý theo điều kiện end\_time\_since&#x20;

&#x20;  *`(Nội dung sẽ Áp dụng từ 02/03/2024)`*&#x20;
{% endhint %}

## Api lấy lịch sử cuộc gọi&#x20;

<mark style="color:blue;">`GET`</mark> `{domain}/api/v1/calls`

**Lưu ý:** Trong trường hợp cần lấy thông tin cuộc gọi trượt qua nhánh IVR thì sử dụng parameter `call_type:3` để lọc dữ liệu.&#x20;

#### Query Parameters

<table><thead><tr><th width="249">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>start_time_since<a data-footnote-ref href="#user-content-fn-7"><sup><mark style="color:$danger;">(*)</mark></sup></a></td><td>DateTime (ISO8601)</td><td>Thời gian bắt đầu cuộc gọi từ <br>Kiểu dữ liệu (yyyy-MM-ddTHH:mm:ssZ)</td></tr><tr><td>start_time_to</td><td>DateTime (ISO8601)</td><td>Thời gian bắt đầu cuộc gọi tới<br>Kiểu dữ liệu (yyyy-MM-ddTHH:mm:ssZ)</td></tr><tr><td>call_id</td><td>String</td><td>ID cuộc gọi của caresoft</td></tr><tr><td>end_time_since</td><td>DateTime (ISO8601)</td><td>Thời gian kết thúc cuộc gọi từ <br>Kiểu dữ liệu (yyyy-MM-ddTHH:mm:ssZ)</td></tr><tr><td>end_time_to</td><td>DateTime (ISO8601)</td><td>Thời gian kết thúc cuộc gọi tới<br>Kiểu dữ liệu (yyyy-MM-ddTHH:mm:ssZ)</td></tr><tr><td>call_type</td><td>Int</td><td>Kiểu cuộc gọi có 3 giá trị 0 hoặc 1 hoặc 3 <a data-footnote-ref href="#user-content-fn-8"> (?)</a></td></tr><tr><td>call_status</td><td>String</td><td><p>Tình trạng cuộc gọi  có 2 giá trị</p><p>miss, metAgent <a data-footnote-ref href="#user-content-fn-2"> (?)</a></p></td></tr><tr><td>phone</td><td>String</td><td>Số điện thoại của khách hàng</td></tr><tr><td>page</td><td>Int</td><td>Trang số</td></tr><tr><td>count</td><td>Int</td><td>Số lượng bản ghi / trang (tối đa 500)</td></tr><tr><td>agent_id</td><td>Int</td><td>Số ipPhone của <a href="/danh-muc/restful-api-cua-caresoft/chuyen-vien">chuyên viên</a></td></tr><tr><td>order_by</td><td>String</td><td>Sắp xếp dữ liệu <a data-footnote-ref href="#user-content-fn-9">(?)</a></td></tr><tr><td>order_type</td><td>String</td><td>Kiểu sắp xếp. Là 1 trong 2 giá trị<a data-footnote-ref href="#user-content-fn-10">...</a></td></tr><tr><td>service_id</td><td>Int</td><td>Id dịch vụ trên <a href="/danh-muc/restful-api-cua-caresoft/dich-vu">caresoft</a></td></tr></tbody></table>

#### Headers

| Name | Type   | Description                                                        |
| ---- | ------ | ------------------------------------------------------------------ |
| \*\* | String | [Thông tin xác thực chung ](/thong-tin-chung#phuong-thuc-xac-thuc) |

{% tabs %}
{% tab title="200: OK Thành công" %}
{% tabs %}
{% tab title="Kết quả điển hình" %}

```json
{
    "code": "OK",
    "numFound": 74,
    "calls": [
        {
            "id": 425647,
            "customer_id": 63204960,
            "call_id": "20221008233814-LSKMQKWP-43",
            "caller": "0868887835",
            "called": "1068",
            "service_id":"100155",
            "user_id": "1",
            "agent_id": "5000",
            "group_id": 1,
            "call_type": 0,
            "start_time": "2022-10-08 23:38:14",
            "call_status": "miss",
            "end_time": "2022-10-08 23:38:29",
            "wait_time": "00:00:15",
            "hold_time": "00:00:00",
            "talk_time": "00:00:00",
            "end_status": "cus",
            "ticket_id": 315053,
            "last_agent_id": "5000",
            "last_user_id": 1,
            "call_survey": "NO",
            "call_survey_result": null,
            "missed_reason": "missed_customer"
        },{
            "id": 425885,
            "customer_id": 29370843,
            "call_id": "20221104143655-LSKMQKWP-268",
            "path": "https://caresoft.vn:19991/f/b6a0d15a9cf87c6cef402e5131f24f6b//6364c13c7569dc76dc5ee57e/6b0e12c9b3304d8e787****194/4bae18d9c8a3ab403210ae724b8f37ab.mp3",
            "path_download": "https://caresoft.vn:19991/f/b6a0d15a9cf87c6cef402e5131f24f6b//6364c13c7569dc76dc5ee57e/cd0490cefca753*****9/4bae18d9c8a3ab403210ae78f37ab.mp3",
            "caller": "0901774143",
            "called": "1066",
            "service_id":"100155",
            "user_id": "63150156",
            "agent_id": "1444",
            "group_id": 65,
            "call_type": 0,
            "start_time": "2022-11-04 14:36:55",
            "call_status": "meetAgent",
            "end_time": "2022-11-04 14:37:19",
            "wait_time": "00:00:01",
            "hold_time": "00:00:00",
            "talk_time": "00:00:23",
            "end_status": "system",
            "ticket_id": 317946,
            "last_agent_id": "1444",
            "last_user_id": 63150156,
            "call_survey": "NO",
            "call_survey_result": null,
            "missed_reason": null
        },

        ...
      ]
    }
```

{% endtab %}

{% tab title="Mô tả kết quả" %}

<table><thead><tr><th width="76">STT</th><th width="177">Trường thông tin</th><th width="101">Kiểu</th><th>Ý nghĩa</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>String</td><td>Trạng thái thành công </td></tr><tr><td>2</td><td>numFound</td><td>Int</td><td>Số lượng bản ghi tìm thấy, sử dụng phân trang dữ liệu</td></tr><tr><td>3</td><td>calls</td><td>Array</td><td>Mảng thông tin cuộc gọi.<br>Các trường dữ liệu mô tả trong <a data-mention href="#thong-tin-truong-du-lieu-cua-cuoc-goi">#thong-tin-truong-du-lieu-cua-cuoc-goi</a></td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="401: Unauthorized Mã token không đúng" %}

{% endtab %}

{% tab title="500: Internal Server Error " %}

{% endtab %}
{% endtabs %}

[^1]: 0: Gọi vào\
    1: Gọi ra

[^2]: miss: Gọi nhỡ\
    metAgent: Gặp chuyên viên

[^3]: cus: Do khách hàng hạ máy

    system: Do chuyên viên dập máy

[^4]: `missed_customer`  Nhỡ bởi khách

    `missed_agent_device` Nhỡ bởi thiết bị của agent\
    `missed_agent_reject`   Nhỡ bởi chuyên viên dập máy

    `missed_agent_timeout` Nhỡ bởi không tìm thấy chuyên viên<br>

[^5]: Trong trường hợp cuộc gọi được chuyển qua nhiều chuyên viên để xử lý thì trường này lưu lại số ipPhone của chuyên viên cuối cùng.

[^6]: Cần tối thiểu 5 phút sau khi kết thúc cuộc gọi để hệ thống tạo file ghi âm

[^7]:

[^8]: 0: Gọi vào\
    1: Gọi ra

    3: Cuộc gọi IVR

[^9]: Mặc định sắp xếp giảm dần theo trường  `start_time`

[^10]: ASC: Tăng dần,\
    DESC: Giảm dần (Mặc định)


# Tin nhắn SMS

API thông tin gửi tin nhắn SMS qua hệ thống CareSoft

Để gửi tin nhắn SMS trên CareSoft cần dịch vụ SMS Brandname đã được tích hợp vào tài khoản khách hàng.&#x20;

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2Frv8kTcNt9DCRLnmdltta%2Fimage.png?alt=media&amp;token=412cbd84-c915-4295-ab54-30aa4fcdbb56" alt="" width="332"><figcaption><p>Cách kiểm tra dịch vụ SMS đã được tích hợp lên hệ thống và lấy ID dịch vụ để thực hiện gửi SMS </p></figcaption></figure>

Lập trình viên có thể sử dụng API SMS tích hợp vào hệ thống CRM/ERP để thực hiện các nghiệp vụ nhắn tin báo số dư, báo trạng thái đơn hàng cho khách hàng theo bối cảnh thực tế.

### Thông tin trường dữ liệu SMS&#x20;

<table><thead><tr><th width="88" data-type="number">STT</th><th width="133">Tên trường</th><th width="133">Kiểu dữ liệu<select><option value="0c41f215a0e941c9973e6b6b6b26a9b5" label="STRING (1000)" color="blue"></option><option value="663e68d0124341ef98fca59215b3d6bd" label="TELEPHONE" color="blue"></option><option value="e30534b0a730432fa57d9f37ca392a75" label="INT" color="blue"></option></select></th><th>Ý nghĩa</th></tr></thead><tbody><tr><td>1</td><td>service_id</td><td><span data-option="e30534b0a730432fa57d9f37ca392a75">INT</span></td><td>ID dịch vụ SMS đã tích hợp trên hệ thống CareSoft</td></tr><tr><td>2</td><td>content</td><td><span data-option="0c41f215a0e941c9973e6b6b6b26a9b5">STRING (1000)</span></td><td>Nội dung tin nhắn gửi đi</td></tr><tr><td>3</td><td>phone</td><td><span data-option="663e68d0124341ef98fca59215b3d6bd">TELEPHONE</span></td><td>Số điện thoại nhận SMS</td></tr><tr><td>4</td><td>ticket_id</td><td><span data-option="e30534b0a730432fa57d9f37ca392a75">INT</span></td><td>ID phiếu ghi trong trường hợp cần gán vào phiếu ghi đã có từ trước</td></tr></tbody></table>

#### Mẫu json body gửi SMS

```json
{
    "sms": {
        "service_id": "12",
        "content": "nội dung tin nhắn",
        "phone": "0980000000"
    }
}
```

#### Mẫu curl gửi tin nhắn SMS&#x20;

```powershell
curl --location --globoff 'https://api.caresoft.vn/{{domain}}/api/v1/sms' \
--header 'Authorization: Bearer {{apiToken}}' \
--header 'Content-Type: application/json' \
--data '{
    "sms": {
        "service_id": "12",
        "content": "Chúc mừng sinh nhật quý khách hàng.",
        "phone": "0980000000"
    }
}'
```

#### Mẫu POSTMAN cấu hình thông tin gửi SMS&#x20;

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FKxFnB1GjllvF1Mdi7KIS%2FPOST_MAN_SMS_SAMPLE.png?alt=media&amp;token=cee1b285-f184-454a-b21d-187b6dbc427b" alt=""><figcaption></figcaption></figure>

## Gửi tin nhắn SMS&#x20;

<mark style="color:green;">`POST`</mark> `{{domain}}/api/v1/sms`

API gửi SMS&#x20;

#### Headers

| Name                                   | Type   | Description                                                        |
| -------------------------------------- | ------ | ------------------------------------------------------------------ |
| \*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung ](/thong-tin-chung#phuong-thuc-xac-thuc) |

#### Request Body

| Name                                  | Type   | Description                                                                   |
| ------------------------------------- | ------ | ----------------------------------------------------------------------------- |
| sms<mark style="color:red;">\*</mark> | Object | Theo [#thong-tin-truong-du-lieu-sms](#thong-tin-truong-du-lieu-sms "mention") |

{% tabs %}
{% tab title="200: OK " %}
{% tabs %}
{% tab title="Kết quả điển hình" %}

```json
{
  "code": "ok",
  "ticket": {
    "ticket_id": 291437,
    "ticket_no": 205025,
    "requester_id": 63203810,
    "assignee_id": 1
  }
}
```

{% endtab %}

{% tab title="Mô tả  kết quả" %}

{% endtab %}
{% endtabs %}

{% endtab %}

{% tab title="400: Bad Request " %}

{% endtab %}

{% tab title="500: Internal Server Error " %}

{% endtab %}
{% endtabs %}

<table><thead><tr><th width="91">STT</th><th width="112">Tên trường</th><th width="129">Kiểu</th><th>Ý nghĩa</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>String</td><td>Trạng thái thành công</td></tr><tr><td>2</td><td>ticket</td><td>Object</td><td>Đối tượng phiếu ghi được tạo mới/Hoặc cập nhật khi gửi SMS <br><a data-footnote-ref href="#user-content-fn-1">(Xem thêm)</a></td></tr><tr><td></td><td></td><td></td><td></td></tr></tbody></table>

[^1]: `ticket_id`: Id Phiếu ghi\
    `ticket_no`: Số phiếu ghi\
    `assignee_id`: ID chuyên viên giữ phiếu\
    `requester_id`: ID khách hàng


# Tin nhắn Zalo

Api kiểm tra trạng thái của khách hàng và gửi tin nhắn tư vấn, tin nhắn giao dịch, tin nhắn truyền thông...

## Kiểm tra trạng thái khách hàng

Hàm kiểm tra các trạng thái \
Payload body TEXT/JSON

```json
{
    "phone_no": "098****980",
    "oa_id": "160019****752846"
}
```

Bảng mô tả kết quả trả về thành công

<table><thead><tr><th width="77.33333333333331">Stt</th><th width="351">Trường dữ liệu</th><th>Chú thích</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>ok/errors: Trạng thái thành công/ Thất bại</td></tr><tr><td>2</td><td>data</td><td>Object dữ liệu trạng thái khách hàng</td></tr><tr><td>3</td><td>data.user_id</td><td>ID khách hàng</td></tr><tr><td>3</td><td>data.username</td><td>Tên khách hàng trên hệ thống CareSoft</td></tr><tr><td>4.</td><td>data.zalo_psid</td><td>Zalo ID của khách hàng tương ứng với OA truyền vào. </td></tr><tr><td>5</td><td>data.following_status</td><td>Trạng thái follow: <br>1: Đang follow<br>0/null: Không follow</td></tr><tr><td>6</td><td>data.last_user_activity_time</td><td>Lần tương tác gần nhất (Định dạng YYYY-mm-dd HH:MM:SS). <br>null: Không có tương tác</td></tr><tr><td>7</td><td>data.can_send_consultation_message</td><td>Có thể gửi tin nhắn tư vấn: <br><code>1: Có thể</code><br><code>0/null: Không thể</code></td></tr><tr><td>8</td><td>data.consultation_message_expired_time</td><td>Thời hạn có thể gửi tin nhắn tư vấn (Định dạng YYYY-mm-dd HH:MM:SS). <br><code>null: Không thể gửi</code></td></tr><tr><td>9</td><td>data.can_send_transaction_message</td><td>Có thể gửi tin nhắn giao dịch<br><code>true: Có thể</code><br><code>false: Không thể</code></td></tr><tr><td>10</td><td>data.can_send_promotion_message</td><td>Có thể gửi tin nhắn truyền thông<br><code>true: Có thể</code><br><code>false: Không thể</code></td></tr><tr><td>11</td><td>data.can_call_zcc_by_phone</td><td>Có thể gọi Zalo Call theo số điện thoại<br>true: Có thể<br>false: Không thể</td></tr><tr><td>12</td><td>data.can_call_zcc_by_zalo_id</td><td>Có thể gọi Zalo Call theo zalo_id<br>true: Có thể<br>false: Không thể</td></tr><tr><td>13</td><td>data.can_send_zns</td><td>Có thể gửi tin nhắn ZNS <br>true: Có thể<br>false: Không thể</td></tr><tr><td>14</td><td>data.is_merge</td><td>Trạng thái merge các profiles lại<br>false: Chưa từng merge<br>true: đã merge </td></tr><tr><td>15</td><td>merge_users</td><td>Mảng thông tin các user zalo được merge theo số điện thoại trên. Trong đó là mảng object tương tự  object data.<br>Key này chỉ xuất hiện nếu data.is_merge= true  </td></tr></tbody></table>

## Kiểm tra trạng thái Zalo của số điện thoại bất kỳ

<mark style="color:green;">`POST`</mark> `{{domain}}/api/v1/zalo/user-status`

Trạng thái Tương tác với Zalo của một số điện thoại tới 1 trang Zalo theo OA ID

#### Request Body

| Name                                        | Type      | Description                  |
| ------------------------------------------- | --------- | ---------------------------- |
| phone\_no<mark style="color:red;">\*</mark> | Telephone | Số điện thoại của khách hàng |
| oa\_id                                      | String    | Zalo OA Id                   |

{% tabs %}
{% tab title="200: OK Thành công" %}
&#x20;**Kết quả thành công**

```json
{
    "code": "ok",
    "data": {
        "user_id": "63**92",
        "username": "Nguyễn **Nghĩa",
        "zalo_psid": "894*****136201",
        "following_status": true,
        "last_user_activity_time": "2023-08-03 16:32:40",
        "can_send_consultation_message": true,
        "consultation_message_expired_time": "2023-08-10 16:32:40",
        "consultation_message_free_remain": 10,
        "can_send_transaction_message": true,
        "can_send_promotion_message": true,
        "can_call_zcc_by_phone": false,
        "can_call_zcc_by_zalo_id": true,
        "can_send_zns": true
        "is_merge":true
    },
    "merge_users":[
     {
        "user_id": "63**92",
        "username": "Nguyễn **Nghĩa",
        "zalo_psid": "894*****136201",
        "following_status": true,
        "last_user_activity_time": "2023-08-03 16:32:40",
        "can_send_consultation_message": true,
        "consultation_message_expired_time": "2023-08-10 16:32:40",
        "consultation_message_free_remain": 10,
        "can_send_transaction_message": true,
        "can_send_promotion_message": true,
        "can_call_zcc_by_phone": false,
        "can_call_zcc_by_zalo_id": true,
        "can_send_zns": true
        "is_merge":true
    },
     {
        "user_id": "63**92",
        "username": "ABC **Nghĩa",
        "zalo_psid": "894*****13620221",
        "following_status": true,
        "last_user_activity_time": "2023-08-03 16:32:40",
        "can_send_consultation_message": true,
        "consultation_message_expired_time": "2023-08-10 16:32:40",
        "consultation_message_free_remain": 10,
        "can_send_transaction_message": true,
        "can_send_promotion_message": true,
        "can_call_zcc_by_phone": false,
        "can_call_zcc_by_zalo_id": true,
        "can_send_zns": true
        "is_merge":true
    }
    ]
}
```

**Giải thích kết quả theo payload phía trên:**\
\
Dữ liệu kiểm tra tương tác khách hàng có số 098\*\*\*\*980  với OA 160019\*\*\*\*752846\
Có kết quả\
\- user\_id 63\*\*92 (ContactId trên hệ thống CareSoft)\
\- Họ tên: "Nguyễn \*\*Nghĩa"\
\- Zalo ID: "894\*\*\*\*\*136201"\
\- Trạng thái follow: Đang follow\
\- Lần tương tác gần đây nhất: "2023-08-03 16:32:40"\
\- Có thể gửi tin nhắn tin vấn.\
\- Còn có thể gửi: 10 tin nhắn tư vấn\
\- Có thể gửi tin nhắn giao dịch\
\- Có thể gửi tin nhắn quảng bá\
\-  Không thể gọi Zalo Call theo số điện thoại\
\- Có thể gọi Zalo Call theo Zalo ID\
\- Có thể gửi tin nhắn ZNS&#x20;
{% endtab %}

{% tab title="400: Bad Request Có lỗi" %}
Lỗi không tìm thấy người dùng/khách hàng

```
{
    "code": "errors",
    "message": "Not found users ",
    "status": -1
}
```

Lỗi không tìm thấy OA hoặc OA mất kích hoạt

```
{
    "code": "errors",
    "message": "Not found or in-active zalo oa id",
    "status": -1
}
```

{% endtab %}
{% endtabs %}

## Gửi tin nhắn truyền thông, tin nhắn giao dịch và tin nhắn tư vấn

Tùy theo mục đích sử dụng và nhu cầu của nghiệp vụ, nhà phát triển có thể sử dụng API dưới đây để gửi tin ZALO tới khách hàng của mình. \
\
**Body Payload điển hình** \
***1. Gửi tin nhắn tới số điện thoại theo kịch bản có parameter***

```json
{
    "zalo": {
        "phone_no": "098*****980",
        "oa_id": "16001****13752846",
        "script_id": 608,
        "template_params": {
            "username": "Anh Tan"
        }
    }
}
```

***2. Gửi tin nhắn tới số điện thoại theo nội dung tùy ý***

```json
{
    "zalo": {
        "phone_no": "098*****980",
        "oa_id": "16001****13752846",
        "message": "CareSoft cảm ơn quý khách đã sử dụng dịch vụ"
    }
}
```

***3. Gửi tin nhắn tới id của Khách hàng trên Caresoft theo nội dung tùy ý***

```json
{
    "zalo": {
        "user_id": "122052447",
        "oa_id": "16001****13752846",
        "message": "CareSoft Xin chào!"
    }
}
```

Bảng mô tả thông tin gửi đi. trong object "zalo"&#x20;

<table><thead><tr><th width="76">STT</th><th>Trường dữ liệu</th><th width="156">Kiểu</th><th>Ghi chú</th></tr></thead><tbody><tr><td>1</td><td>phone_no (*)</td><td>Telephone</td><td>Số điện thoại của người nhận<br>(*) Nếu không có cần có user_id của người dùng để thay thế </td></tr><tr><td>2</td><td>user_id (*)</td><td>Int</td><td>ContactID của khách hàng định danh trên CareSoft<br>(*) Trong trường hợp gửi theo số điện thoại thì không điền tham số này</td></tr><tr><td>3</td><td>oa_id *</td><td>Int</td><td>Zalo OA Id của Trang Zalo đã tích hợp lên CareSoft (Bắt buộc)</td></tr><tr><td>4</td><td>script_id (**)</td><td>Int</td><td>ID Biểu mẫu được cấu hình trên CareSoft  (Xem trên giao diện Admin/Kịch Bản/Kịch bản Zalo) <br>Kịch bản có thể là kịch bản tin nhắn truyền thông, tin tư vấn hoặc tin giao dịch.<br>(**)Trong trường hợp không điền tham số này thì bắt buộc phải có trường message</td></tr><tr><td>5</td><td>message(**)</td><td>Text(1000)</td><td>Nội dung tin nhắn. <br>Nội dung bắt buộc nếu không truyền script_id, Nếu điền script_id vui lòng bỏ qua params này </td></tr><tr><td>6</td><td>template_params</td><td>ObjectArray</td><td>Trường này chỉ có tác dụng Khi gửi tin nhắn theo kịch bản<br>Đối tượng chứa các param thay thế được cấu hình trong kịch bản</td></tr></tbody></table>

## Gửi tin nhắn Zalo&#x20;

<mark style="color:green;">`POST`</mark> `{{domain}}/api/v1/zalo/send-message`

Gửi tin nhắn Truyền thông, Tin nhắn Giao dịch, Tin nhắn tư vấn

#### Request Body

| Name | Type   | Description                        |
| ---- | ------ | ---------------------------------- |
| (\*) | String | Theo Payload JSON Object phía trên |

{% tabs %}
{% tab title="200: OK Thành công" %}

```json
{
    "code": "ok",
    "message": "Tạo thành công!"
}
```

{% endtab %}

{% tab title="400: Bad Request Lỗi " %}
Lỗi không tìm thấy người dùng

```
{
    "code": "errors",
    "message": "Not found zalo profile of user"
}
```

Lỗi không tìm thấy Zalo OA id hoặc OA đang mất kích hoạt

```json
{
    "code": "errors",
    "message": "Not found zalo oa 160011954754137252846"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Lỗi thông tin không hợp lệ" %}
Payload body còn thiếu hoặc sai nội dung
{% endtab %}
{% endtabs %}


# Tin nhắn Zalo ZNS

Gửi tin nhắn ZNS tới Zalo  của khách hàng thông qua số điện thoại

## 1. Gửi ZNS&#x20;

Chuẩn bị: ID kịch bản trên hệ thống caresoft với template được ZALO duyệt (kèm ZNS\_ID)

**Thông tin trường dữ liệu gửi ZNS**&#x20;

<table><thead><tr><th width="98">STT</th><th width="129">Trường</th><th width="168">Kiểu </th><th>Chú thích</th></tr></thead><tbody><tr><td>1</td><td>zns</td><td>Object</td><td>Object chứa thông tin gửi ZNS</td></tr><tr><td></td><td>..</td><td></td><td></td></tr><tr><td>2</td><td>phone</td><td>TelephoneNo</td><td>Số điện thoại cần gửi ZNS</td></tr><tr><td>3</td><td>template_id</td><td>Int</td><td>Mẫu nội dung template được cấu hình đã được Zalo phê duyệt Template này được cấu hình liên kết đến 1 zalo OA đã tích hợp vào caresoft từ trước đó<br>(Xem hướng dẫn ở mục 2) </td></tr><tr><td>4</td><td>ticket_id</td><td>Int</td><td>Id của phiếu ghi nếu muốn thực hiện nghiệp vụ trả lời cho 1 phiếu ghi đã có, trong trường hợp không truyền tham số này hệ thống sẽ tự tạo 1 phiếu ghi mới </td></tr><tr><td>5</td><td>params</td><td>Object</td><td><p>Object Param dạng <br><code>{</code></p><p> <code>param:value,</code> </p><p> <code>param1:value1</code></p><p><code>}</code><br> Đây là tên biến và giá trị thay thế được cấu hình trên nội dung kịch bản ZNS (xem hướng dẫn Mục 3 phía dưới)</p><p>Trong trường hợp không truyền tham số này, Hệ thống tự động lấy các tham số đã cấu hình mapping trong kịch bản </p></td></tr></tbody></table>

**Body Payload tiêu biểu.**&#x20;

\
Trong payload này  hệ thống sẽ gửi 1 kịch bản ZNS có ID là 366 tới khách hàng có số điện thoại  09839\*\*148  và ghi chú phản hồi vào phiếu ghi có ID  297005

{% code title="Body Payload JSON/Object" %}

```json
{
    "zns": {
        "phone": "09839**148",
        "template_id": 366,
        "ticket_id": 297005,
        "params": {
            "requester": "Nguyễn Hải Hà",
            "masoDatve": "098733" 
        }
    }
}
```

{% endcode %}

## Gửi tin nhắn Zalo ZNS

<mark style="color:green;">`POST`</mark> `{{domain}}/api/v1/zalo/zns`

Gửi tin nhắn ZNS tới 1 số điện thoại bất kỳ đã đăng ký tài khoản Zalo

#### Headers

| Name                                   | Type   | Description                                                        |
| -------------------------------------- | ------ | ------------------------------------------------------------------ |
| \*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung ](/thong-tin-chung#phuong-thuc-xac-thuc) |

#### Request Body

| Name             | Type    | Description                                                                                                                                                                                                                                                                                                                                                                 |
| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| zns              | Object  | Object thông tin gửi ZNS                                                                                                                                                                                                                                                                                                                                                    |
| zns.phone        | PhoneNo | Số điện thoại cần gửi ZNS                                                                                                                                                                                                                                                                                                                                                   |
| zns.template\_id | Int     | <p>Mẫu nội dung template được cấu hình đã được Zalo phê duyệt Template này được cấu hình liên kết đến 1 zalo OA đã tích hợp vào caresoft từ trước đó<br>(Xem hướng dẫn ở mục 2) </p><p></p><p></p>                                                                                                                                                                          |
| zns.params       | Object  | <p>Object Param dạng <br><code>{</code></p><p> <code>param:value,</code> </p><p> <code>param1:value1</code></p><p><code>}</code><br> Đây là tên biến và giá trị thay thế được cấu hình trên nội dung kịch bản ZNS (xem hướng dẫn Mục 3 phía dưới)</p><p>Trong trường hợp không truyền tham số này, Hệ thống tự động lấy các tham số đã cấu hình mapping trong kịch bản </p> |
| zns.ticket\_id   | Int     | Id của phiếu ghi nếu muốn thực hiện nghiệp vụ trả lời cho 1 phiếu ghi đã có, trong trường hợp không truyền tham số này hệ thống sẽ tự tạo 1 phiếu ghi mới                                                                                                                                                                                                                   |

{% tabs %}
{% tab title="200: OK Kết quả thành công" %}

```json
{
    "status": "OK",
    "ticket": {
        "ticketId": "297002"
    }
}
```

{% endtab %}

{% tab title="400: Bad Request Lỗi thông tin " %}
{% code title="Lỗi không tìm thấy template" %}

```json
{
    "code": "errors",
    "errors": {
        "template_id": [
            "The selected template id is invalid."
        ]
    }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

## 2. Cách lấy template\_id trên CareSoft

Sử dụng tài khoản Admin  vào menu Admin → Kịch bản , Trong loại kịch bản chọn “Gửi tin nhắn Zalo ZNS” →  bấm tìm kiếm&#x20;

Copy ID kịch bản trong phần kết quả (khoanh tròn màu đỏ) tương ứng.&#x20;

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FfVVZyWiMlci4zCK5v4AS%2Fimage.png?alt=media&amp;token=eefc0fe0-64a2-45c1-bc9d-4c546df41fa0" alt=""><figcaption></figcaption></figure>

## 3. Cấu hình kịch bản ZNS&#x20;

Lưu ý: ID kịch bản Zalo ZNS phải là ID được Zalo phê duyệt.  Zalo OA là Page Zalo đã được tích hợp vào CareSoft&#x20;

<figure><img src="https://lh3.googleusercontent.com/OsuLPKcPW9oqKpV9sr3ncEe-sKbQ5NHQn0IC_45Uwuw5Qj0tqPTo_LaZnNolb5u3ZGvX7t5pf4GtfYjistNWvM5FaplfuB1tTFf3jqrYBvQX4q4dczC3rkJIEDGorlk_Ec2uZQKlIZ1j68mF1HBwbQ" alt=""><figcaption></figcaption></figure>


# Chiến dịch

Lấy danh sách chiến dịch trên CareSoft

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FdYa7HST5OSG4VAHxEDbo%2Fimage.png?alt=media&amp;token=bdb6cf4a-cda2-4c14-9767-237be8e0309c" alt=""><figcaption></figcaption></figure>

## Danh sách các chiến dịch trên CareSoft

<mark style="color:green;">`GET`</mark> `{{domain}}/api/v1/campaigns`

API lấy danh sách các chiến dịch đang có. Dữ liệu được sắp xếp từ mới nhất đến cũ nhất  (theo `campaign_id`)

#### Request Body

| Name           | Type     | Description                                                                                                                  |
| -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| created\_since | DateTime | Thời điểm tạo bắt đầu từ mặc định từ ngày đầu tiên của năm                                                                   |
| created\_to    | DateTime | Thời điểm tạo tới. Mặc định là thời điểm hiện tại                                                                            |
| status         | String   | <p>Trạng thái chiến dịch cho phép các giá trị:<br>NEW: Mới<br>RUNNING: Đang chạy<br>PAUSE: Tạm dừng</p><p>STOP: Kết thúc</p> |
| page           | Int      | Trang số (mặc định 1)                                                                                                        |
| count          | Int      | Số bản ghi trên trang (mặc định 500, tối đa 500)                                                                             |

{% tabs %}
{% tab title="200: OK Kết quả" %}
{% tabs %}
{% tab title="Kết quả điển hình" %}

<pre><code>{
    "code": "ok",
    "campaigns": [
<strong>        {
</strong>            "campaign_status": "FINISHED",
            "campaign_name": "Đồng bộ chi tiết chiến dịch ",
            "campaign_id": 81584,
            "start_time": "2024-09-28 00:00:00",
            "end_time": "2024-09-28 00:00:00",
            "created_at": "2024-09-28 00:05:19",
            "v_type": 1,
            "member_status": [
                {
                    "id": 349,
                    "description": "Chưa gửi",
                    "is_default": 1,
                    "campaign_id": 81584
                },
                {
                    "id": 350,
                    "description": "Đã gửi",
                    "is_default": 0,
                    "campaign_id": 81584
                },
                {
                    "id": 351,
                    "description": "Gửi lỗi",
                    "is_default": 0,
                    "campaign_id": 81584
                },
                {
                    "id": 352,
                    "description": "Gửi thành công",
                    "is_default": 0,
                    "campaign_id": 81584
                }
            ]
        },
        {
            "campaign_status": "NEW",
            "campaign_name": "Life Event - Sự kiện",
            "campaign_id": 56618,
            "start_time": "2023-04-03 16:03:41",
            "end_time": "2023-04-03 16:03:41",
            "created_at": "2023-04-03 16:03:41"
            "v_type": 0,
        },
        {
            "campaign_status": "NEW",
            "campaign_name": "Life events - CMSN",
            "campaign_id": 56617,
            "start_time": "2023-04-03 16:03:33",
            "end_time": "2023-04-03 16:03:33",
            "created_at": "2023-04-03 16:03:33"
        },
        {
            "campaign_status": "NEW",
            "campaign_name": "Happy call",
            "campaign_id": 56616,
            "start_time": "2023-04-03 16:03:13",
            "end_time": "2023-04-03 16:03:13",
            "created_at": "2023-04-03 16:03:13"
        }
    ],
    "created_since": "2023-01-01 00:00:00",
    "created_to": "2023-04-24 15:29:36",
    "numFound": 3
}
</code></pre>

{% endtab %}

{% tab title="Mô tả kết quả" %}

<table><thead><tr><th width="102">STT</th><th width="170">Trường dữ liệu</th><th>Ghi chú</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>Trạng thái thực thi <code>ok</code>, <code>errors</code></td></tr><tr><td>2</td><td>campaigns</td><td><p>Mảng dữ liệu chiến dịch</p><p>Gồm các object có cấu trúc </p><ul><li><code>campaign_status</code>: Trạng thái chiến dịch</li><li><code>campaign_name</code>: Tên chiến dịch</li><li><code>campaign_id</code>: ID chiến dịch</li><li><code>start_time</code>: Ngày bắt đầu,</li><li><code>end_time</code>:Thời điểm kết thúc</li><li><code>created_at</code>: Ngày tạo</li><li><p>v_type: Phiên bản chiến dịch (Đối với v_type=1 thì sẽ có thêm danh sách các trạng thái của chiến dịch,   member_status.id sẽ tương đương member_status_id khi tạo hay update phiếu ghi.<br></p><pre class="language-json"><code class="lang-json">  "member_status": [
                {
                    "id": 349,
                    "description": "Chưa gửi",
                    "is_default": 1,
                    "campaign_id": 81584
                },...
</code></pre></li></ul></td></tr><tr><td>3</td><td>created_to</td><td>Thời điểm lọc chiến dịch đến theo ngày tạo</td></tr><tr><td>4</td><td>numFound</td><td>Số lượng chiến dịch tìm ra</td></tr><tr><td>5</td><td>created_since</td><td>Thời điểm lọc chiến dịch đến theo ngày tạo</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

{% endtab %}
{% endtabs %}


# Kết quả chiến dịch

Lấy kết quả chiến dịch qua API

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FHHTQy1Uku2vKQVbOus0h%2FPOSTMAN_KetquaChiendich.png?alt=media&amp;token=36a25ef0-439e-4ca6-8f5f-f491d9ba86b7" alt=""><figcaption></figcaption></figure>

## Kết quả chiến dịch

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/campaigns/results`

#### Query Parameters

| Name                                           | Type               | Description                                   |
| ---------------------------------------------- | ------------------ | --------------------------------------------- |
| start\_time                                    | DateTime (ISO8601) | Thời gian tạo từ ngày (yyyy-MM-ddTHH:mm:ssZ)  |
| end\_time                                      | DateTime (ISO8601) | Thời gian tạo tới ngày (yyyy-MM-ddTHH:mm:ssZ) |
| campaign\_id<mark style="color:red;">\*</mark> | Int                | ID chiến dịch                                 |
| manual\_message\_id                            | Int                | ID tin nhắn thủ công                          |
| auto\_message\_id                              | Int                | ID tin nhắn tự độngn                          |
| script\_id<mark style="color:red;">\*</mark>   | Int                | ID kịch bản                                   |

{% tabs %}
{% tab title="200: OK Kết quả thành công" %}
{% tabs %}
{% tab title="Kết quả tiêu biểu" %}

```json
{
    "code": "OK",
    "numFound": 2,
    "data": [
        {
            "ticket_id": 384879220,
            "ticket_no": 7299,
            "ticket_priority": "Normal",
            "ticket_source": "Api",
            "ticket_status": "pending",
            "ticket_subject": "Khách hủy đơn mua iphone #200939",
            "created_at": "2023-04-12 14:08:48",
            ....
            "custom_field": [               
              {
                    "id": 6783,
                    "lable": "Cuộc gọi nhỡ",
                    "type": "Text",
                    "value": null
                }
                ...
            ],
            "assignee": {
                "id": 124734559,
                "username": "Sale agent 1",
                "email": "nng****.com",
                "phone_no": "09875****",
                "agent_id": "50002",
                "role_id": 1,
                "group_id": 13067,
                "group_name": "test 123"
            },
            "requester": {
                "id": 164882867,
                "username": "Khach Hang Nguyen Van Nam",
                "email": null,
                "email2": null,
                "phone_no": "08122***",
                "phone_no2": null,
                "phone_no3": null,
                "organization_id": null,
                "custom_field": [
                    {
                        "id": 6840,
                        "lable": "Phân loại khách hàng",
                        "type": "Single drop-down list",
                        "value": null
                    }
                    ...                    
                ]
            },
            "campaign_result": [
                {
                    "id": 23452,
                    "lable": "Bạn có thực sự đặt hàng",
                    "type": "Single drop-down list",
                    "value": "52336"
                },
                {
                    "id": 23453,
                    "lable": "Tại sao bạn hủy đơn",
                    "type": "Text",
                    "value": "Do dat loi"
                },
                {
                    "id": 23454,
                    "lable": "Cảm ơn bạn nhiều",
                    "type": "Text",
                    "value": "Vang"
                }
            ]
        },
       ...   
           
    ]
}

```

{% endtab %}

{% tab title="Mô tả kết quả" %}
**Chi tiết phiếu ghi chiến dịch trong mảng dữ liệu kết quả.**

*Do kết quả 1 chiến dịch thường kèm theo việc nhập liệu phân loại dữ liệu  với các trường động phiếu ghi hoặc người dùng nên Object tickets trong kết quả chiến dịch sẽ đi kèm thông tin trường động của khách hàng, phiếu ghi và các thông tin cơ bản của phiếu ghi, vui lòng xem các thông tin từ các object liên quan*&#x20;
{% endtab %}
{% endtabs %}

{% endtab %}
{% endtabs %}


# Khai thác dữ liệu chuyên sâu

Api Search hỗ trợ tìm kiếm đa điều kiện, tìm khách hàng, tổ chức, phiếu ghi theo các thành phần đặc thù của chúng

Trong một số trường hợp cần khai thác sâu dữ liệu theo các điều kiện riêng biệt (VD: Chỉ lấy các phiếu ghi có trường động có tên "Phân loại"  đã lựa chọn giá trị "Chốt đơn"). Lập trình viên có thể sử dụng API search và truyền vào các điều kiện tìm kiếm cụ thể theo giá trị "Chốt đơn" như yêu cầu

Để bắt đầu tìm kiếm sử dụng  cú pháp truyền qua  body json với cấu trúc&#x20;

{% code title="Param tìm phiếu ghi cuộc gọi nhỡ" %}

```json
{
    "params": {
        "q": "Cuộc gọi nhỡ"
    }
}
```

{% endcode %}

Trong đó: “q” chứa từ khóa tìm kiếm, Tùy theo định dạng dữ liệu của “q” mà hệ thống sẽ tìm kiếm nhanh trong dữ liệu phiếu ghi:

* Nếu chứa toàn số. Hệ thống sẽ tự tìm theo  Số Phiếu ghi.
* Nếu là ký tự văn bản, hệ thống sẽ tìm theo Tiêu đề của phiếu ghi

## Api Search

## API tìm kiếm dữ liệu chuyên sâu

<mark style="color:green;">`POST`</mark> `{{domain}}/api/v1/search`

#### Headers

| Name                                   | Type   | Description                 |
| -------------------------------------- | ------ | --------------------------- |
| \*\*<mark style="color:red;">\*</mark> | String | Thông tin xác thực mặc định |

#### Request Body

| Name | Type   | Description                                   |
| ---- | ------ | --------------------------------------------- |
| \*   | String | Đối tượng được mô tả trong tài liệu phía dưới |

{% tabs %}
{% tab title="200: OK " %}

{% endtab %}

{% tab title="400: Bad Request " %}

{% endtab %}

{% tab title="500: Internal Server Error " %}

{% endtab %}
{% endtabs %}

1. TÌM PHIẾU GHI&#x20;

<table><thead><tr><th width="123">Sub param</th><th width="150">Key param</th><th width="114">Kiểu</th><th>Ý nghĩa</th><th data-hidden></th></tr></thead><tbody><tr><td>type</td><td><br></td><td><p>String</p><p><br></p></td><td>Loại dữ liệu tìm kiếm<br>TICKET: Tìm phiếu ghi (*) mặc định<br>USER: Tìm khách hàng<br>ORG: Tìm tổ chức </td><td></td></tr><tr><td>page</td><td><br></td><td>Int</td><td>Trang dữ liệu</td><td><br></td></tr><tr><td>count</td><td><br></td><td>Int</td><td>Số bản ghi trên 1 trang dữ liệu trả về (Tối đa 500)</td><td><br><br><br></td></tr><tr><td>params</td><td><br></td><td>Object array</td><td>Mảng đối tượng chứa điều kiện tìm kiếm</td><td>Bắt buộc</td></tr><tr><td><br></td><td>q</td><td><br></td><td><p>Chuỗi tìm kiếm mặc định<br><br></p><ul><li>Nếu chứa toàn số. Hệ thống sẽ tự tìm theo  Số Phiếu ghi. </li><li>Nếu là ký tự văn bản, hệ thống sẽ tìm theo Tiêu đề của phiếu ghi<br>Lưu ý: Nếu truyền dạng 098xxxx (số điện thoại) thì hệ thống sẽ hiểu là tìm theo chuỗi ký tự văn bản và tìm tương đối trong tiêu đề phiếu ghi</li></ul></td><td></td></tr><tr><td></td><td>ticket_subject</td><td>String</td><td>Tìm tương đối trong tiêu đề phiếu ghi</td><td><br></td></tr><tr><td></td><td>ticket_id</td><td>int</td><td>Tìm chính xác theo TIcket_ID</td><td><br></td></tr><tr><td></td><td>ticket_no</td><td>Int</td><td>Tìm chính xác theo Ticket Number</td><td><br></td></tr><tr><td></td><td>assignee_id</td><td>Int</td><td>Tìm chính xác theo người xử lý<br>(Xem thêm API Contact để lấy được ID)</td><td><br></td></tr><tr><td></td><td>service_id</td><td>Int</td><td>Tìm chính xác theo ID dịch vụ (Tham khảo API Lấy danh sách dịch vụ để có ServiceID)</td><td><br></td></tr><tr><td></td><td>ticket_priority</td><td>String</td><td><a data-footnote-ref href="#user-content-fn-1">Tìm theo độ ưu tiên. </a></td><td><br></td></tr><tr><td><br></td><td>ticket_status</td><td>String</td><td><a data-footnote-ref href="#user-content-fn-2">Tìm theo trạng thái ticket</a></td><td><br></td></tr><tr><td></td><td>ticket_source</td><td>String</td><td><a data-footnote-ref href="#user-content-fn-3">Tìm theo nguồn Ticket</a></td><td><br></td></tr><tr><td><br></td><td>requester_id</td><td>Int</td><td>Tìm ticket chính xách theo ID người yêu cầu (Xem thêm API Contact để lấy được ID)</td><td><br></td></tr><tr><td><br></td><td>campaign_id</td><td>Int</td><td>Tìm ticket chính xách theo ID chiến dịch (Xem thêm API Chiến dịch)</td><td><br></td></tr><tr><td><br></td><td>satisfaction_channel</td><td>Int </td><td>Tìm ticket theo kênh khảo sát. Các giá trị cho phép từ 1 đến 6<br>Trong đó: 1- voice, 2 - email, 3- sms, 4- manual, 5 - Livechat, 6 - Inbox Facebook</td><td><br></td></tr><tr><td><br></td><td>created_since</td><td>Date<br></td><td>Tìm ticket có ngày  tạo từ ngày <br>(YYYY-MM-DDTHH:mm:ssZ)</td><td><br></td></tr><tr><td><br></td><td>created_to</td><td>Date</td><td>Tìm ticket có ngày tạo nhỏ hơn ngày <br>(YYYY-MM-DDTHH:mm:ssZ)</td><td><br></td></tr><tr><td><br></td><td>updated_since</td><td>Date<br></td><td>Tìm ticket có ngày  cập nhật từ ngày<br>(YYYY-MM-DDTHH:mm:ssZ)</td><td><br></td></tr><tr><td><br></td><td>updated_to</td><td>Date<br></td><td>Tìm ticket có ngày cập nhật nhỏ hơn ngày (YYYY-MM-DDTHH:mm:ssZ)</td><td><br></td></tr><tr><td><br></td><td>duedate_since</td><td>Date</td><td>Tìm ticket có thời hạn xử lý từ ngày <br>(YYYY-MM-DDTHH:mm:ssZ)</td><td><br></td></tr><tr><td><br></td><td>duedate_to</td><td>Date</td><td>Tìm ticket có   thời hạn xử lý  nhỏ hơn ngày  (YYYY-MM-DDTHH:mm:ssZ)</td><td><br></td></tr><tr><td></td><td>qa_script_id</td><td>Int</td><td>Tìm kiếm phiếu ghi theo ID kịch bản QA</td><td></td></tr><tr><td></td><td>qa_agent</td><td>Int</td><td>Tìm kiếm phiếu ghi theo ID Chuyên viên QA</td><td></td></tr><tr><td></td><td>current_agent</td><td>Int</td><td>Tìm kiếm phiếu ghi QA theo chuyên viên </td><td></td></tr><tr><td></td><td>tag_name</td><td>String</td><td>Tìm ticket có gắn tag</td><td><br></td></tr><tr><td></td><td>custom_fields</td><td>Array</td><td>Mảng chứa điều kiện tìm kiếm theo trường động (* xem thêm mục 4)</td><td><br></td></tr></tbody></table>

2. **TÌM KHÁCH HÀNG (CONTACT)**

<table><thead><tr><th width="121">Key param</th><th width="154">Key param</th><th width="122">Kiểu dữ liệu</th><th>Ý nghĩa</th></tr></thead><tbody><tr><td>type</td><td><br></td><td><p>String</p><p><br></p></td><td>Loại dữ liệu tìm kiếm: <a data-footnote-ref href="#user-content-fn-4">USER</a></td></tr><tr><td>page</td><td><br></td><td>Int</td><td>Trang dữ liệu</td></tr><tr><td>count</td><td><br></td><td>Int</td><td>Số bản ghi trên 1 trang dữ liệu trả về</td></tr><tr><td>params</td><td><br></td><td>Object </td><td>Mảng đối tượng chứa điều kiện tìm kiếm</td></tr><tr><td><br></td><td>q</td><td><br></td><td><p>Chuỗi tìm kiếm mặc định<br><br></p><ul><li>Nếu chứa toàn số. Hệ thống sẽ tự tìm theo  ID người dùng.</li><li>Nếu là ký tự văn bản, hệ thống sẽ tìm theo Địa chỉ, tên người dùng, email người dùng, số điện thoại của người dùng<br>Lưu ý: Nếu truyền dạng 098xxxx (số điện thoại) thì hệ thống sẽ hiểu là tìm theo chuỗi ký tự văn bản và tìm tương đối trong tên người dùng, số điện thoại của người dùng</li></ul></td></tr><tr><td><br></td><td>email</td><td>String</td><td>Tìm tương đối theo email của người dùng </td></tr><tr><td><br></td><td>organization_id</td><td>Int</td><td>Tìm chính xác theo tổ chức của người dùng (Xem thêm API Tìm tổ chức) </td></tr><tr><td><br></td><td>follower_id</td><td>Int</td><td>Tìm chính xác khách hàng theo ID của người xử lý (Xem thêm API Agent)</td></tr><tr><td><br></td><td>username</td><td>String</td><td>Tìm tương đối theo tên người dùng</td></tr><tr><td><br></td><td>phone_no</td><td>String</td><td>Tìm tương đối theo số điện thoại của người dùng</td></tr><tr><td><br></td><td>address</td><td>String</td><td>Tìm tương đối theo địa chỉ người dung</td></tr><tr><td><br></td><td>detail</td><td>String</td><td>Tìm tương đối theo trường thông tin thêm </td></tr><tr><td><br></td><td>note</td><td>String</td><td>Tìm tương đối theo trường ghi chú</td></tr><tr><td></td><td>tag_name</td><td>String</td><td>Tìm người dùng có gắn tag</td></tr><tr><td></td><td>created_since</td><td>Date</td><td>Tìm người dùng có ngày  tạo từ ngày </td></tr><tr><td></td><td>created_to</td><td>Date</td><td>Tìm người dùng có ngày tạo nhỏ hơn ngày </td></tr><tr><td></td><td>updated_since</td><td>Date</td><td>Tìm người dùng có ngày  cập nhật từ ngày </td></tr><tr><td></td><td>updated_to</td><td>Date</td><td>Tìm người dùng có ngày cập nhật nhỏ hơn ngày </td></tr><tr><td></td><td>custom_field</td><td>Array</td><td>Mảng chứa điều kiện tìm kiếm theo trường động (* xem thêm mục 4)</td></tr></tbody></table>

TỔ CHỨC

<table><thead><tr><th width="122">Key param</th><th width="153">Key param</th><th width="121">Kiểu dữ liệu</th><th width="345">Ý nghĩa</th></tr></thead><tbody><tr><td></td><td></td><td></td><td></td></tr><tr><td><br></td><td><br></td><td><br></td><td><br></td></tr><tr><td>type</td><td><br></td><td><p>String</p><p><br></p></td><td>Loại dữ liệu tìm kiếm<br>TICKET: Tìm phiếu ghi<br>USER: Tìm khách hàng<br>ORG: Tìm tổ chức</td></tr><tr><td>page</td><td><br></td><td>Int</td><td>Trang dữ liệu</td></tr><tr><td>count</td><td><br></td><td>Int</td><td>Số bản ghi trên 1 trang dữ liệu trả về</td></tr><tr><td>params</td><td><br></td><td>Object array</td><td>Mảng đối tượng chứa điều kiện tìm kiếm</td></tr><tr><td><br></td><td>q</td><td><br></td><td><p>Chuỗi tìm kiếm mặc định</p><ul><li>Nếu chứa toàn số. Hệ thống sẽ tự tìm chính xác theo  ID Tổ chức.</li><li>Nếu là ký tự văn bản, hệ thống sẽ tìm theo Tên tổ chức, Domain của tổ chức</li></ul></td></tr><tr><td><br></td><td>domain</td><td>String</td><td>Tìm tương đối theo domain của tổ chức</td></tr><tr><td><br></td><td>name</td><td>String</td><td>Tìm tương đối theo tên tổ chức</td></tr><tr><td><br></td><td>detail</td><td>String</td><td>Tìm tương đối theo trường thông tin thêm</td></tr><tr><td><br></td><td>note</td><td>String</td><td>Tìm tương đối theo trường chú ý</td></tr><tr><td><br></td><td>created_since</td><td>Date</td><td>Tìm  tổ chức có ngày  tạo từ ngày </td></tr><tr><td><br></td><td>created_to</td><td>Date</td><td><p>Tìm tổ chức</p><p> có ngày tạo nhỏ hơn ngày </p></td></tr><tr><td><br></td><td>updated_since</td><td>Date</td><td>Tìm  tổ chức có ngày  cập nhật từ ngày </td></tr><tr><td><br></td><td>updated_to</td><td>Date</td><td>Tìm  tổ chức có ngày cập nhật nhỏ hơn ngày </td></tr><tr><td><br></td><td>tag_name</td><td>String</td><td>Tìm người dùng có gắn tag</td></tr><tr><td><br></td><td>custom_fields</td><td>Array</td><td>Mảng chứa điều kiện tìm kiếm theo trường động (* xem thêm mục 4)</td></tr></tbody></table>

### TRƯỜNG ĐỘNG

Trường động có cấu trúc chung giống nhau cho cả 3 đối tượng và tùy theo kiểu dữ liệu trường động được thiết lập trong cấu hình, hệ thống sẽ nhận diện kiểu dữ liệu tương ứng

**Cấu trúc mảng trường động kết hợp**

```json
"custom_fields": [    
            {
                "field_id": 14,
                "field_value_since": "2019-10-09T10:15:00Z",
                "field_value_to": "2019-11-09T10:15:00Z"
            },
            {
                "field_id": 16,
                "field_value_greater": "15",
                "field_value_lesser": "50"
            },
            {
                "field_id": 19,
                "field_value": "CODE234"
            }
        ]

```

**Trong đó:**&#x20;

* `field_id`: ID trường động (Tham khảo API /custom\_fields  của từng đối tượng dữ liệu trong tài liệu API DOCS)&#x20;
* `field_value`: Từ khóa tìm kiếm tương đối đối với dữ liệu dạng Văn bản, Số, Ký tự, chọn nhiều, tìm kiếm chính xác với dữ liệu dạng chọn 1.
* `field_value_since`: Tìm kiếm với dữ liệu dạng ngày tháng từ ngày.
* `field_value_to`: Tìm kiếm dữ liệu với dạng ngày tháng tới ngày
* `field_value_greater`: Tìm kiếm dữ liệu dạng số với giá trị lớn hơn.
* `field_value_lesser`: Tìm kiếm dữ liệu dạng số với giá trị nhỏ hơn <br>

[^1]: Trong danh sách sau:\
    Low, High, Normal, Urgent

[^2]: Trong danh sách sau\
    open, pending, closed, solved, new

[^3]: **Trong danh sách sau**\
    Voice, Chat, Email, Facebook, Voicemail, Web, Voice Out, Email Out, Sms Out, Inbox Facebook, Inbox Zalo, Api, Facebook Rating, Facebook Lead Ads, Voice Campaign, IVR, Ticket Form, Ticket Sharing

[^4]:


# Smart Dialer

Tạo dữ liệu, lấy kết quả cuộc gọi và bật tắt chiến dịch smartdialer trên  CareSoft

Tài liệu này cung cấp các luồng tích hợp SmartDialer vào ứng dụng của quý khách.

{% hint style="info" %}
Lưu ý: Địa chỉ HOST của các cuộc gọi API tới dịch vụ smartdialer sẽ là

&#x20;**`https://dialer-api.caresoft.vn`**
{% endhint %}

## 1. Danh sách chiến dịch

<mark style="color:green;">`GET`</mark> `/{domain}/api/v1/campaign/list`

Danh sách các chiến dịch đã được cấu hình trên hệ thống.

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Params**

| Name         | Type                         | Description              | Ghi chú                                                                                              |
| ------------ | ---------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------- |
| date\_from   | DateTime YYYY-MM-DD HH:mm:ss | Từ ngày (tạo chiến dịch) | Ngày đầu tiên trong năm                                                                              |
| date\_to     | DateTime YYYY-MM-DD HH:mm:ss | Age of the user          | Thời điểm hiện tại                                                                                   |
| status       | Int                          | Trạng thái chiến dịch    | <p>Là 1 trong các giá trị 0: Draff<br>1:  New<br>2: Ready<br>3: Running<br>4: Pause<br>5: Finish</p> |
| page         | int                          | Trang số                 | Mặc định 1                                                                                           |
| count        | int                          | Số bản ghi trên request  | Mặc định 25, tối đa 1000                                                                             |
| campaign\_id | Int                          | ID campaign              | Trong truờng hợp chỉ cần thông tin của 1 chiến dịch cụ thể có thể dùng theo cách này                 |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "numFound": "3",
    "data": [
        {
            "campaign_id": 5674,
            "name": "123456",
            "schedule_start": null,
            "schedule_stop": null,
            "statusType": "DRAFF",
            "actionType": "AUTODIAL",
            "status": 0,
            "action": 3
        },
        {
            "campaign_id": 5323,
            "name": "TestAT",
            "schedule_start": "2022-09-26 00:00:00",
            "schedule_stop": "2022-09-26 23:59:59",
            "statusType": "FINISHED",
            "actionType": "AUTODIAL",
            "status": 5,
            "action": 3
        },
        {
            "campaign_id": 5320,
            "name": "2409 at",
            "schedule_start": "2022-09-24 00:00:00",
            "schedule_stop": "2022-09-24 23:59:59",
            "statusType": "DRAFF",
            "actionType": "AUTODIAL",
            "status": 0,
            "action": 3
        }
    ]
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

**Giải thích kết quả**

| Param           | Ý Nghĩa                      | Ghi chú                                                                       |
| --------------- | ---------------------------- | ----------------------------------------------------------------------------- |
| campaign\_id    | ID chiến dịch (khóa chính)   |                                                                               |
| name            | Tên chiến dịch               |                                                                               |
| schedule\_start | Thời điểm bắt đầu chiến dịch |                                                                               |
| schedule\_stop  | Thời điểm kết thúc           |                                                                               |
| status          | Trạng thái                   | <p>0: Draff<br>1:  New<br>2: Ready<br>3: Running<br>4: Pause<br>5: Finish</p> |
| action          | Loại chiến dịch              | <p>1: Preview<br>2: Predictive Call<br>3: Autocall</p>                        |

## 2. Kết quả cuộc gọi chiến dịch

<mark style="color:green;">`GET`</mark> `/{domain}/api/v1/smartdialer/call-logs`

Lấy danh sách kết quả chiến dịch tới khách hàng, Danh sách này thể hiện việc gọi được cho khách hàng hay không và giá trị cuộc gọi nếu gọi được là gì.&#x20;

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Params**

| Name               | Type                         | Description                                                                                                                                 |
| ------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| campaign\_id (\*)  | Int                          | ID chiến dịch                                                                                                                               |
| campaign\_type     | Varchar                      | <p>Kiểu chiến dịch Điền 1 trong 2 loại kiểu chiến dịch để lấy dữ liệu theo tất cả chiến dịch dạng đó <br>AUTO\_CALL<br>PREDICTIVE\_CALL</p> |
| start\_time\_since | DateTime YYYY-MM-DD HH:mm:ss | <p>Thời điểm bắt đầu lọc dữ liệu<br><em>\* Mặc định từ ngày đầu trong tháng</em></p>                                                        |
| start\_time\_to    | DateTime YYYY-MM-DD HH:mm:ss | <p>Thời điểm kết thúc lọc dữ liệu<br><em>\* Mặc định thời điểm hiện tại</em></p>                                                            |
| phone\_no          | Varchar(12)                  | Số điện thoại gọi đến                                                                                                                       |
| line               | Varchar(12)                  | Đầu số gọi ra                                                                                                                               |
| lst\_data          | Array                        | Danh sách ID dữ liệu caresoft đã trả về qua API tạo cuộc gọi từ trước. Vd: \[1134,456,2233]                                                 |
| status\_code       | Int                          | Mã trạng thái thoại 200: Gọi thành công Các mã khác: Cuộc gọi không thành công                                                              |
| page               | Int                          | Trang số                                                                                                                                    |
| count              | Int                          | <p>Số bản ghi trên 1 trang. <br><em>\* Giới hạn tối đa 500</em></p>                                                                         |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "status": true,
    "data": {       
        "numFound": 6,
        "data": [
            {
                "id": 511,
                "called": "0983914980",
                "line": "842999999968",
                "start_time": "2020-04-21 10:41:50",
                "end_time": "2020-04-21 10:41:58",
                "status_code": 200,
                "connect_time": "2020-04-21 10:41:53",
                "call_duration": 5,
                "ring_customer_duration": 2,
                "ticket_id": null,
                "customer_user_id": 63150012,
                "account_id": 1,
                "call_attempt_total": 0,
                "campaign_id": 476,
                "customer_input_dtmf": null,...             

```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

Kết quả trả về&#x20;

| STT           | Tên trường         | Chú thích                                                                                                                                                                                                        |
| ------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p><br>1</p>  | Campaign\_name     | Tên chiến dich                                                                                                                                                                                                   |
| 2             | Created\_at        | Ngày tạo chiến dich                                                                                                                                                                                              |
| 3             | Updated\_at        | Ngày cập nhật chiến dịch                                                                                                                                                                                         |
| <p>4<br></p>  | Last\_run          | Thời điểm chạy chiến dịch gần nhất                                                                                                                                                                               |
| 5             | Schedule\_start    | Thời gian bắt đầu chạy chiến dịch                                                                                                                                                                                |
| 6             | Schedule\_stop     | Thời điểm kết thúc chiến dịch                                                                                                                                                                                    |
| 7             | Time\_frame\_start | Thời gian chạy chiến dịch(trong ngày)                                                                                                                                                                            |
| 8             | Time\_frame\_stop  | Thời gian dừng chiến dịch (trong ngày)                                                                                                                                                                           |
| 9             | Campaign\_status   | <p>Trạng thái chiến dịch</p><ol><li>Mới tạo</li><li>Đang review</li><li>Sẵn sàng để chạy</li><li>Đang chạy</li><li>Đã kết thúc</li></ol><p>      -1.    Lỗi</p>                                                  |
| <p>10<br></p> | Campaign\_type     | <p>Loại chiến dịch<br>AUTO\_CALL: Gọi tự động<br>PREDICTIVE\_CALL: Gọi predictive</p><p>PREVIEW\_CALL: Gọi chủ động</p>                                                                                          |
| <p><br>11</p> | Data {}            | Mảng Kết quả chiến dich ( [Chi tiết mảng này tham khảo API chi tiết thông tin cuộc gọi theo DataID](https://docs.google.com/document/d/19HZGYFJET-hYVwdgjwbWDcjd7llazsn_JrUVXPhaNDg/edit#heading=h.gmzzluvz1ze)) |
| <p>12<br></p> | numFound           | Số lượng khách hàng đã thực hiện gọi cho chiến dịch                                                                                                                                                              |

## 3. Kết quả chi tiết chiến dịch&#x20;

<mark style="color:green;">`GET`</mark> `/{domain}/api/v1/smartdialer/call-log-details`

Danh sách chi tiết các cuộc gọi phát sinh của chiến dịch (Bao gồm cả các cuộc gọi không thành công và gọi lại theo cấu hình&#x20;

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Params**&#x20;

{% hint style="info" %}
Tương tự [mục kết quả chiến dịch](#id-2.-ket-qua-cuoc-goi-chien-dich)
{% endhint %}

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "status": true,
    "data": {       
        "numFound": 6,
        "data": [
            {
                "id": 511,
                "called": "0983914980",
                "line": "842999999968",
                "start_time": "2020-04-21 10:41:50",
                "end_time": "2020-04-21 10:41:58",
                "status_code": 200,
                "connect_time": "2020-04-21 10:41:53",
                "call_duration": 5,
                "ring_customer_duration": 2,
                "ticket_id": null,
                "customer_user_id": 63150012,
                "account_id": 1,
                "call_attempt_total": 0,
                "campaign_id": 476,
                "customer_input_dtmf": null,
                "path": null,
                "path_download": null,   
                "call_attempt_index": 0,        
            "call_id": "20220707172702-DIALERGEVFF-387740",
            "ivr_list_id": null,
            "campaign_data_id": 206697139,
            
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

**Kết quả trả về**

| Trường                   | Định nghĩa                                                   | Ghi chú                                                                                                                                        |
| ------------------------ | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| id                       | ID tự tăng của bản ghi                                       |                                                                                                                                                |
| called                   | Số điện thoại khách hàng                                     |                                                                                                                                                |
| line                     | Số hotline (Đầu số)                                          |                                                                                                                                                |
| start\_time              | Thời điểm bắt đầu                                            |                                                                                                                                                |
| end\_time                | Thời điểm kết thúc                                           |                                                                                                                                                |
| status\_code             | Mã trạng thái cuộc gọi (sip code)                            | Ví dụ: 200, thành công, 408: Khách hàng tắt nguồn. 600: khách hàng bận không nghe máy...                                                       |
| connect\_time            | Thời điểm khách nhấc máy nghe cuộc gọi                       |                                                                                                                                                |
| call\_duration           | Thời lượng cuộc gọi                                          | (Giây)                                                                                                                                         |
| ring\_customer\_duration | Thời gian khách chờ bắt máy                                  | (Giây)                                                                                                                                         |
| ticket\_id               | ID phiếu ghi liên quan                                       | Trong trường hợp cuộc gọi có kết nối tới chuyên viên                                                                                           |
| customer\_user\_id       | ID khách hàng                                                |                                                                                                                                                |
| call\_attempt\_total     | Tổng số lần gọi thực hiện gọi khách                          | Trong 1 phiên nếu số lần gọi lại là 3 và cuộc gọi thứ 2 khách mới bắt máy thì số này thế hiện là 2                                             |
| campaign\_id             | ID chiến dịch                                                |                                                                                                                                                |
| customer\_input\_dtmf    | Dãy số mà khách hàng bấm vào trong lúc nghe cuộc gọi         |                                                                                                                                                |
| path                     | Đường dẫn file ghi âm (Dùng nghe trực tiếp trên trình duyệt) | Trong trường hợp cuộc gọi kết nối tới chuyên viên và phát sinh trao đổi, nội dung cuộc gọi sẽ được lưu lại sau khi kết thúc cuộc gọi vài phút. |
| path\_download           | Đường dẫn tải về file ghi âm                                 |                                                                                                                                                |
| call\_id                 | ID cuộc gọi                                                  |                                                                                                                                                |
| campaign\_data\_id       | ID dữ liệu chiến dịch phát sinh ra cuộc gọi                  |                                                                                                                                                |
|                          |                                                              |                                                                                                                                                |

## 4. Tạo mới cuộc gọi vào 1 chiến dịch đang có&#x20;

Các phương thức có thể đẩy dữ liệu vào 1 chiến dịch đang chạy để thực hiện cuộc gọi&#x20;

### 4.1 Đẩy dữ liệu theo [contact\_id](/danh-muc/restful-api-cua-caresoft/khach-hang#them-moi-khach-hang) trên CareSoft

<mark style="color:green;">`POST`</mark> `/{domain}/api/v1/campaign/data`

Thực hiện tạo cuộc gọi theo ID của khách hàng (ContactId) có trên CareSoft. Hệ thống sẽ lấy số điện thoại tồn tại trên ContactId để thực hiện cuộc gọi ra&#x20;

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Body** \
***SON format***

```json
{
  "campaign_id": 325,
  "contact_id": 2,
  "message": {
    "customerID": "09812212121",
    "name": "Nghia",
    "buy_date": "2018 july 20",
    "message": "Purchase success"
  }
}

```

| Name         | Type   | Description                            |
| ------------ | ------ | -------------------------------------- |
| campaign\_id | number | ID của chiến dịch ở bước 1             |
| contact\_id  | number | ID khách hàng trên CareSoft            |
| message      | String | Chuỗi nội dung tham số thay thế nếu có |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "status": true,
    "status_code": 200  
}
```

{% endtab %}

{% tab title="422" %}

```json
{
    "status": false,
    "status_code": 422,
    "data": {
        "campaign_id": 3225,
        "contact_id": 2,
        "paramsValue": {
            "phone": "09812212121",
            "name": "Nghia",
            "buy_date": "2018 july 20",
            "message": "Purchase success"
        }
    }
}

```

{% endtab %}
{% endtabs %}

### 4.2 Đẩy dữ liệu theo số điện thoại khách hàng

<mark style="color:green;">`POST`</mark> `/{domain}/api/v1/campaign/dataPhone`

Tạo cuộc gọi smartDialer theo số điện thoại của khách hàng. Trong trường hợp chưa tồn tại hệ thống sẽ tự tạo khách hàng tương ứng.&#x20;

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Body**\
***JSON Format***

```json
{
  "campaign_id": 325,
  "phone_no": "0971221122",
  "message": {
    "name": "Le Manh Hai",
    "buy_date": "2018 july 20",
    "message": "Purchase success"
  }
}
```

| Name         | Type    | Description                               |
| ------------ | ------- | ----------------------------------------- |
| campaign\_id | Int     | ID chiến dịch                             |
| phone\_no    | phoneNo | Số điện thoại của chiến dịch              |
| message      | Object  | Object chứa param thay thế của TTS nếu có |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "status": true,
  "status_code": 200
}
```

{% endtab %}

{% tab title="422" %}

```json
{
    "status": false,
    "status_code": 422,
    "data": {
        "campaign_id": 3225,
        "phone_no":”12”,
        "paramsValue": {
            "phone": "09812212121",
            "name": "Nghia",
            "buy_date": "2018 july 20",
            "message": "Purchase success"
        }
    }
}
```

{% endtab %}
{% endtabs %}

### 4.3 Đẩy dữ liệu theo email của khách hàng

<mark style="color:green;">`POST`</mark>  `/{domain}/api/v1/campaign/dataEmail`

Tạo cuộc gọi dựa theo email của khách hàng. Nếu trên hệ thống CareSoft tồn tại khách hàng trùng khớp với email truyền vào và khách đó có số điện thoại. hệ thống sẽ gọi ra theo số điện thoại tìm thấy theo kịch bản của chiến dịch.

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Body**\
***Json Format***

```json
{
  "campaign_id": 325,
  "email": "info@caresoft.vn",
  "message": {
    "name": "Nghia",
    "buy_date": "2018 july 20",
    "message": "Purchase success"
  }
}
```

| Name         | Type   | Description                                    |
| ------------ | ------ | ---------------------------------------------- |
| campaign\_id | Int    | ID chiến dịch                                  |
| `email`      | email  | Email của khách hàng                           |
| message      | Object | Các key thay thế của cuộc gọi TTS nếu cấu hình |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "status": true,
  "status_code": 200
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "status": false,
  "status_code": 422,
  "data": {
    "campaign_id": 3225,
    "email": "info@caresoft.vn",
    "paramsValue": {
      "phone": "09812212121",
      "name": "Nghia",
      "buy_date": "2018 july 20",
      "message": "Purchase success"
    }
  }
}
```

{% endtab %}
{% endtabs %}

### 4.4  Đẩy dữ liệu theo danh sách ID khách hàng&#x20;

<mark style="color:green;">`POST`</mark> `/{domain}/api/v1/campaign/dataMultiple`

Tạo hàng loạt cuộc gọi dựa theo 1 danh sách khách hàng có sẵn trên hệ thống CareSoft&#x20;

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Body**\
***Json Format***

```json
{
  "campaign_id": 325,
  "contact_id_list": [
    1000,
    10001,
    10002
  ],
  "message": {
    "contactid": "09812212121",
    "name": "Nghia",
    "buy_date": "2018 july 20",
    "message": "Purchase success"
  }
}
```

| Name              | Type   | Description                                                                                       |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------- |
| `campaign_id`     | Int    | ID chiến dịch                                                                                     |
| contact\_id\_list | Array  | Danh sách ID của khách hàng trên caresoft được tạo từ bước 3, dạng mảng array tối đa 1000 dữ liệu |
| message           | Object | Chuỗi thông tin dạng Json để có thể parse trong template TTS                                      |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "status": true,
  "extra": {
    "id_list": [
      {
        "campaign_data_id": 522228,
        "contact_id": 63204924
      },
      {
        "campaign_data_id": 522229,
        "contact_id": 63204925
      }
    ]
  }
}
```

{% endtab %}

{% tab title="422" %}

```json
{
  "status": false,
  "message": "Not found campaign ID or incompatible type of campaign:12122"
}
```

{% endtab %}
{% endtabs %}

### 4.5 Đẩy dữ liệu theo danh sách số điện thoại&#x20;

<mark style="color:green;">`POST`</mark> `/{domain}/api/v1/campaign/dataMultiplePhone`

Tạo cuộc gọi theo danh sách số điện thoại

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Body**\
***JSON Format***

```json
{ "campaign_id": 521, "phone_no_list": [ "0971221122", "0971221123" ] }
```

| Name            | Type  | Description                   |
| --------------- | ----- | ----------------------------- |
| campaign\_id    | Int   | ID chiến dịch                 |
| phone\_no\_list | Array | Mảng số điện thoại khách hàng |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "status": true,
    "extra": {
        "id_list": [
            {
                "phone_no": "0971221122",
                "campaign_data_id": 522224,
                "contact_id": 63204924
            },
            {
                "phone_no": "0971221123",
                "campaign_data_id": 522225,
                "contact_id": 63204925
            }
        ]
    }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

### 4.6  Đẩy dữ liệu theo danh sách email&#x20;

<mark style="color:green;">`POST`</mark> `/{domain}/api/v1/campaign/dataMultipleEmail`

Tạo cuộc gọi theo danh  sách email (Nếu đã có contact ID trên CareSoft và các contact đó có dữ liệu)

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Body**

| Name          | Type  | Description     |
| ------------- | ----- | --------------- |
| `campaign_id` | Int   | ID chiến dịch   |
| email\_list   | Array | Danh sách Email |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "status": true,
    "extra": {
        "id_list": [
            {
                "campaign_data_id": 522226,
                "contact_id": 63155193,
                "email": "info@caresoft.vn"
            },
            {
                "campaign_data_id": 522227,
                "contact_id": 63204926,
                "email": "info2@caresoft.vn"
            }
        ]
    }
}

```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}


# QA

Lấy danh sách các đối tượng  được chấm điểm QA

### Lấy danh sách các đối tượng được đánh giá QA

<mark style="color:green;">`GET`</mark> `/{{domain}}/api/v1/qa-results`

Danh sách các phiếu ghi /Lead/Deal đã được chấm điểm QA.&#x20;

**Headers**

| Name          | Value                                                                             |
| ------------- | --------------------------------------------------------------------------------- |
| Content-Type  | `application/json`                                                                |
| Authorization | `Bearer` [`<token>`](/thong-tin-chung#cach-lay-api-token-tren-giao-dien-caresoft) |

**Parameter**

<table><thead><tr><th width="291">Name</th><th width="184">Type</th><th>Description</th></tr></thead><tbody><tr><td>updated_since</td><td>DateTime Định dạng  (YYYY-mm-ddTHH:mm:ssZ)</td><td>Cập nhật từ ngày (Mặc định từ đầu tháng hiện tại)</td></tr><tr><td>updated_to</td><td>DateTime Định dạng  (YYYY-mm-ddTHH:mm:ssZ)</td><td>Cập nhật đến ngày(Mặc định ngày hiện tại)</td></tr><tr><td>qa_agent</td><td>Int</td><td>ID chuyên viên  QA  (<a href="/danh-muc/restful-api-cua-caresoft/chuyen-vien">Danh sách</a>)</td></tr><tr><td>script_id</td><td>Int</td><td>ID kịch bản </td></tr><tr><td>page</td><td>Int</td><td>Mặc định: 1</td></tr><tr><td>count</td><td>Int</td><td>Mặc định: 50, Tối đa: 500</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "code": "ok",
    "numFound": 2,
    "results": [
        {
            "id": 414856113,
            "qa_lead_id": null,
            "is_agree": null,
            "created_at": "2024-09-13 13:44:33",
            "updated_at": "2024-09-13 13:44:33",
            "agent_comment": null,
            "qa_lead_comment": null,
            "qa_agent": 63204887,
            "qa_script_id": 429,
            "qa_script_name": "0612 QAv2",
            "ticket_created_at": "2024-03-26 14:48:15",
            "ticket_updated_at": "2024-03-26 14:48:17",
            "assignee_id": 63150156,
            "requester_id": 63216571,
            "type": 0,
            "duedate": null
        },
        {
            "id": 414954039,
            "qa_lead_id": null,
            "is_agree": 0,
            "created_at": "2024-09-12 17:14:59",
            "updated_at": "2024-09-12 17:15:40",
            "agent_comment": null,
            "qa_lead_comment": null,
            "qa_agent": 63155144,
            "qa_script_id": 429,
            "qa_script_name": "0612 QAv2",
            "ticket_created_at": "2024-09-12 15:22:59",
            "ticket_updated_at": "2024-09-12 18:11:13",
            "assignee_id": 29371047,
            "requester_id": 63217768,
            "type": 0,
            "duedate": null
        }
    ]
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

**Chú thích thông tin dữ liệu trả về**

{% hint style="info" %}
Dữ liệu trả về mặc định sắp xếp theo ngày cập nhật của kết quả QA (<mark style="color:orange;">updated\_at</mark> ) từ gần ngày hiện tại  nhất&#x20;
{% endhint %}

<table><thead><tr><th width="198">Trường dữ liêu</th><th width="131">Kiểu dữ liệu</th><th width="225">Diễn giải</th><th>Ghi chú</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>Trạng thái thành công</td><td>giá trị: ok, errors</td></tr><tr><td>numFound</td><td>Int</td><td>Số lượng bản ghi tìm được</td><td></td></tr><tr><td>results</td><td>ArrayObjects</td><td>Mảng Object dữ liệu các đối tượng đã QA</td><td></td></tr><tr><td>... {chi tiết object}...</td><td></td><td></td><td></td></tr><tr><td>id</td><td>Int</td><td>ID phiếu ghi/lead/deal tương ứng</td><td>Sử dụng hàm lấy <a href="/danh-muc/restful-api-cua-caresoft/phieu-ghi">chi tiết phiếu ghi </a>kèm theo ID này để lấy chi tiết thông tin được QA </td></tr><tr><td>qa_lead_id</td><td>Int</td><td>ID của QA Lead </td><td>Danh sách chuyên viên có thể truy xuất tại <a href="/danh-muc/restful-api-cua-caresoft/chuyen-vien">đây </a></td></tr><tr><td>is_agree</td><td>Int</td><td>Trạng thái đồng ý với QA</td><td>0: Không đồng ý<br>1: Đồng ý<br>null: Chưa đánh giá</td></tr><tr><td>created_at</td><td>DateTime</td><td>Ngày chấm QA</td><td></td></tr><tr><td>updated_at</td><td>DateTime</td><td>Thời điểm cập nhật QA</td><td></td></tr><tr><td>agent_comment</td><td>String</td><td>Ý kiến của chuyên viên</td><td></td></tr><tr><td>qa_lead_comment</td><td>String</td><td>Ý kiến của QA Lead</td><td></td></tr><tr><td>qa_agent</td><td>Int</td><td>ID của chuyên viên QA</td><td>Danh sách chuyên viên có thể truy xuất tại <a href="/danh-muc/restful-api-cua-caresoft/chuyen-vien">đây </a></td></tr><tr><td>qa_script_name</td><td>String</td><td>Tên kịch bản QA </td><td></td></tr><tr><td>qa_script_id</td><td>Int</td><td>ID của Kịch bản QA</td><td></td></tr><tr><td>ticket_created_at</td><td>DateTime</td><td>Ngày tạo phiếu ghi/lead/deal</td><td></td></tr><tr><td>ticket_updated_at</td><td>DateTime</td><td>Thời điểm cập nhật phiếu ghi/lead/Deal</td><td></td></tr><tr><td>assignee_id</td><td>Int</td><td>ID Chuyên viên </td><td>Danh sách chuyên viên có thể truy xuất tại <a href="/danh-muc/restful-api-cua-caresoft/chuyen-vien">đây </a></td></tr><tr><td>requester_id</td><td>Int</td><td>ID khách hàng</td><td>Chi tiết khách hàng  xem thêm tại <a href="/danh-muc/restful-api-cua-caresoft/khach-hang#chi-tiet-khach-hang">đây</a></td></tr><tr><td>duedate</td><td>DateTime</td><td>Thời hạn xử lý </td><td></td></tr><tr><td>type</td><td>Int</td><td>Loại đối tượng dữ liệu</td><td>0: Phiếu ghi<br>1:  Lead<br>2: Deal</td></tr></tbody></table>


# Trạng thái hệ thống

Endpoint cung cấp trạng thái hiện thời của tất cả dịch vụ CareSoft được giám sát. Dữ liệu đã được gộp & rút gọn, sẵn sàng cho hệ thống giám sát của khách hàng.

<mark style="color:green;">`GET`</mark> `/`**`https://status.caresoft.vn/api/v1/heartbeat`**

Endpoint cung cấp trạng thái hiện thời của tất cả dịch vụ CareSoft được giám sát.

### 1. Yêu cầu (HTTP Request)

<table><thead><tr><th width="231.29296875">Thuộc tính</th><th>Giá trị</th></tr></thead><tbody><tr><td><strong>Phương thức</strong></td><td><code>GET</code></td></tr><tr><td><strong>Đường dẫn</strong></td><td><code>https://status.caresoft.vn/api/v1/heartbeat</code></td></tr><tr><td><strong>Tham số query</strong></td><td><code>pretty</code> (tùy chọn) – trả JSON có thụt dòng (dễ đọc thủ công).</td></tr><tr><td><strong>Header</strong></td><td>Không bắt buộc</td></tr></tbody></table>

**Ví dụ**

<pre><code><strong>GET https://status.caresoft.vn/api/v1/heartbeat
</strong></code></pre>

### 2. Phản hồi (HTTP Response)

#### 2.1. Mã trạng thái

| Mã              | Ý nghĩa                          |
| --------------- | -------------------------------- |
| 200 OK          | Thành công & trả về JSON hợp lệ. |
| 502 Bad Gateway | Dữ liệu tạm thời chưa có.        |

#### 2.2. Headers nổi bật

| Header              | Kiểu                | Mô tả                                         |
| ------------------- | ------------------- | --------------------------------------------- |
| `Content-Type`      | `application/json`  | Luôn là JSON UTF‑8.                           |
| `X-Cache-Generated` | `RFC3339 timestamp` | Thời điểm dữ liệu vừa được hệ thống tổng hợp. |

#### 2.3. Nội dung (JSON)

```jsonc
{
  "generated_at": "2025-07-21 12:15:03",
  "title": "CareSoft",
  "monitors": [
    {
      "id": 1,
      "name": "WEB_APP V2",
      "status": 1,
      "last_ping_ms": 29,
      "last_heartbeat": "2025-07-21 05:06:51.208",
      "uptime_24h": 1.0
    }
    /* …các monitor khác (nếu có) … */
  ]
}
```

| Trường           | Kiểu                         | Giải thích                                           |
| ---------------- | ---------------------------- | ---------------------------------------------------- |
| `generated_at`   | `string`                     | Thời điểm hệ thống tạo bản ghi này.                  |
| `title`          | `string`                     | Tên cụm dịch vụ.                                     |
| `monitors`       | `array<Monitor>`             | Danh sách tất cả dịch  vụ đang public giám sát.      |
| `id`             | `int`                        | Định danh dịch vụ.                                   |
| `name`           | `string`                     | Tên thân thiện của dịch vụ.                          |
| `status`         | `int` (`1` = UP, `0` = DOWN) | Trạng thái mới nhất.                                 |
| `last_ping_ms`   | `int`                        | Thời gian phản hồi (millisecond) của heartbeat cuối. |
| `last_heartbeat` | `string`                     | Thời điểm heartbeat cuối (theo múi giờ server).      |
| `uptime_24h`     | `float` (0 – 1)              | Tỉ lệ uptime 24 giờ qua (1 = 100%).                  |

### 3. Ví dụ sử dụng

#### 3.1. cURL

```bash
curl https://status.caresoft.vn/api/v1/heartbeat | jq .
```

#### 3.2. JavaScript

```js
fetch('https://status.caresoft.vn/api/v1/heartbeat')
  .then(r => r.json())
  .then(({ monitors }) => {
    monitors.forEach(m => {
      console.log(`${m.name}: ${m.status ? 'UP ✅' : 'DOWN ❌'} (${m.last_ping_ms}ms)`);
    });
  });
```

### 4. Cập nhật API

| Phiên bản     | Thay đổi           |
| ------------- | ------------------ |
| 1.0 (07‑2025) | Phát hành lần đầu. |


# Tạo phiếu ghi/lead/deal kèm thông tin trường động

Hướng dẫn tạo phiếu ghi kèm giá trị của trường động phiếu ghi.

**Bài toán:**  Nhu cầu tích hợp CareSoft vào website bán hàng Online. Trong đó khi phát sinh đơn hàng, thì tạo phiếu ghi. và gán phân loại đơn hàng là "mới" kèm giá trị đơn hàng là tổng tiền của đơn hàng trên CRM&#x20;

Trên cấu hình trường động phiếu ghi, đã cấu hình 2 trường dữ liệu gồm:\
\- Trạng thái Đơn Hàng-  Chọn 1 trong các giá trị: Mới tạo, Đã Xuất Kho, Đã Giao Hàng, Hủy đơn\
\- Giá trị đơn hàng: - Kiểu số&#x20;

### Chuẩn bị

1. Gọi API lấy trường động dữ liệu phiếu ghi, xem tại [Trường động (Custom fields)](/thong-tin-chung/truong-dong-custom-fields) có giá trị như sau  (Dữ liệu mô phỏng)   \
   **GET**: `{{domain}}/api/v1/tickets/custom_fields`

{% code title="Dữ liệu mô phỏng giá trị trường động" %}

```json
{
    "code": "ok",
    "custom_fields": [
        {
            "custom_field_id": 6416,
            "code":"TRANGTHAIDONHANG",
            "custom_field_lable": "Trạng thái đơn hàng",
            "type": "Single drop-down list",
            "values": [
                {
                    "id": 90923,
                    "label": "Mới",
                    "code":"12ABC",
                    "parent_value_id": -1
                },
                {
                    "id": 90924,
                    "label": "Đã xuất kho",
                    "code":"XUATKHO",
                    "parent_value_id": -1
                },
                {
                    "id": 90925,
                    "label": "Đã giao hàng",
                    "code":"DAGIAO",
                    "parent_value_id": -1
                }
            ]
        },
        {
            "custom_field_id": 6422,
            "code":"GIATRI",
            "custom_field_lable": "Giá trị đơn hàng",
            "type": "Numeric"
        }
    ]
} 
```

{% endcode %}

2. Tạo 1 bảng mapping thông tin  custom\_field\_id  với các trường thông tin tương ứng trên CRM

### Thực hiện

1. Tạo phiếu ghi khi có đơn hàng mới. Tình huống giả định: Anh Nam mua điện thoại có giá trị 5.000.000 đ\
   \
   Tạo object phiếu ghi để thực hiện tạo mới bằng cách gọi tới api \
   **POST**: `{{domain}}/api/v1/tickets`<br>

   <pre class="language-json" data-title="Click vào từng giá trị để xem thông tin" data-overflow="wrap"><code class="lang-json">{
       "ticket": {
           "phone": "09****0148",
           "username": "Anh Nam",
           "service_id": 12,
           "<a data-footnote-ref href="#user-content-fn-1">ticket_subject</a>": "Đơn hàng #122211",
           "ticket_comment": "Khách đặt 3 iphone",
           "is_public": 0,
           "custom_fields": [
               {
                   "id": "<a data-footnote-ref href="#user-content-fn-2">6416</a>",
                   "value": "<a data-footnote-ref href="#user-content-fn-3">90923</a>" 
               },
               {
                   "id": "<a data-footnote-ref href="#user-content-fn-4">6422</a>",
                   "value": "<a data-footnote-ref href="#user-content-fn-5">5000000</a>"
               }
           ]
       }
   }
   </code></pre>

\
Hoặc theo Code trường động

```json
{
    "ticket": {
        "phone": "09****0148",
        "username": "Anh Nam",
        "service_id": 12,
        "ticket_subject": "Đơn hàng #122211",
        "ticket_comment": "Khách đặt 3 iphone",
        "is_public": 0,
        "custom_fields": [
            {
                "code": "TRANGTHAIDONHANG",
                "value_code": "DAXUATKHO" 
            },
            {
                "code": "GIATRI",
                "value": "5000000"
            }
        ]
    }
}
```

Mô phỏng Postman tạo phiếu ghi

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FiJ1y9pbWdSjnfCvk42XB%2FTaoMoiPhieuGhiWTruongDong.png?alt=media&amp;token=623d48a4-4b53-4e81-b58e-1d11090c54bd" alt=""><figcaption><p>Lưu lại ticketId để thực hiện cập nhật phiếu ghi ở tiến trình tiếp theo </p></figcaption></figure>

Kết quả hiển thị trên giao diện CareSoft.

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FISW4sNcYUnf1SZyABo5h%2FCS.png?alt=media&amp;token=1bf06cb6-c280-4b82-88e1-ee5783351086" alt=""><figcaption></figcaption></figure>

Để cập nhật thêm trạng thái xem thêm ở [Phiếu ghi](/danh-muc/restful-api-cua-caresoft/phieu-ghi)

> Đối với các tác vụ tạo lead/deal thực hiện thay đổi lại endpoint, object  và làm tương tự.&#x20;

[^1]: Chủ đề phiếu ghi sử dụngt

[^2]: ID của trường "Trạng thái đơn hàng"

[^3]: ID của giá trị phân loại **"Mới"** của trường **"Trạng thái đơn hàng"**

[^4]: ID của trường **Giá trị đơn hàng**

[^5]: Số tiền giá trị đơn hàng từ CRM đẩy trực tiếp sang


# Tích hợp thoại

Tài liệu tích hợp gọi điện thoại trực tiếp từ website/Ứng dụng của khách hàng sử dụng nền tảng của CareSoft

Tham khảo các tài liệu phía dưới để tìm giải pháp phù hợp với yêu cầu của bạn&#x20;

{% content-ref url="/pages/DzJJRSZW7ODXYTDiEbJU" %}
[Tích hợp kênh thoại trên ứng dụng mobile](/danh-muc/tich-hop-thoai/tich-hop-kenh-thoai-tren-ung-dung-mobile)
{% endcontent-ref %}

{% content-ref url="/pages/xdIfdpnwJ7BECEZdJU5O" %}
[Tích hợp gọi ra sử dụng Click to call trên web](/danh-muc/tich-hop-thoai/tich-hop-goi-ra-su-dung-click-to-call-tren-web)
{% endcontent-ref %}

{% content-ref url="/pages/enBo4CwB3sZeGbDR6AoR" %}
[Tích hợp kênh thoại trên ứng dụng Web (Voice API)](/danh-muc/tich-hop-thoai/tich-hop-kenh-thoai-tren-ung-dung-web-voice-api)
{% endcontent-ref %}


# Danh sách dịch vụ gọi ra

API lấy danh sách các dịch vụ gọi ra được tích hợp trên nền tảng Caresoft

## Danh sách dịch vụ gọi ra

<mark style="color:green;">`GET`</mark> `/{domain}/api/v1/service/callouts`

Toàn bộ các dịch vụ gọi ra được tích hợp trên CareSoft bao gồm cả Zalo ZCC  và các đầu số dịch vụ thoại thông thường.&#x20;

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "code": "ok",
  "data": [
    {
      "callout_id": 2006581,
      "description": "098****112",
      "service_type": 1,
      "callout_type": 0,
      "page_id": null
    },
    {
      "callout_id": 2006582,
      "description": "Vinaphone- 091****222",
      "service_type": 2,
      "callout_type": 3,
      "page_id": null
    },
    {
      "callout_id": 2006824,
      "description": "ZCC Casper",
      "service_type": 1,
      "callout_type": 1,
      "page_id": "2976478350661937291"
    }
  ]
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

**Mô tả dữ liệu**

| Param         | Ý nghĩa                                                 | Ghi chú                                                     |
| ------------- | ------------------------------------------------------- | ----------------------------------------------------------- |
| callout\_id   | ID đầu số gọi ra                                        |                                                             |
| description   | Tên đầu số (Số Hotline hoặc tên Zalo OA gọi ZCC)        |                                                             |
| service\_type | Kiểu dữ liệu khi phát sinh                              | <p>1: Ticket<br>2: Lead<br>3: Deal </p>                     |
| callout\_type | Loại đầu số                                             | <p>0: Đầu số thường<br>1: Đầu số gọi ra Zalo<br>3: Nhóm</p> |
| page\_id      | ID của OA zalo trong trường hợp đầu số là loại Zalo ZCC |                                                             |


# Tích hợp kênh thoại trên ứng dụng Web (Voice API)

Giải pháp tích hợp kênh thoại trên ứng dụng Web, bao gồm cả luồng gọi vào và gọi ra.

* Hỗ trợ các loại ứng dụng web (web app) tích hợp tổng đài thoại CareSoft.
* Người dùng (user) của doanh nghiệp có thể thực hiện việc tiếp nhận cuộc gọi hay gọi điện ra ra cho khách hàng thông qua số hotline CareSoft.
* Popup thông tin khách hàng khi có cuộc gọi đến
* Công nghệ sử dụng WebRTC không cần cài đặt thêm phần mềm nghe gọi điện.
* Hỗ trợ tích hợp với các thiết bị nghe gọi như IP Phone, Softphone

## Chuẩn bị thông tin

1. Lấy mã xác thực từ giao diện admin  CareSoft. \
   Truy cập vào CareSoft bằng tài khoản admin mà CareSoft cấp cho khách hàng.&#x20;
2. Tại menu Admin --> Api --> Api Token. \
   \
   Ở dòng **Token voice api hiện tại** chọn **Tạo token mới**  nếu chưa có hoặc **Copy**  nếu đã có và lưu lại thành 1 cấu hình `{{apiVoiceAccessToken}}`&#x20;

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FB1jLabwd54SvgAuhDweM%2FAPI_VOICE_TOKEN.png?alt=media&amp;token=25a903fa-0415-4031-bbf5-94a19661bb1e" alt=""><figcaption></figcaption></figure>

3. Thư viện JWT phù hợp với ngôn ngữ lập trình của bạn để tạo mã token cho mỗi cuộc gọi. Xem thêm ở  [www.jwt.io](https://jwt.io/)

{% hint style="info" %}
**LƯU Ý:** Khi  bấm nút tạo mới hệ thống sẽ thay thế `apiVoiceAccessToken`cũ bằng `apiVoiceAccessToken` mới khiến các ứng dụng đang tích hợp sẽ mất quyền truy cập.  Vui lòng cập nhật token ở các ứng dụng theo token mới nếu bạn bấm "Tạo token mới" để đảm bảo hệ thống hoạt động liền mạch&#x20;
{% endhint %}

## Cách thức tích hợp

1. Chuẩn bị payload để tạo mã token cuộc gọi

```json
{
  "ipphone": "{{agent_id}}",
  "expired": "2017-07-30 00:00:00"
}
```

**Trong đó:**&#x20;

* `IpPhone` Là số Iphone của Chuyên viên tương ứng (Xem thêm thông tin chuyên viên  ở [Chuyên viên](/danh-muc/restful-api-cua-caresoft/chuyen-vien))
* `expired` Thời hạn hết hạn của token

2. Lập trình với thư viện JWT để tạo ra chuỗi token  trong hình dưới là cách thức gen  token sử dụng trực tiếp từ trang web jwt.io.  Xem các hướng dẫn và thư viện tương thích trong mục "[Libraries](https://jwt.io/libraries)" của JWT&#x20;

*Ví dụ: Tạo chuỗi token đăng nhập vào hệ thống Caresoft sử dụng giao diện JWT.io*

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FrilrknHfyUk8ntczUJL5%2FJWT_voice.png?alt=media&amp;token=b2ff5c3d-c0d2-4617-b83e-20dde3783e5e" alt=""><figcaption></figcaption></figure>

Copy chuỗi token JWT lưu thành biến {{token}} \
Ví dụ ở trường hợp trên sẽ là  `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....e_ZYyfTxg3EDG6vrKxhbZXPx9tQXrLcB5o`

3. Sau khi gen token, CRM gọi  API service bên dưới để login vào Caresoft để đăng ký token với hệ thống.&#x20;

{% code title="Payload body đăng nhập" %}

```json
 {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.....g3EDG6vrKxhbZXPx9tQXrLcB5o"
  }
```

{% endcode %}

## Đăng nhập VoiceAPI

<mark style="color:green;">`POST`</mark> `https://capi.caresoft.vn/{domain}/thirdParty/login`

#### Request Body

| Name                                    | Type   | Description                             |
| --------------------------------------- | ------ | --------------------------------------- |
| token<mark style="color:red;">\*</mark> | String | {{token}}  Chuỗi token nhận được ở trên |

{% tabs %}
{% tab title="200: OK Thành công" %}

```json
{
    "code": "ok",
    "user": {
        "accountId": 1223,
        "account_id": 1223,
        "userId": "1",
        "email": "sample@gmail.com",
        "name": "Sale Department",
        "username": "Sale Department",
        "agentId": "5000",
        "agent_id": "5000",
        "phone_no": "0864894596",
        "ipAddress": "222.252.98.36",
        "groupId": "10001",
        "role": "1",
        "active": "1"
    }
}
```

{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="400: Bad Request " %}

{% endtab %}

{% tab title="500: Internal Server Error " %}

{% endtab %}
{% endtabs %}

Mẫu minh họa gọi hàm login từ postman

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FxKLWnUnM4qKnnOKyCPa1%2FLogin.png?alt=media&amp;token=926c49a3-337d-452e-9b1e-39cb1da65129" alt=""><figcaption></figcaption></figure>

### Lập trình tích hợp tiếp nhận cuộc gọi CareSoft vào CRM

{% hint style="info" %}
**Chú ý:** Nếu bạn lập trình trên localhost, cài extension "Allow Cross Domain" trên Chrome để không bị lỗi Cross Domain.
{% endhint %}

* Import các lib javascript đã được CareSoft cung cấp sẵn vào CRM (trong đó custom.js là file js chứa các hàm CareSoft định nghĩa sẵn để hỗ trợ thông báo, xử lý giao diện, tương tác tuỳ theo nhu cầu của từng CRM)

  ```
  	<script src="https://capi.caresoft.vn/js/embed/jquery.min.js" type="text/javascript"></script>    
  	<script src="https://capi.caresoft.vn/js/embed/jssip-3.2.10.js" type="text/javascript"></script>
  	<script src="https://capi.caresoft.vn/js/embed/init-3.0.7.js" type="text/javascript"></script>
  	<script src="https://capi.caresoft.vn/js/embed/web.push.js" type="text/javascript"></script>
  	<script src="https://capi.caresoft.vn/js/embed/cs_const.js" type="text/javascript"></script>
  	<script src="https://capi.caresoft.vn/js/embed/cs_voice.js" type="text/javascript"></script>
  	<script src="custom.js" type="text/javascript"></script>
  ```
* Copy dòng sau giữa thẻ body:

  ```
  	<video id="my-video" style="display: none;" autoplay playsinline muted></video>
  	<video id="peer-video" style="display: none;" autoplay playsinline></video>
  ```
* Thực hiện việc kết nối với tổng đài CareSoft qua hàm sau:

  ```
    csInit(token, domain);
  ```

Trong đó token là token đã được tạo ra ở bước 1

* Tại một thời điểm, chỉ 1 tab có quyền gọi và tiếp nhận cuộc gọi. Để cho 1 tab bật quyền tiếp nhận cuộc gọi, gọi hàm **csEnableCall();**
* Hệ thống hỗ trợ 2 loại thiết bị nghe gọi:
* Nghe gọi trên trình duyệt
* Nghe gọi qua softphone, IP Phone

Tuỳ thuộc vào loại thiết bị sẽ sử dụng mà chọn thiết bị bằng cách gọi hàm sau:

```
         changeDevice(type);
```

Trong đó: \
\-  `type = 1`: nghe gọi trên trình duyệt \
\- `type = 2`: nghe gọi qua softphone, IP Phone

Trong trường hợp muốn tắt trình duyệt đi mà vẫn tiếp nhận được cuộc gọi qua ipphone/softphone, chuyển `type = 4`.

Trong trường hợp muốn tắt trình duyệt đi mà vẫn tiếp nhận được cuộc gọi qua GSM, chuyển \
`type = 3` và truyền vào số điện thoại di động sẽ tiếp nhận cuộc gọi.

```
           changeDevice(3, '093xxxxxxxx');
```

Sau khi F5, hoặc đăng xuất, không sử dụng nữa thì phải huỷ đăng ký gọi và chuyển về thiết bị gọi mặc định để có thể tiếp tục sử dụng bình thường bằng cách sử dụng đoạn code sau:

```
          $(window).bind('unload', function () {
             csUnregister();
                 if (csVoice.enableVoice) {
                         reConfigDeviceType();
                 }
            });
```

Sau khi kết nối thành công với tổng đài, ngay lúc này đã có thể nhận và gọi điện tới khách hàng. Các hàm dùng để tương tác với hệ thống:

<table><thead><tr><th width="79.33333333333331">STT</th><th width="330">Hàm</th><th>Mô tả</th></tr></thead><tbody><tr><td>1</td><td><code>csEnableCall();</code></td><td>CareSoft chỉ cho phép tại 1 thời điểm có 1 tab được quyền gọi. Vì thế nếu bật nhiều tab hoặc đăng nhập tại nhiều nơi thì cũng chỉ có duy nhất 1 tab được sử dụng chức năng thoại. Tab đầu tiên đăng nhập vào hệ thống sẽ có quyền thoại này. Các tab về sau muốn dùng thì sử dụng hàm này</td></tr><tr><td>2</td><td><code>changeCallStatus();</code></td><td>CareSoft có hỗ trợ trạng thái tiếp nhận cuộc gọi là On/Off. Nếu để trạng thái là On thì cuộc gọi sẽ đổ về. Ngược lại thì sẽ không đổ về. Để chuyển qua lại 2 trạng thái thì sẽ dùng hàm này</td></tr><tr><td>3</td><td><code>csCallout(number,calloutId);</code></td><td>Gọi điện thoại tới số điện thoại của khách hàng (<code>number</code>là số điện thoại cần gọi, <code>calloutId</code> là id dịch vụ gọi ra (optional, nếu không truyền vào sẽ gọi theo dịch vụ mặc định))</td></tr><tr><td>4</td><td><code>onAcceptCall();</code></td><td>Tiếp nhận cuộc gọi đến</td></tr><tr><td>5</td><td><code>endCall();</code></td><td>Kết thúc cuộc gọi</td></tr><tr><td>6</td><td><code>holdCall();</code></td><td>Hold/Unhold cuộc gọi</td></tr><tr><td>7</td><td><code>muteCall();</code></td><td>Mute/Unmute cuộc gọi. Sự kiện này được gọi khi cuộc gọi bị Mute. Hàm này chỉ hoạt động cho cuộc gọi nhận từ khách hàng, không hoạt động cho cuộc gọi ra</td></tr><tr><td>8</td><td><code>changeDevice(type)</code></td><td>Thay đổi thiết bị tiếp nhận cuộc gọi</td></tr><tr><td>9</td><td><code>reConfigDeviceType()</code></td><td>Đối với nhân viên có vai trò Extension, Mobile, Softphone, khi đăng nhập vào để gọi điện sẽ gây bất đồng bộ khiến không thể tiếp nhận cuộc gọi trên các thiết bị mặc định được nữa. Gọi hàm này khi đăng xuất hoặc F5 web tích hợp để chuyển thiết bị nhân viên này về mặc định và tiếp nhận cuộc gọi như bình thường</td></tr><tr><td>10</td><td><code>getTransferAgent()</code></td><td>Lấy thông tin agent đang online</td></tr><tr><td>11</td><td><code>csTransferCallAgent(ipphone)</code></td><td>Chuyển cuộc gọi qua agent khác, <code>ipphone</code> số ipphone của agent muốn chuyển,Chú ý: agent phải đang trong cuộc gọi mới có thể chuyển cuộc gọi</td></tr><tr><td>12</td><td><code>csTransferCallAcd(queueId)</code></td><td>Chuyển cuộc gọi qua nhánh acd khác, <code>queueId</code> id của nhánh acd muốn chuyển,Chú ý: agent phải đang trong cuộc gọi mới có thể chuyển cuộc gọi</td></tr><tr><td>13</td><td><code>responseTransferAgent(action)</code></td><td>Tiếp nhận cuộc gọi được chuyển,<code>action=1</code> đồng ý,<code>action=0</code> từ chối</td></tr><tr><td>14</td><td><code>transferSurvey(survey)</code></td><td><p>Chuyển cuộc gọi sang khảo sát (after call survey). Chỉ hoạt động khi đang trong cuộc gọi và sau khi chuyển thành công cuộc gọi sẽ ngắt. <br>survey : <code>{</code></p><p><code>id: id của survey,</code></p><p><code>sipurl : sipurl</code></p><p><code>}</code></p></td></tr></tbody></table>

> Ngoài ra, khi muốn thay đổi giao diện hoặc xử lý thông tin mỗi khi có một sự kiện của cuộc gọi, CareSoft hỗ trợ các hàm sau

{% hint style="info" %}
**Chú ý:** Tất cả các hàm dưới đây đều phải được implement để đảm bảo tính đúng đắn của chương trình
{% endhint %}

<table><thead><tr><th width="98">STT</th><th width="284">Hàm</th><th>Mô tả</th></tr></thead><tbody><tr><td>1</td><td><code>csCallRinging(phone)</code></td><td>Sự kiện này được gọi khi có cuộc gọi đến nhân viên (phone là số điện thoại gọi đến)</td></tr><tr><td>2</td><td><code>csAcceptCall();</code></td><td>Sự kiện này được gọi khi nhân viên tiếp nhận cuộc gọi</td></tr><tr><td>3</td><td><code>csEndCall();</code></td><td>Sự kiện này được gọi khi cuộc gọi kết thúc.</td></tr><tr><td>4</td><td><code>csMuteCall();</code></td><td>Sự kiện này được gọi khi cuộc gọi bị Mute. Hàm này chỉ hoạt động cho cuộc gọi nhận từ khách hàng, không hoạt động cho cuộc gọi ra</td></tr><tr><td>5</td><td><code>csUnMuteCall();</code></td><td>Sự kiện này được gọi khi cuộc gọi bị unMute. Hàm này chỉ hoạt động cho cuộc gọi nhận từ khách hàng, không hoạt động cho cuộc gọi ra</td></tr><tr><td>6</td><td><code>csHoldCall();</code></td><td>Sự kiện này được gọi khi cuộc gọi bị Hold</td></tr><tr><td>7</td><td><code>csUnHoldCall();</code></td><td>Sự kiện này được gọi khi cuộc gọi bị UnHold</td></tr><tr><td>8</td><td><code>showCalloutInfo(number)</code></td><td>Sự kiện này được gọi khi có nhân viên gọi ra ngoài cho khách hàng (number là số gọi đi)</td></tr><tr><td>9</td><td><code>showCalloutError(errorCode, sipCode)</code></td><td>Sự kiện này được gọi khi có xảy ra lỗi lúc gọi đến khách hàng (errorCode, sipCode sẽ được mô tả trong bảng dưới)</td></tr><tr><td>10</td><td><code>csShowEnableVoice(isEnable)</code></td><td>Sự kiện này xảy ra khi một tab này được kích hoạt hay bị tắt chức năng thoại</td></tr><tr><td>11</td><td><code>csShowCallStatus(status)</code></td><td>Sự kiện này xảy ra khi trạng thái cuộc gọi bị thay đổi</td></tr><tr><td>12</td><td><code>csCustomerAccept()</code></td><td>Sự kiện này được gọi khi khách hàng nghe cuộc gọi đối với cuộc gọi ra</td></tr><tr><td>13</td><td><code>csShowDeviceType(type)</code></td><td>Sự kiện này được gọi khi thông tin loại thiết bị đang dùng để tiếp nhận cuộc gọi thay đổi (1: gọi bằng trình duyệt, 2: nhận cuộc gọi qua IP phone nhưng phải đăng nhập vào mới tiếp nhận được, 4: nhận cuộc gọi qua IP phone nhưng không cần đăng nhập vào)</td></tr><tr><td>14</td><td><code>csCurrentCallId(callId)</code></td><td>Sự kiện xảy ra khi có cuộc gọi đang diễn ra và trả về callId của cuộc gọi</td></tr><tr><td>15</td><td><code>csInitError(errorCode)</code></td><td>Sự kiện này xảy ra khi thiết lập thông số không thành công và sẽ trả về mã lỗi(token lỗi, lỗi kết nối,…)</td></tr><tr><td>16</td><td><code>csInitComplete()</code></td><td>Sự kiện được gọi khi thiết lập thành công mọi thông số và đã sẵn sang để bắt đầu nhận hay tiếp nhận cuôc gọi <br><strong>Lưu ý</strong> : Trong trường hợp muốn kích hoạt thoại luôn thì sẽ gọi hàm <strong>csEnableCall()</strong> trong hàm này</td></tr><tr><td>17</td><td><code>csListTransferAgent(listTransferAgent)</code></td><td>Sự kiện được gọi khi lấy thành công list agent đang online</td></tr><tr><td>18</td><td><code>csTransferCallError(error, tranferedAgentInfo)</code></td><td>Sự kiện được gọi khi chuyển cuộc gọi thất bại. <code>error</code> là mã lỗi trả về, <code>tranferedAgentInfo</code> là thông tin agent được chuyển (có thể null)</td></tr><tr><td>19</td><td><code>csTransferCallSuccess(tranferedAgentInfo)</code></td><td>Sự kiện được gọi khi chuyển cuộc gọi thành công. <code>tranferedAgentInfo</code> là thông tin agent được chuyển</td></tr><tr><td>20</td><td><code>csNewCallTransferRequest(transferCall)</code></td><td>Sự kiện được gọi khi có một cuộc gọi được chuyển</td></tr><tr><td>21</td><td><code>csTransferCallResponse(status)</code></td><td>Sự kiện được gọi khi người được chuyển cuộc gọi bấm từ chối hoặc tiếp nhận yêu cầu. <code>status=OK</code> tiếp nhận,<code>status=NOK</code> từ chối</td></tr><tr><td>22</td><td><code>csTransferSurveyResponse(status)</code></td><td>Sự kiện được gọi khi nhận được kết quả gửi khảo sát (<code>status=true</code> thành công, <code>status=false</code> thất bại)</td></tr><tr><td>23</td><td><code>csNotifyReconnecting(retry,maxRetry)</code></td><td>Sự kiện được gọi khi socket bị mất kết nối và đang kết nối lại <br><code>retry</code> Lần retry hiện tại<br><code>maxRetry</code> Số lần retry tối đa</td></tr><tr><td>24</td><td><code>csOndisconnected()</code></td><td>Sự kiện được gọi khi socket đã thất bại quá số lần retry tối đa ở function<code>csNotifyReconnecting</code></td></tr></tbody></table>

{% hint style="info" %}
**Chú ý:** csTransferCallError,csTransferCallSuccess,csNewCallTransferRequest chỉ áp dụng cho cuộc gọi chuyển từ agent sang agent , không áp dụng cho cuộc gọi chuyển nhánh, cuộc gọi chuyển nhánh sẽ hoạt động như 1 cuộc gọi vào bình thường
{% endhint %}

**Các hàm này đã được để trong file custom.js**

### Phụ lục: Bảng mã lỗi khi gọi ra

<table><thead><tr><th width="85">STT</th><th width="242">Error Code</th><th width="140">Sip Code</th><th>Mô tả</th></tr></thead><tbody><tr><td>1</td><td>IPCC_NOT_CONNECT_CUSTOMER</td><td></td><td>Gọi ra thất bại, chi tiết trong các mã sip Code bên dưới</td></tr><tr><td>2</td><td></td><td>486</td><td>Khách hàng đang bận</td></tr><tr><td>3</td><td></td><td>408</td><td>Khách hàng không nghe máy hoặc có lỗi xảy ra</td></tr><tr><td>4</td><td></td><td>403</td><td>Lỗi đầu số, xin vui lòng liên hệ đơn vị cung cấp đầu số để được hỗ trợ</td></tr><tr><td>5</td><td></td><td>487</td><td>Khách hàng không nghe máy</td></tr><tr><td>6</td><td></td><td>480</td><td>Khách hàng không nghe máy</td></tr><tr><td>7</td><td></td><td>404</td><td>Không kết nối được đến số thuê bao, xin vui lòng liên hệ đơn vị cung cấp đầu số để được hỗ trợ</td></tr><tr><td>8</td><td></td><td>500</td><td>Có lỗi xảy ra, xin vui lòng liên hệ đơn vị cung cấp đầu số để được hỗ trợ</td></tr><tr><td>9</td><td></td><td>600 || 603</td><td>Khách không nghe máy hoặc đang bận</td></tr><tr><td>10</td><td></td><td>703</td><td>Số gọi ra bị Caresoft chặn</td></tr><tr><td>11</td><td></td><td>786</td><td>Lỗi trạng thái nghe gọi, gen token mới hoặc on/off lại trạng thái</td></tr><tr><td>12</td><td>Các mã khác</td><td></td><td>Có lỗi xảy ra</td></tr><tr><td>13</td><td>IPCC_NOT_CONNECT_AGENT_ID</td><td></td><td>Không thể kết nối được đến thiết bị nghe gọi của tư vấn viênkiểm tra lại IP Phone/SoftPhone và đường truyền Internet</td></tr><tr><td>14</td><td>CALLOUT_AGENT_BUSY</td><td></td><td>Busy. Vui lòng đăng xuất và đăng nhập lại để tiếp tục sử dụng.</td></tr><tr><td>15</td><td>CALLOUT_PERMISSION_DENY</td><td></td><td>Không có quyền gọi ra. Liên hệ Admin để cấu hình</td></tr><tr><td>16</td><td>ERROR_CALLOUT_CONNECT</td><td></td><td>Có lỗi xảy ra</td></tr><tr><td>17</td><td>ERROR_CALLOUT_NUMBER_BLOCKED</td><td></td><td>Số điện thoại gọi ra bị chặn theo cấu hình</td></tr></tbody></table>

**Bảng mã lỗi khi chuyển cuộc gọi**

<table><thead><tr><th width="74">STT</th><th width="253">Error Code</th><th>Mô tả</th></tr></thead><tbody><tr><td>1</td><td>NOT_CHOOSE_TYPE_TRANSFER</td><td>Chưa chọn loại chuyển cuộc gọi</td></tr><tr><td>2</td><td>TRANSFER_CALL_FAILED</td><td>Chuyển cuộc gọi thất bại</td></tr><tr><td>3</td><td>NOT_IN_A_CALL</td><td>Không trong cuộc gọi</td></tr><tr><td>4</td><td>COULD_NOT_GET_CALL_INFO</td><td>Không thể lấy thông tin cuộc gọi</td></tr></tbody></table>

**Các thuộc tính trong csVoice**

<table><thead><tr><th width="86">STT</th><th width="224">Thuộc tính</th><th width="122">Kiểu dữ liệu</th><th>Mô tả</th></tr></thead><tbody><tr><td>1</td><td><code>isCallout</code></td><td><code>bool</code></td><td>Có phải là cuộc gọi ra hay không</td></tr><tr><td>2</td><td><code>deviceType</code></td><td><code>int</code></td><td>thiết bị hiện tại, có 5 loại : <br><code>1</code> = web<br><code>2</code> = ipphone/softphone (phải đăng nhập)<br><code>3</code> = divert di động <br><code>4</code> =  ipphone/softphone (không cần đăng nhập)<br><code>8</code> = Ứng dụng CareSoft</td></tr><tr><td>2</td><td><code>enableVoice</code></td><td><code>bool</code></td><td>Trạng thái kích hoạt thoại</td></tr><tr><td>3</td><td><code>isMute</code></td><td><code>bool</code></td><td>Đang mute cuộc gọi hay không</td></tr><tr><td>4</td><td><code>isHold</code></td><td><code>bool</code></td><td>Đang hold cuộc gọi hay không</td></tr><tr><td>5</td><td><code>getCalloutServices</code></td><td><code>func</code></td><td>Trả về danh sách các dịch vụ gọi ra mà agent hiện tại được gán quyền. Danh sách trả về gồm 1 mảng object có cấu trúc sau: <br><code>{</code><br> <code>"callout_id": Id dịch vụ,</code><br> <code>"agent_id":ipphone của agent hiện tại,</code><br> <code>"is_default":có phải dịch vụ mặc định không,</code><br> <code>"descriptions":Mô tả</code><br> <code>}</code> </td></tr></tbody></table>

{% hint style="info" %}
**Tham khảo**: \
Code demo  <https://gitlab.com/caresoftpublic/Demo-Embed-VoiceAPI>
{% endhint %}


# Xử lí multitab

Xử lí trạng thái kích hoạt thoại khi mở nhiều tab trình duyệt

Trường hợp user thao tác trên nhiều tab của ứng dụng. CareSoft quy định tại 1 thời điểm có 1 tab được quyền gọi. Vì thế nếu bật nhiều tab hoặc đăng nhập tại nhiều nơi thì cũng chỉ có duy nhất 1 tab được sử dụng chức năng thoại. Tab đầu tiên đăng nhập vào hệ thống sẽ có quyền thoại này. Các tab về sau muốn dùng thì sử dụng hàm `csEnableCall()`

{% hint style="warning" %}
Khi đang ở trong cuộc gọi, nếu gọi hàm `csEnableCall()` thì cuộc gọi sẽ bị ngắt. &#x20;
{% endhint %}


# Xử lí lỗi cross domain (CORS error)

Cách xử lí lỗi CORS khi init sdk

CareSoft mặc định sẽ chặn cross domain cho những domain chưa được whitelist trên hệ thống. Nếu môi trường code của bạn không thuộc whitelist CORS của CareSoft, bạn sẽ gặp phải lỗi này:

{% code overflow="wrap" %}

```
Access to XMLHttpRequest at 'http://localhost:8000/api/login/check-partner?authToken={your_token}&domain={your_domain}' from origin 'http://localhost' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
```

{% endcode %}

Cách xử lí: Khi bạn đang thao tác trên môi trường test, làm theo hướng dẫn sau:

Nếu dùng google chrome (hoặc các trình duyệt khác sử dụng nhân chromium): Đóng chrome và khởi động lại với tham số `--disable-web-security`&#x20;

{% hint style="info" %}
Hãy chắc chắn rằng bạn đã đóng tất cả các cửa sổ chrome đang bật
{% endhint %}

Click chuột phải vào chrome, chọn **Properties.**&#x20;

![](https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FFnFnTw6zFWXl1G3N55Hm%2Fimage.png?alt=media\&token=f9862142-9483-4cb9-a087-2f370cb18102)

Ở ô **Target** nhập đoạn lệnh sau:

```
chromium-browser --disable-web-security --user-data-dir="[some directory here]"
```

`--user-data-dir` Là đường dẫn đến thư mục tự tạo, ví dụ `c:/chromedev` .Sau đó click chọn **Ok.**&#x20;

Nếu thành công, khi mở chrome trình duyệt sẽ cảnh báo "you are using an unsupported command line". Bạn có thể bỏ qua thông báo này và thực hiện init sdk như bình thường

Tham khảo: <https://stackoverflow.com/a/3177718>

Nếu bạn deploy app ở môi trường thật, bạn cần gửi thông tin tên miền hiện tại đang sử dụng để CareSoft mở whitelist CORS.


# Chuyển cuộc gọi (agent)

Luồng hoạt động của chức năng chuyển cuộc gọi (agent)

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2F3wvHDXWbUOjr1RFPu5Rb%2F5ce1f54d55458b1bd254.jpg?alt=media&amp;token=61d77a28-4b4c-4587-88f4-25bff942704b" alt=""><figcaption><p>Biểu đồ miêu tả luồng hoạt động của chức năng chuyển cuộc gọi (agent - agent)</p></figcaption></figure>


# Tích hợp gọi ra sử dụng Click to call trên web

Nếu đối tác chỉ có nhu cầu tích hợp luồng gọi ra thì CareSoft cung cấp thêm giải pháp C2C đơn giản và tiết kiệm thời gian hơn.

Trên CRM/ERP khi phát sinh nhu cầu cần gọi  điện cho khách hàng qua tổng đài CareSoft. Giúp giảm thiểu rủi ro do thao thác nhập liệu giữa các ứng dụng. Lập trình viên có thể sử dụng Click to call của CareSoft để thực hiện nghiệp vụ này.

## Các bước chuẩn bị&#x20;

1. Lấy mã xác thực từ giao diện admin  CareSoft. \
   Truy cập vào CareSoft bằng tài khoản admin mà CareSoft cấp cho khách hàng. Tại menu Admin --> Api --> Api Token.&#x20;

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FB1jLabwd54SvgAuhDweM%2FAPI_VOICE_TOKEN.png?alt=media&amp;token=25a903fa-0415-4031-bbf5-94a19661bb1e" alt=""><figcaption></figcaption></figure>

2. Ở dòng **Token voice api hiện tại** chọn **Tạo token mới**  nếu chưa có hoặc **Copy**  nếu đã có và lưu lại thành 1 cấu hình `{{apiVoiceAccessToken}}`&#x20;

{% hint style="info" %}
**LƯU Ý:** Khi  bấm nút tạo mới hệ thống sẽ thay thế `apiVoiceAccessToken`cũ bằng `apiVoiceAccessToken` mới khiến các ứng dụng đang tích hợp sẽ mất quyền truy cập.  Vui lòng cập nhật token ở các ứng dụng theo token mới nếu bạn bấm "Tạo token mới" để đảm bảo hệ thống hoạt động liền mạch&#x20;
{% endhint %}

3. Thư viện JWT phù hợp với ngôn ngữ lập trình của bạn để tạo mã token cho mỗi cuộc gọi. Xem thêm ở  [www.jwt.io](https://jwt.io/)
4. Liên kết để mở ra khi thực hiện cuộc gọi \
   `https://c2c.caresoft.vn/{{domain}}/c2call?token={{token}}&number={{phoneNo}}&device={{deviceId}}`\
   Trong đó `deviceId` là Id của thiết bị để gọi ra `1`: web, `2`: IPPhone

## Cách thức thực hiện.

1. Chuẩn bị payload để tạo mã token cuộc gọi

<pre class="language-json" data-title="Mẫu Payload"><code class="lang-json">{
    "ipphone": "{{agent_id}}",
    "expired": "2017-07-30 00:00:00",
    "callout_id":"<a data-footnote-ref href="#user-content-fn-1">{{callOutId}}</a>"
  }

</code></pre>

**Trong đó:**&#x20;

* `IpPhone` Là số Iphone của Chuyên viên tương ứng (Xem thêm thông tin chuyên viên  ở [Chuyên viên](/danh-muc/restful-api-cua-caresoft/chuyen-vien))
* `expired` Thời hạn hết hạn của token
* `callout_id` ID của đầu số muốn gọi ra, nếu không truyền vào sẽ lấy đầu số default được gán cho agent để gọi ra. (Liên hệ với bộ phận hỗ trợ của CareSoft để có danh sách ID đầu số gọi ra đã tích hợp vào hệ thống)&#x20;

2. Lập trình với thư viện JWT để tạo ra chuỗi token  trong hình dưới là cách thức gen  token sử dụng trực tiếp từ trang web jwt.io.  Xem các hướng dẫn và thư viện tương thích trong mục "[Libraries](https://jwt.io/libraries)" của JWT

*Ví dụ minh họa: Sử dụng giao diện web jwt.io để gen token*

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FMNFRnq5IA0GGFNVNHaMJ%2FJWT.png?alt=media&amp;token=0ff1dcc3-010d-47cc-bee7-5edf628ec4fa" alt=""><figcaption></figcaption></figure>

Copy chuỗi token JWT lưu thành biến {{token}} \
Ví dụ ở trường hợp trên sẽ là  `"eyJhbGciOiJIUzI1NiIsInR5cCI6Ik....CI6IjIwMDU3..."`

2. Nhúng link theo từng số điện thoại cần thực hiện gọi\
   Lập trình viên thực hiện gép các chuỗi thông tin lại  thành 1 liên kết  cấu trúc như mục 1.4  và thay thế các biến thông tin thành các chuỗi giá trị liên quan. Ở đây phoneNo là số điện thoại của khách hàng cần thực hiện gọi ra. \
   `https://c2c.caresoft.vn/{{domain}}/c2call?token={{token}}&number={{phoneNo}}&device={{deviceId}}`\
   \
   Sử dụng popup để mở ra cửa sổ mới với link trên. &#x20;
3. Tham khảo code html&#x20;

{% code title="Code html tham khảo " %}

```html
<!DOCTYPE html>
<html>
<body>
<h1>CRM</h1>
<button onclick="makeCsCall()">Gọi điện</button>
<script>
function makeCsCall() {
var url="https://c2c.caresoft.vn/{{domain}}/c2call?token={{token}}&number={{phoneNo}}" 
  window.open(url,"csCall","width=400,height=600");
}

function displayMessage(evt) {
             try {
                 console.log(evt);
             } catch (err) {
                 log(err);
             }
         }
        
         if (window.addEventListener) {
             // For standards-compliant web browsers
             window.addEventListener("message", displayMessage, false);
         } else {
             window.attachEvent("onmessage", displayMessage);
         }
</script>
</body>
</html>

```

{% endcode %}

Cửa sổ mở ra đường link trên sẽ có dạng&#x20;

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FcUwZhnAyoUeCyHaYnKOu%2FCS_CALL.png?alt=media&amp;token=5b251c31-efd8-4571-99f3-3125a13a311e" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**GỢI Ý:**\
Lập trình viên có thể bổ sung callback để lưu thông tin cuộc gọi lại phục vụ các nghiệp vụ khác
{% endhint %}

Mẫu dữ liệu callback CareSoft sẽ trả lại cửa sổ chính sau khi cuộc gọi kết thúc và cửa sổ cuộc gọi bị đóng lại.

<pre class="language-json" data-overflow="wrap"><code class="lang-json">{
  "id": 8,
  "type": "<a data-footnote-ref href="#user-content-fn-2">call_ended</a>",
  "data": {
    "customer_phone": "<a data-footnote-ref href="#user-content-fn-3">09xxxxxx</a>",
    "call_id": "<a data-footnote-ref href="#user-content-fn-4">20230412120428-OUTHJAMC-47</a>"
  },
  "origin": "caresoft",
  "queryString": "?token=eyJhbGciOiJIUz....mLNv54j34jZR7-baoSfEWqzlMxwyrcX_Ec&#x26;number=09xxxxxx"
}
</code></pre>

[^1]: null hoặc Liên hệ với bộ phận hỗ trợ của CareSoft để có danh sách ID đầu số gọi ra đã tích hợp vào hệ thống

[^2]: call\_ended: Kết thúc\
    call\_starting: Bắt đầu

[^3]: Số điện thoại gọi đến

[^4]: ID cuộc gọi


# Tích hợp kênh thoại trên ứng dụng mobile

Giải pháp tích hợp kênh thoại trên ứng dụng mobile

Trong nhiều trường hợp. Doanh nghiệp cần giữ thông suốt thông tin từ ứng dụng riêng biệt của mình trên điện thoại di động (ứng dụng trên nền tảng iOS hoặc Android).  CareSoft cung cấp giải pháp tích hợp kênh thoại trên ứng dụng mobile của đối tác, cho phép user có thể nhận cuộc gọi vào và thực hiện cuộc gọi ra ngay trên ứng dụng của đối tác.

> **Yêu cầu:**  Thiết bị di động của chuyên viên (điện thoại iPhone hoặc các thiết bị Android) đều cài đặt  ứng dụng của doanh nghiệp và ứng dụng CsCall

### Chuẩn bị thông tin

1. Lấy mã xác thực từ giao diện admin  CareSoft. \
   Truy cập vào CareSoft bằng tài khoản admin mà CareSoft cấp cho khách hàng.
2. Tại menu Admin --> Api --> Api Token. \
   Ở dòng Token voice api hiện tại chọn Tạo token mới  nếu chưa có hoặc Copy  nếu đã có và lưu lại thành 1 cấu hình {{apiVoiceAccessToken}}
3. Thư viện JWT phù hợp với ngôn ngữ lập trình của bạn để tạo mã token cho mỗi cuộc gọi. Xem thêm ở [ www.jwt.io](https://jwt.io/)​

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FB1jLabwd54SvgAuhDweM%2FAPI_VOICE_TOKEN.png?alt=media&amp;token=25a903fa-0415-4031-bbf5-94a19661bb1e" alt=""><figcaption><p>Cách lấy và khởi tạo Voice token trên giao diện Caresoft</p></figcaption></figure>

{% hint style="info" %}
**LƯU Ý**: Khi  bấm nút tạo mới hệ thống sẽ thay thế `apiVoiceAccessToken` cũ bằng `apiVoiceAccessToken` mới khiến các ứng dụng đang tích hợp sẽ mất quyền truy cập.  Vui lòng cập nhật token ở các ứng dụng theo token mới nếu bạn bấm "Tạo token mới" để đảm bảo hệ thống hoạt động liền mạch
{% endhint %}

## Cách thức tích hợp

### Chuẩn bị payload để tạo mã token cuộc gọi

```json
{
 "ipphone": "{{agent_id}}"
}
```

**Trong đó:**

* IpPhone Là số Iphone của Chuyên viên tương ứng (Xem thêm thông tin chuyên viên  ở[ Chuyên viên](https://docs.caresoft.vn/danh-muc/restful-api-cua-caresoft/chuyen-vien))

### Tạo chuỗi token

Lập trình với thư viện JWT để tạo ra chuỗi token  trong hình dưới là cách thức gen  token sử dụng trực tiếp từ trang web jwt.io.  Xem các hướng dẫn và thư viện tương thích trong mục "[Libraries](https://jwt.io/libraries)" của JWT

Ví dụ: Tạo chuỗi token đăng nhập vào hệ thống Caresoft sử dụng giao diện JWT.io

Copy chuỗi token JWT lưu thành biến **`{token}`**&#x20;

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2F1aLLMAq7HR8nLPuFjXLD%2FpayloadJWT.png?alt=media&amp;token=2c8cd9b3-f6c8-415e-a3bf-4e78885b391a" alt=""><figcaption></figcaption></figure>

*Ví dụ ở trường hợp trên sẽ là*&#x20;

`eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....e_ZYyfTxg3EDG6vrKxhbZXPx9tQXrLcB5oeyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....e_ZYyfTxg3EDG6vrKxhbZXPx9tQXrLcB5o`

Token này sẽ lưu lại để thực hiện việc tích hợp click to call với ứng dụng CsCall.

### Thực hiện đăng nhập vào ứng dụng CsCall.

Để thực hiện đăng nhập với ứng dụng CsCall, từ ứng dụng của khách hàng, thực hiện truy cập liên kết sau:

`https://caresoftcall.page.link/?link={link}&apn=com.caresoft.caresoftcall&isi=6447892382&ibi=com.caresoft.caresoftcall&efr=1`

**Trong đó:**&#x20;

\- [https://caresoftcall.page.link](https://caresoft.page.link) là đường dẫn ứng dụng CsCall đã đăng ký để khi gọi đường dẫn này sẽ tự động mở ứng dụng CsCall và thực hiện các tác vụ tương ứng mà ở đây là thực hiện đăng nhập với token đã tạo ở bước trên

\- {link}: đường dẫn để gọi sang app có cấu trúc như sau:

`https://mapi.caresoft.vn/dangnhap?appToken={token}&appDomain={domain}`&#x20;

&#x20;    \+ {token}: token đã tạo và lưu ở bước tạo token

&#x20;    \+ {domain}: tên domain của khách hàng.

**Lưu ý**: đường dẫn khi tạo xong phải được encode

Ví dụ: Với token là 123456, domain là test, thì đường dẫn cuối cùng thực hiện gọi sẽ là:&#x20;

`https://caresoftcall.page.link/?link=https%3A%2F%2Fmapi.caresoft.vn%2Fdangnhap%3FappToken%3D123456%26appDomain%3Dtest&apn=com.caresoft.caresoftcall&isi=6447892382&ibi=com.caresoft.caresoftcall&efr=1`

### Tiếp nhận cuộc gọi vào

Khi Agent để chế độ tiếp nhận trên mobile, khi cuộc gọi đến Agent sẽ tiếp nhận cuộc gọi qua ứng dụng của CsCall, kết thúc cuộc gọi thì quay lại ứng dụng chính để làm việc tiếp.

### **Thực hiện cuộc gọi ra**

Để thực hiện luồng gọi ra, đối tác sẽ tích hợp theo dạng click to call từ ứng dụng của khách hàng bằng cách truy cập liên kết sau:

`https://caresoftcall.page.link/?link={link}&apn=com.caresoft.caresoftcall&isi=6447892382&ibi=com.caresoft.caresoftcall&efr=1`

**Trong đó:**&#x20;

\- [https://caresoftcall.page.link](https://caresoft.page.link) là đường dẫn ứng dụng CsCall đã đăng ký để khi gọi đường dẫn này sẽ tự động mở ứng dụng CsCall và thực hiện các tác vụ tương ứng mà ở đây là thực hiện gọi ra một số điện thoại

\- {link}: đường dẫn để gọi sang app có cấu trúc như sau:

`https://mapi.caresoft.vn/call?phone={phone}&appToken={token}&tempId={tempId}`&#x20;

&#x20;   \+ {phone}: số điện thoại thực hiện gọi ra

&#x20;   \+ {token}: token đã tạo và lưu ở bước tạo token. Sau khi ứng dụng Caresoft đã đúng token với token đăng nhập thì sẽ cho phép gọi ra, tránh việc gọi sai tài khoản.

&#x20;   \+ {tempId}: mã cuộc gọi do ứng dụng khách hàng tạo ra (đảm bảo mã này là duy nhất), dùng để truy xuất thông tin cuộc gọi sau này.

**Lưu ý**: đường dẫn khi tạo xong phải được encode

Ví dụ: Với token là 123456, số điện thoại gọi ra là 0988888888, mã cuộc gọi là 0123456789, thì đường dẫn cuối cùng thực hiện gọi sẽ là:&#x20;

`https://caresoftcall.page.link/?link=https%3A%2F%2Fmapi.caresoft.vn%2Fcall%3Fphone%3D0988888888%26appToken%3D123456%26tempId%3D0123456789&apn=com.caresoft.caresoftcall&isi=6447892382&ibi=com.caresoft.caresoftcall&efr=1`

### Trạng thái và lịch sử cuộc gọi

Lập trình viên có thể sử dụng API [Cuộc gọi](/danh-muc/restful-api-cua-caresoft/cuoc-goi) để lấy về danh sách cuộc gọi đã thực hiện của chuyên viên theo số điện thoại của khách. Xem thêm tại: \
[Cuộc gọi](/danh-muc/restful-api-cua-caresoft/cuoc-goi#vi-du-minh-hoa-lay-lich-su-cuoc-goi-theo-so-dien-thoai-cua-khach-cua-1-chuyen-vien)

#### **Thông tin thêm:**

Tải Ứng dụng CsCall cho Android [tại đây](https://play.google.com/store/apps/details?id=com.caresoft.caresoftcall\&pli=1) hoặc iOS [tại đây](https://apps.apple.com/vn/app/cscall/id6447892382)<br>


# Webhook

Version 1.3

CareSoft cung cấp tính năng hỗ trợ các webhook để nhận thông tin cập nhật người dùng, tổ chức, phiếu ghi, các sự kiện realtime cho cuộc gọi vào, sự kiện kết thúc cuộc gọi trên smartdialer.

Để thực hiện các kịch bản webhook nâng cao như tuỳ chỉnh nội dung đầu ra, gọi API ngoài bằng POST/GET, kiểm tra phản hồi để chọn Outputs, và định dạng dữ liệu trước khi cập nhật CRM, bạn tham khảo thêm tại: Workflow CareSoft: [Gửi Webhook (POST/GET), Test Webhook và Định dạng dữ liệu (Data Ops)](https://doc.caresoft.vn/danh-sach-tinh-nang/workflow/nhom-hanh-dong-gui-webhook-test-webhook-va-dinh-dang-du-lieu-data-ops)

## I. Cấu hình và vận hành Webhook

### &#x20;1. Chuẩn bị thông tin&#x20;

#### Khách hàng gửi thông tin server webhook cho support hỗ trợ cấu hình bao gồm:

* Callback Url  (*VD: <http://sample.com/api/webHook>*)
* SecretKey (option)
* Các sự kiện hỗ trợ đăng ký: \
  **`Người dùng:`**`user`\
  **`Tổ chức:`**` ``organization`\
  **`Phiếu ghi:`**` ``ticket.voice, ticket.voice_out, ticket.ivr, ticket.voicemail, ticket.voice_campaign, ticket.email, ticket.email_out, ticket.web, ticket.api, ticket.sms_out, ticket.ticket_form, ticket.ticket_sharing, ticket.chat, ticket.facebook, ticket.inbox_facebook, ticket.inbox_facebook_out, ticket.facebook_rating, ticket.facebook_lead_ads, ticket.instagram, ticket.chat_instagram, ticket.inbox_zalo, ticket.inbox_zalo_out, ticket.inbox_zalo_zns, ticket.zalo_lead_form`\
  **`Lead:`**` ``lead`\
  **`Deal:`**` ``deal`\
  **`SmartDialer:`**` ``smart_dialer`\
  **`Cuộc gọi vào:`**` ``call_in`

{% hint style="info" %}
**LƯU Ý:** Event sẽ được trả về theo method POST. Request body dạng application/json. Header bao gồm X-Hub-Signature được mã hoá body theo chuẩn HmacSHA1 với secret key đã được cấu hình (Kết quả mã hoá ở dạng uppercase)

Link test mã hoá Signature: \
<https://tools.onecompiler.com/hmac-sha1>

VD:

Request Body: {"ticket\_id":1}\
SecretKey: CS123

Signature: 420A69CE7D3C36559E9828D6361530DF30065D37
{% endhint %}

### 2. Cảnh báo và hủy kích hoạt Webhook&#x20;

Để đảm bảo tính ổn định của hệ thống, CareSoft sẽ theo dõi trạng thái gửi Webhook.

Nếu Webhook phát sinh lỗi liên tục và không thể gửi thành công trong vòng X giờ, hệ thống sẽ gửi email cảnh báo đến email đã đăng ký.

Nếu Webhook vẫn không thể gửi thành công trong vòng Y giờ, hệ thống sẽ tự động hủy kích hoạt cấu hình Webhook và gửi email thông báo. Để kích hoạt lại, vui lòng liên hệ bộ phận Chăm sóc khách hàng của CareSoft.

X và Y là giá trị mặc định của hệ thống ( X: 1h và Y: 5h). Ví dụ:

* Sau 1h phát sinh lỗi liên tục → gửi email cảnh báo.
* Sau 5h vẫn không gửi thành công → tự động hủy kích hoạt và gửi email thông báo và cần liên hệ lại với bộ phận chăm sóc khách hàng của CareSoft để mở

## II. Các sự kiện webhook

### 1. Sự kiện trên người dùng

{% code title="Sự kiện người dùng" %}

```json
// Sự kiện người dùng được tạo
{
  "object": "user",
  "action": "create",
  "user": {
       "id": 0,
       "username": "",
       "account_id": 0,
       "email": "",
       "email2": "",
       "phone_no": "",
       "phone_no2": "",
       "phone_no3": "",
       "role_id": 3,
       "facebook": "",
       "note": "",
       "gender": 0,
       "organization_id": 0,
       "detail": "",
       "avatar": "",
       "user_info1": "", //facebook name
       "user_info5": "", //address
       "user_info10": "", //instagram name
       "user_info12": "", //instagram link
       "user_info16": "", //zalo name
       "follower_id": 0,
       "updated_at": 0, //Time in millis
       "created_at": 0, //Time in millis
       "addition_fields":
     [
       {
         "id": 0, //id trường động
         "field": "addition_field1", //Mã trường động
         "label": "", //Tên trường động
         "type": 0|1|2|3|4|6|7, //String|Number|DateTime|SingleSelect|MultiSelect|TextArea|Stage
         "value": "", //value in string
         "value_id": 0 //value id
       }
     ]
   }
}

```

{% endcode %}

{% code title="Sự kiện người dùng" %}

```json
// Sự kiện cập nhật người dùng
{
  "object": "user",
  "action": "update",
  "user": {
       "id": 0,
       "username": "",
       "account_id": 0,
       "email": "",
       "email2": "",
       "phone_no": "",
       "phone_no2": "",
       "phone_no3": "",
       "role_id": 3,
       "facebook": "",
       "note": "",
       "gender": 0,
       "organization_id": 0,
       "detail": "",
       "avatar": "",
       "user_info1": "", //facebook name
       "user_info5": "", //address
       "user_info10": "", //instagram name
       "user_info12": "", //instagram link
       "user_info16": "", //zalo name
       "follower_id": 0,
       "updated_at": 0, //Time in millis
       "created_at": 0, //Time in millis
       "addition_fields":
     [
       {
         "id": 0, //id trường động
         "field": "addition_field1", //Mã trường động
         "label": "", //Tên trường động
         "type": 0|1|2|3|4|6|7, //String|Number|DateTime|SingleSelect|MultiSelect|TextArea|Stage
         "value": "", //value in string
         "value_id": 0 //value id
       }
     ]
   }
}
```

{% endcode %}

### 2. Sự kiện trên tổ chức

{% code title="Tổ chức" %}

```json
// Sự kiện tổ chức được tạo
{
  "object": "organization",
  "action": "create",
  "organization": {
    "organization_id": 0,
    "account_id": 0,
    "organization_name": "",
    "organization_domain": "",
    "details": "",
    "note": "",
    "created_at": 0, //Time in millis
    "updated_at": 0, //Time in millis,
    "addition_fields":
     [
       {
         "id": 0, //id trường động
         "field": "addition_field1", //Mã trường động
         "label": "", //Tên trường động
         "type": 0|1|2|3|4|6|7, //String|Number|DateTime|SingleSelect|MultiSelect|TextArea|Stage
         "value": "", //value in string
         "value_id": 0 //value id
       }
     ]
  }
}
```

{% endcode %}

<pre class="language-json" data-title="Tổ chức"><code class="lang-json"><strong>// Sự kiện tổ chức được cập nhật
</strong>{
  "object": "organization",
  "action": "update",
  "organization": {
    "organization_id": 0,
    "account_id": 0,
    "organization_name": "",
    "organization_domain": "",
    "details": "",
    "note": "",
    "created_at": 0, //Time in millis
    "updated_at": 0, //Time in millis,
    "addition_fields":
     [
       {
         "id": 0, //id trường động
         "field": "addition_field1", //Mã trường động
         "label": "", //Tên trường động
         "type": 0|1|2|3|4|6|7, //String|Number|DateTime|SingleSelect|MultiSelect|TextArea|Stage
         "value": "", //value in string
         "value_id": 0 //value id
       }
     ]
  }
}
</code></pre>

### 3. Sự kiện trên phiếu ghi

Khi có sự kiện xảy ra trên phiếu ghi, nguồn của sự kiện này sẽ phân biệt bằng giá trị của thuộc tính **`source`** trong **`ticket_comment.`**&#x20;

Ví dụ để phân biệt sự kiện là cuộc gọi vào hay cuộc gọi ra:&#x20;

Các giá trị source cuộc gọi vào: `Voice`, `IVR`, `ZCC In`, `MissCall`, `VoiceMail`, `Voicemail`

Các giá trị source cho gọi ra: `Voice Out`, `ZCC Out`, `Voice Campaign`

Xem đầy đủ danh sách các giá trị của nguồn tại [Danh sách nguồn](https://docs.caresoft.vn/danh-muc/restful-api-cua-caresoft/phieu-ghi/danh-sach-nguon).

{% code title="Phiếu ghi" %}

```json
// Phiếu ghi được tạo
{
 "object": "ticket",
 "action": "create",
 "ticket": {
   "ticket_id": 0,
   "ticket_no": 0,
   "assignee_id": 0,
   "service_id": 0,
   "ticket_priority": "normal",
   "ticket_source": "web",
   "ticket_source_end_status": 0,
   "ticket_status": "open",
   "ticket_subject": "",
   "created_at": 0, //Time in millis
   "updated_at": 0, //Time in millis,
   "last_change_status_at": 0, //Time in millis
   "campaignId": 0,
   "addition_fields":
     [
       {
         "id": 0, //id trường động
         "field": "addition_field1", //Mã trường động
         "label": "", //Tên trường động
         "type": 0|1|2|3|4|6|7, //String|Number|DateTime|SingleSelect|MultiSelect|TextArea|Stage
         "value": "", //value in string
         "value_id": 0 //value id
       }
     ]
   "ticket_comment": 
     {
       "ticket_id": 0,
       "comment": "",
       "addition_details": "",
       "commentator_id": 0,
       "source": "web",
       "is_public": 0,
       "type": 0,
       "created_at": 0, //Time in millis
       "updated_at": 0, //Time in millis,
     }
  }
}
```

{% endcode %}

{% code title="Phiếu ghi" %}

```json
// Phiếu ghi được cập nhật
{
 "object": "ticket",
 "action": "update",
 "ticket": {
   "ticket_id": 0,
   "ticket_no": 0,
   "assignee_id": 0,
   "service_id": 0,
   "ticket_priority": "normal",
   "ticket_source": "web",
   "ticket_source_end_status": 0,
   "ticket_status": "open",
   "ticket_subject": "",
   "created_at": 0, //Time in millis
   "updated_at": 0, //Time in millis,
   "last_change_status_at": 0, //Time in millis
   "campaignId": 0,
   "addition_fields":
     [
       {
         "id": 0, //id trường động
         "field": "addition_field1", //Mã trường động
         "label": "", //Tên trường động
         "type": 0|1|2|3|4|6|7, //String|Number|DateTime|SingleSelect|MultiSelect|TextArea|Stage
         "value": "", //value in string
         "value_id": 0 //value id
       },
       {
       }
     ]
   "ticket_comment": 
     {
       "ticket_id": 0,
       "comment": "",
       "addition_details": "",
       "commentator_id": 0,
       "source": "web",
       "is_public": 0,
       "type": 0,
       "created_at": 0, //Time in millis
       "updated_at": 0, //Time in millis,
     }
  },
  "call_info":  //Thông tin cuộc gọi nếu có
  {    
    "call_id": "",
    "caller": "", //SĐT khách hàng
    "called": "", //Đầu số
    "status_code": "200",
    "start_time": 000 //Time in millis
    "answer_time": 000 //Time in millis
    "end_time": 000 //Time in millis
  }
}
```

{% endcode %}

```json
// Phiếu bị bị xoá
{
 "object": "ticket",
 "action": "delete",
 "ticket": {
    "ticket_id": 0
  }
}
```

{% code title="Phiếu ghi" %}

```json
// Phiếu ghi bị ghép
{
 "object": "ticket",
 "action": "merge",
  "mergeOption":
  {
    "primaryTicket": 0,
    "secondaryTickets": 1,
    "primaryComment": "",
    "primaryIsPublic": 0,
    "secondaryComment": "",
    "secondaryIsPublic": 0,
    "addCC": 0,
    "addFollow": 0,
    "copyComments": 0,
  }
}
```

{% endcode %}

### 4. Sự kiện trên SmartDialer

{% code title="SmartDialer" %}

```json
// Cuộc gọi kết thúc từ chiến dịch auto call
{
  "object": "smart_dialer",
  "action": "ad_end_call",
  "call_info": {
    "call_id": "",
    "line": "",
    "phone_number": "",
    "call_attempt_index": 0,
    "max_attempt": 1,
    "campaign_id": 0,
    "customer_id": 0,
    "customer_name": "",
    "campaign_data_id": 0,
    "start_time": 0, //Time in millis
    "connect_time": 0, //Time in millis
    "end_time": 0, //Time in millis
    "ring_customer_duration": 0, //seconds
    "call_duration": 0, //seconds
    "status_code": "",
    "customer_input_dtmf": "", //dữ liệu bấm phím ivr nếu có
  }
}
```

{% endcode %}

{% code title="SmartDialer" %}

```json
//Cuộc gọi kết thúc từ chiến dịch predictive call
{
  "object": "smart_dialer",
  "action": "pd_end_call",
  "call_info": {
    "call_id": "",
    "line": "",
    "phone_number": "",
    "call_attempt_index": 0,
    "max_attempt": 1,
    "campaign_id": 0,
    "customer_id": 0,
    "customer_name": "",
    "campaign_data_id": 0,
    "start_time": 0, //Time in millis
    "connect_time": 0, //Time in millis
    "end_time": 0, //Time in millis
    "ring_customer_duration": 0, //seconds
    "call_duration": 0, //seconds
    "agent_user_id": 0,
    "agent_id": 0, 
    "agent_ring_time": 0, //Time in millis
    "agent_connect_time": 0, //Time in millis
    "ring_agent_duration": 0, //seconds
    "status_code": ""
  }
}
```

{% endcode %}

### 5. Sự kiện cập nhật trạng thái cuộc gọi vào

Đăng ký nhận sự kiện này nếu bạn muốn tích hợp chi tiết tất cả các sự kiện xảy ra trong quá trình gọi vào từ lúc cuộc gọi bắt đầu, tới lúc đổ chuông chuyên viên và kết thúc cuộc gọi.

{% code title="Cuộc gọi vào" %}

```json
//1. Sự kiện bắt đầu cuộc gọi
{
  "object": "call_in",
  "action": "call_in_start",
  "call_info": 
  {
    "event_name": "call_in_start",
    "call_id": "",
    "account_id": 0,
    "direction": "inbound",
    "caller": "", //SĐT khách hàng
    "called": "", //Đầu số
    "event_time": 000 //Time in millis
  }
}
```

{% endcode %}

{% code title="Cuộc gọi vào" %}

```json
//2. Sự kiện đổ chuông tới Agent
{
  "object": "call_in",
  "action": "call_in_agent_ring",
  "call_info": 
  {
    "event_name": "call_in_agent_ring",
    "call_id": "",
    "account_id": 0,
    "direction": "inbound",
    "caller": "", //SĐT khách hàng
    "called": "", //Đầu số
    "agent_id": "",
    "event_time": 000 //Time in millis
  }
}
```

{% endcode %}

{% code title="Cuộc gọi vào" %}

```json
//3. Sự kiện Agent bắt máy
{
  "object": "call_in",
  "action": "call_in_agent_answer",
  "call_info": 
  {
    "event_name": "call_in_agent_answer",
    "call_id": "",
    "account_id": 0,
    "direction": "inbound",
    "caller": "", //SĐT khách hàng
    "called": "", //Đầu số
    "agent_id": "",
    "event_time": 000 //Time in millis
  }
}
```

{% endcode %}

{% code title="Cuộc gọi vào" %}

```json
//4. Sự kiện Agent kết thúc cuộc gọi
{
  "object": "call_in",
  "action": "call_in_agent_end",
  "call_info": 
  {
    "event_name": "call_in_agent_end",
    "call_id": "",
    "account_id": 0,
    "direction": "inbound",
    "caller": "", //SĐT khách hàng
    "called": "", //Đầu số
    "agent_id": "",
    "event_time": 000 //Time in millis
  }
}
```

{% endcode %}

{% code title="Cuộc gọi vào" %}

```json
//5. Sự kiện Khách hàng kết thúc cuộc gọi
{
  "object": "call_in",
  "action": "call_in_customer_end",
  "call_info": 
  {
    "event_name": "call_in_customer_end",
    "call_id": "",
    "account_id": 0,
    "direction": "inbound",
    "caller": "", //SĐT khách hàng
    "called": "", //Đầu số
    "agent_id": "",
    "event_time": 000 //Time in millis
  }
}
```

{% endcode %}

{% code title="Cuộc gọi vào" %}

```json
//6. Sự kiện cuộc gọi kết thúc
{
  "object": "call_in",
  "action": "call_in_end",
  "call_info": 
  {
    "event_name": "call_in_end",
    "call_id": "",
    "account_id": 0,
    "direction": "inbound",
    "caller": "", //SĐT khách hàng
    "called": "", //Đầu số  
    "event_time": 000 //Time in millis
    "call_start_time": 0, //Time in millis
    "call_answer_time": 0, //Time in millis
    "call_end_time": 0, //Time in millis
    "call_end_time": 0, //Time in millis
    "call_duration": 0, //Time in seconds
    "status": "answered|miss", //Trạng thái gặp agent hay không
    "answer_duration": 0, //Time in seconds - status answered
    "record_url": "" //Link file ghi âm - status answered
  }
}
```

{% endcode %}

### 6. Sự kiện trên Lead

#### 6.1. Lead được tạo

```json
// lead created event payload
{
  "account_id": 1,
  "activity_source": "AGENT",
  "action": "create",
  "lead": {
    "lead_id": 414856712,
    "name": "Lead name",
    "last_change_status_at": 1713150362091,
    "lead_status_id": 525,
    "estimated_closed_date": 1713200399000,
    "addition_fields": [
      {
        "field": "addition_field6",
        "id": 4373,
        "label": "Reasons Unqualified",
        "value_id": "",
        "type": 3,
        "value": ""
      }
    ],
    "source": "Web",
    "created_at": 1713150362013,
    "updated_at": 1713150362091,
    "activity": {
      "updated_at": 1713150362124,
      "commentator_id": 63216138,
      "is_public": 0,
      "created_at": 1713150362124,
      "comment": "first comment",
      "ticket_id": 414856712,
      "type": 0
    },
    "requester_id": 63216138,
    "assignee_id": 1
  },
  "object": "lead"
}
```

#### 6.2. Lead được convert từ đối tượng khác

```json
// Lead converted from Ticket payload
{
  "account_id": 1,
  "activity_source": "AGENT",
  "action": "convert",
  "updated_properties": [
    {
      "field": "lead_status_id",
      "value": 525
    }
  ],
  "convert_from_object": "ticket",
  "lead": {
    "lead_id": 414856714,
    "name": "Lead name sample",
    "last_change_status_at": 1713153062000,
    "lead_status_id": 525,    
    "addition_fields": [
      {
        "field": "addition_field9",
        "id": 4376,
        "label": "Custom field abc",
        "type": 2,
        "value": ""
      }
    ],
    "source": "Web",
    "created_at": 1713153062000,
    "updated_at": 1713153076734,
    "activity": {
      "updated_at": 1713153076732,
      "commentator_id": 1,
      "is_public": 0,
      "created_at": 1713153076732,
      "comment": "Chuyển đổi dữ liệu thành dạng Lead",
      "source": "Web",
      "lead_id": 414856714,
      "type": 1
    },
    "requester_id": 1,
    "assignee_id": 1
  },
  "object": "lead"
}
```

6.3. Lead được cập nhật

```json
// lead updated event payload
{
  "account_id": 1,
  "activity_source": "AGENT",
  "action": "update",
  "updated_properties": [
    {
      "field": "addition_field19",
      "value": "value sample"
    }
  ],
  "lead": {
    "lead_id": 414856712,
    "name": "Lead name",
    "last_change_status_at": 1713150362000,
    "lead_status_id": 525,
    "estimated_closed_date": 1713200399000,    
    "addition_fields": [
      {
        "field": "addition_field6",
        "id": 4373,
        "label": "Reasons  Unqualified",
        "value_id": "",
        "type": 3,
        "value": ""
      },
      {
        "field": "addition_field19",
        "id": 4406,
        "label": "Kí tự nhỏ hơn 20",
        "type": 0,
        "value": "value sample"
      }
    ],
    "source": "Web",
    "created_at": 1713150362000,
    "updated_at": 1713152406418,
    "activity": {
      "updated_at": 1713152406442,
      "commentator_id": 1,
      "is_public": 0,
      "created_at": 1713152406442,
      "comment": "update",
      "ticket_id": 414856712,
      "type": 1
    },
    "requester_id": 63216138,
    "assignee_id": 1
  },
  "object": "lead"
}
```

Sự kiện Lead chuyển đổi thành Deal xem tại Sự kiện 7.2. Deal được convert từ đối tượng khác

### 7. Sự kiện trên Deal

#### 7.1. Deal được tạo mới

<pre class="language-json"><code class="lang-json">// Deal created event payload
{
  "deal": {
    "deal_id": 414856715,
    "name": "New sample deal",
    "last_change_status_at": 1713153881216,   
    "probability": 5,
    "addition_fields": [
      {
        "field": "addition_field1",
        "id": 4380,
        "label": "Sample custom field",
        "value_id": "",
        "type": 7,
        "value": ""
      }
    ],
    "source": "Web",
    "created_at": 1713153881152,
    "updated_at": 1713153881216,
    "activity": {
      "updated_at": 1713153881253,
      "commentator_id": 1,
      "is_public": 0,
      "created_at": 1713153881253,
      "comment": "first comment",
<strong>      "deal_id": 414856715,
</strong>      "type": 0
    },
    "pipeline_id": 56,    
    "value": 0,
    "last_change_stage_at": 1713153881216,
    "requester_id": 1,
    "assignee_id": 1,
    "pipeline_stage_id": 376
  },
  "account_id": 1,
  "activity_source": "AGENT",
  "action": "create",
  "object": "deal"
}
</code></pre>

#### 7.2. Deal được chuyển đổi từ đối tượng khác

```json
// Deal converted from object (Lead) event payload
{
  "deal": {
    "deal_id": 414856712,
    "name": "Deal name",
    "last_change_status_at": 1713150362000,
    "estimated_closed_date": 1713200399000,    
    "closed_type": 1,
    "addition_fields": [
      {
        "field": "addition_field1",
        "id": 4380,
        "label": "sample custom field",
        "value_id": "",
        "type": 7,
        "value": ""
      }
    ],
    "source": "Web",
    "created_at": 1713150362000,
    "updated_at": 1713154107391,
    "activity": {
      "updated_at": 1713154107417,
      "commentator_id": 1,
      "is_public": 0,
      "created_at": 1713154107417,
      "comment": "Chuyển đổi Lead thành Deal",
      "deal_id": 414856712,
      "type": 1
    },
    "pipeline_id": 56,
    "value": 0,
    "last_change_stage_at": 1713154107391,
    "requester_id": 63216138,
    "assignee_id": 1,
    "pipeline_stage_id": 376
  },
  "account_id": 1,
  "activity_source": "AGENT",
  "action": "convert",
  "convert_from_object": "lead"
  "updated_properties": [
    {
      "field": "value",
      "value": 0
    },
    {
      "field": "converted_at",
      "value": 1713154107391
    },
    {
      "field": "converted_by",
      "value": 1
    },
    {
      "field": "converted_type",
      "value": 1
    }
  ],
  "agent_submit": {
    "from_object": "lead"
  },
  "object": "deal"
}
```

#### 7.3. Deal được cập nhật

```json
// Deal updated event payload
{
  "deal": {
    "deal_id": 414856712,
    "name": "Deal name",
    "last_change_status_at": 1713150362000,
    "estimated_closed_date": 1713200399000,    
    "closed_type": 1,
    "addition_fields": [
      {
        "field": "addition_field1",
        "id": 4380,
        "label": "Sample custom field",
        "value_id": "",
        "type": 7,
        "value": ""
      },
      {
        "field": "addition_field22",
        "id": 6999,
        "label": "Custom field single select",
        "value_id": "92942",
        "type": 3,
        "value": "123a"
      },
      {
        "field": "addition_field16",
        "id": 4385,
        "label": "invoice_field",
        "type": 0,
        "value": "sample text custom field"
      }
    ],
    "source": "Web",
    "created_at": 1713150362000,
    "updated_at": 1713154405236,
    "activity": {
      "updated_at": 1713154405251,
      "commentator_id": 1,
      "is_public": 0,
      "created_at": 1713154405251,
      "comment": "update deal value",
      "ticket_id": 414856712,
      "type": 1
    },
    "pipeline_id": 56,
    "value": 1000000,
    "last_change_stage_at": 1713154107000,
    "requester_id": 63216138,
    "assignee_id": 1,
    "pipeline_stage_id": 376
  },
  "account_id": 1,
  "activity_source": "AGENT",
  "action": "update",
  "updated_properties": [
    {
      "field": "value",
      "value": 1000000
    },
    {
      "field": "addition_field16",
      "value": "sample text custom field"
    },
    {
      "field": "addition_field22",
      "value": "92942"
    }
  ],
  "object": "deal"
}
```

## III. Mô tả tham số

### 1. Tham số phân loại sự kiện

<table><thead><tr><th width="235.33333333333334">Tham số </th><th>Mô tả</th><th>Giá trị</th></tr></thead><tbody><tr><td>object</td><td>Loại đối tượng</td><td><code>ticket</code>: Phiếu ghi<br><code>user</code>: Khách hàng<br><code>organization</code>: Tổ chức<br><code>smart_dialer</code>: Smartdialer<br><code>call_in</code>: Cuộc gọi vào</td></tr><tr><td>action</td><td>Hành động</td><td><p>Các loại sự kiện xảy ra trên đối tượng: Ví dụ:<br><code>create</code>: Tạo mới</p><p><code>update</code>: Cập nhật </p><p><code>delete</code>: Xóa</p><p><code>ad_end_call</code>: Kết thúc cuộc gọi AutoCall của SmartDialer<br><code>pd_end_call</code>: Kết thúc cuộc gọi PredictiveCall của SmartDialer,<br></p></td></tr></tbody></table>

### 2. Tham số phiếu ghi `ticket`

<table><thead><tr><th width="242.33333333333331">Tham số</th><th width="256">Mô tả</th><th>Giá trị</th></tr></thead><tbody><tr><td>ticket_id</td><td>ID phiếu ghi</td><td></td></tr><tr><td>ticket_no</td><td>Số phiếu ghi</td><td></td></tr><tr><td>requester_id</td><td>ID người yêu cầu</td><td></td></tr><tr><td>assignee_id</td><td>ID người xử lý</td><td></td></tr><tr><td>service_id</td><td>ID dịch vụ</td><td></td></tr><tr><td>ticket_priority</td><td>Độ ưu tiên</td><td>High, Low, Normal</td></tr><tr><td>ticket_source</td><td>Nguồn phiếu ghi</td><td>Các giá trị từ <a data-mention href="/danh-muc/restful-api-cua-caresoft/phieu-ghi/danh-sach-nguon">Danh sách nguồn</a></td></tr><tr><td>ticket_source_end_status</td><td>Trạng thái kết thúc phiếu</td><td></td></tr><tr><td>ticket_status</td><td>Trạng thái phiếu ghi</td><td>new, open, pending, closed, solved</td></tr><tr><td>ticket_subject</td><td>Tiêu đề phiếu ghi</td><td></td></tr><tr><td>addition_fields</td><td>Trường động phiếu ghi.  </td><td>Định dạng json array. VD: [{id:1234, field:addition_field1", label: "Tên trường động", value: "Giá trị dạng text"},...]</td></tr><tr><td>created_at</td><td>Thời điểm tạo phiếu ghi</td><td></td></tr><tr><td>updated_at</td><td>Thời điểm cập nhật phiếu ghi</td><td></td></tr></tbody></table>

### 3. Tham số comment phiếu ghi `ticket.ticket_comment`

<table><thead><tr><th width="243">Tham số </th><th>Mô tả</th></tr></thead><tbody><tr><td>ticket_id</td><td>ID phiếu ghi</td></tr><tr><td>commentator_id</td><td>ID người comment</td></tr><tr><td>source</td><td>Nguồn comment</td></tr><tr><td>is_public</td><td>Loại comment:  Công khai (1) hoặc ghi chú nội bộ (0).</td></tr><tr><td>created_at</td><td>Thời điểm comment</td></tr><tr><td>updated_at</td><td>Thời điểm update comment</td></tr></tbody></table>

### 4. Tham số cuộc gọi `call_info`

Đối với cuộc gọi thông thường object cuộc gọi sẽ là  `ticket`

<table><thead><tr><th width="244">Tham số</th><th>Mô tả</th></tr></thead><tbody><tr><td>caller</td><td>SĐT khách hàng</td></tr><tr><td>called</td><td>Hotline tổng đài</td></tr><tr><td>call_id</td><td>ID cuộc gọi</td></tr><tr><td>start_time</td><td>Thời điểm bắt đầu cuộc gọi</td></tr><tr><td>answer_time</td><td>Thời điểm bắt máy</td></tr><tr><td>end_time</td><td>Thời điểm kết thúc</td></tr><tr><td>status_code</td><td>Mã trả về từ đầu số <a href="https://kb.caresoft.vn/support/hc#/?type=article&#x26;id=4">(một số mã thường gặp)</a></td></tr></tbody></table>

### 5. Tham số người dùng `user`

<table><thead><tr><th width="250">Tham số người dùng</th><th>Mô tả</th><th>Giá trị</th></tr></thead><tbody><tr><td>username</td><td>Tên người dùng</td><td></td></tr><tr><td>email</td><td>Email chính</td><td></td></tr><tr><td>email2</td><td>Email phụ</td><td></td></tr><tr><td>phone_no</td><td>SĐT chính</td><td></td></tr><tr><td>phone_no2</td><td>SĐT phụ 2</td><td></td></tr><tr><td>phone_no3</td><td>SĐT phụ 3</td><td></td></tr><tr><td>note</td><td>Ghi chú</td><td></td></tr><tr><td>gender</td><td>Giới tính (0 - Nam, 1 - Nữ, 2 - Khác)</td><td></td></tr><tr><td>organization_id</td><td>ID tổ chức</td><td></td></tr><tr><td>detail</td><td>Mô tả</td><td></td></tr><tr><td>avatar</td><td>Đường dẫn ảnh đại diện</td><td></td></tr><tr><td>user_info5</td><td>Địa chỉ</td><td></td></tr><tr><td>addition_fields</td><td>Trường động người dùng</td><td>Định dạng json array. VD: [{id:1234, field:addition_field1", label: "Tên trường động", value: "Giá trị dạng text"},...]</td></tr><tr><td>follower_id</td><td>ID nhân viên xử lý</td><td></td></tr><tr><td>created_from</td><td>Nguồn tạo KH</td><td></td></tr><tr><td>city_id</td><td>ID tỉnh / thành phố</td><td></td></tr><tr><td>district_id</td><td>ID quận / huyện</td><td></td></tr></tbody></table>

### 6. Tham số tổ chức `organization`

| Tham số tổ chức (organization) | Mô tả               | Ghi chú                                                                                                                   |
| ------------------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| organization\_id               | ID tổ chức          |                                                                                                                           |
| organization\_name             | Tên tổ chức         |                                                                                                                           |
| organization\_domain           | Website             |                                                                                                                           |
| details                        | Chi tiết            |                                                                                                                           |
| note                           | Ghi chú             |                                                                                                                           |
| addition\_fields               | Trường động tổ chức | Định dạng json array. VD: \[{id:1234, field:addition\_field1", label: "Tên trường động", value: "Giá trị dạng text"},...] |

### 7. Tham số cuộc gọi SmartDialer `call_info`

Đối với cuộc gọi smart dialer. Khi object trả về "`smart_dialer`" thì dữ liệu đối tượng `call_info` theo thông tin mô tả dưới đây.&#x20;

<table><thead><tr><th width="251">Tham số </th><th>Mô tả</th></tr></thead><tbody><tr><td>campaign_id</td><td>ID chiến dịch</td></tr><tr><td>customer_id</td><td>ID khách hàng</td></tr><tr><td>customer_name</td><td>Tên khách hàng</td></tr><tr><td>campaign_data_id</td><td>ID Data</td></tr><tr><td>call_id</td><td>Mã cuộc gọi</td></tr><tr><td>line</td><td>Đầu số gọi ra</td></tr><tr><td>phone_number</td><td>SĐT nhận cuộc gọi</td></tr><tr><td>call_attempt_index</td><td>Số lần retry hiện tại</td></tr><tr><td>max_attempt</td><td>Số lần retry tối đa</td></tr><tr><td>start_time</td><td>Thời điểm bắt đầu cuộc gọi (millis)</td></tr><tr><td>connect_time</td><td>Thời điểm bắt máy</td></tr><tr><td>end_time</td><td>Thời điểm kết thúc</td></tr><tr><td>ring_customer_duration</td><td>Thời gian đổ chuông (giây)</td></tr><tr><td>call_duration</td><td>Thời lượng cuộc gọi (giây)</td></tr><tr><td>status_code</td><td>Mã lỗi cuộc gọi (Thành công = 200)</td></tr><tr><td>customer_input_dtmf</td><td>Dữ liệu bấm phím (nếu cuộc gọi là IVR)</td></tr><tr><td>agent_user_id</td><td>ID chuyên viên (Cuộc gọi predictive call - object = pd_end_call)</td></tr><tr><td>agent_id</td><td>IP Phone chuyên viên (Cuộc gọi predictive call)</td></tr><tr><td>agent_ring_time</td><td>Thời điểm đổ chuông tới chuyên viên (Preditive call)</td></tr><tr><td>agent_connect_time</td><td>Thời điểm kết nối tới chuyên viên (Predictive call)</td></tr><tr><td>ring_agent_duration</td><td>Thời lượng chuông tới chuyên viên (Predictive call)</td></tr></tbody></table>

## IV. Mẫu sự kiện

### 1. Ticket Cuộc gọi vào nhỡ

```json
{
   "account_id": 9999,
   "ticket": {
       "ticket_status": "new",
       "ticket_subject": "Cuộc gọi nhỡ từ 0889999999",
       "ticket_priority": "Normal",
       "ticket_source": "Voice",
       "created_at": 1633489861000,
       "ticket_id": 9999,
       "updated_at": 1633489912859,
       "ticket_comment": {
           "updated_at": 1633489912859,
           "commentator_id": 666,
           "is_public": 1,
           "created_at": 1633489861017,
           "comment": "<b>Cuộc gọi vào<\/b><br/>ID cuộc gọi: 20211006101009-HRFZNHMV-9999<br/>Số điện thoại gọi tới: 0889999999<br/>Đầu số gọi: 1019002267<br/>Dịch vụ: Gọi vào 1999999- Gặp NV hỗ trợ<br/>Thời gian bắt đầu: 2021-10-06 10:11:00<br/>Thời gian kết thúc: 2021-10-06 10:11:52<br/>Thời gian gọi: 00:00:51<br/>Cuộc gọi bị nhỡ",
           "source": "MissCall",
           "ticket_id": 9999,
           "type": 0
       },
       "ticket_no": 888,
       "ticket_source_end_status": 1,
       "service_id": 9999,
       "requester_id": 999,
       "assignee_id": -1
   },
   "action": "update",
   "call_info": {
       "answer_time": 0,
       "start_time": 1633489860000,
       "caller": "0889999999",
       "status_code": 0,
       "called": "1999999",
       "end_time": 1633489912861,
       "call_id": "20211006101009-HRFZNHMV-9999"
   },
   "object": "ticket"
}

```

### 2. Cuộc gọi vào IVR (Không chuyển ACD):

```json
{
   "account_id": 9999,
   "ticket": {
       "ticket_status": "new",
       "updated_at": 1633488353675,
       "ticket_comment": {
           "updated_at": "Wed Oct 06 09:45:53 ICT 2021",
           "commentator_id": 123391762,
           "created_at": "Wed Oct 06 09:45:53 ICT 2021",
           "comment": "Cuộc gọi vào IVR <\/br>Số gọi đến: 0889999999<\/br>Đầu số: 19009999<\/br>Id cuộc gọi: 20211006094514-HRFZNHMV-9999<\/br>Thời gian bắt đầu: 2021-10-06 09:45:14<\/br>Thời gian kết thúc: 2021-10-06 09:45:53<\/br>NodeName: Gọi vào<\/br>Dtmf: -2-#",
           "source": "IVR",
           "ticket_id": 259312810,
           "type": 0
       },
       "ticket_subject": "Cuộc gọi vào IVR từ : 0889999999",
       "ticket_no": 45028,
       "service_id": 0,
       "ticket_priority": "Normal",
       "ticket_source": "IVR",
       "created_at": 1633488353675,
       "ticket_id": 259312810,
       "requester_id": 123391762
   },
   "action": "update",
   "call_info": {
       "start_time": 1633488314064,
       "caller": "0889999999",
       "called": "19009999",
       "dtmf": "-2-#",
       "end_time": 1633488353669,
       "node_name": "Gọi vào",
       "call_id": "20211006094514-HRFZNHMV-9999"
   },
   "object": "ticket"
}
```

### 3. Ticket Cuộc gọi ra

```json
{   
   "account_id": 9999,
   "ticket": {
       "ticket_status": "solved",
       "ticket_subject": "Cuộc gọi ra gặp khách hàng tới 0889999999",
       "ticket_priority": "Normal",
       "ticket_source": "Voice Out",
       "created_at": 1633489494000,
       "ticket_id": 9999,
       "updated_at": 1633489530561,
       "ticket_comment": {
           "updated_at": 1633489530561,
           "commentator_id": 4444,
           "is_public": 1,
           "created_at": 1633489494488,
           "comment": "<b>Cuộc gọi ra<\/b><br/>Người gọi ra:  (admin@caresoft.vn)<br/>ID cuộc gọi: 20211006100454-EXGPSDDQ-9999<br/>Số điện thoại gọi tới: 0889999999<br/>Đầu số gọi ra: 1999999<br/>Thời gian bắt đầu: 2021-10-06 10:04:54<br/>Khách hàng trả lời cuộc gọi<br/>Thời gian trả lời: 2021-10-06 10:05:01<br/>Agent kết thúc cuộc gọi<br/>Thời gian kết thúc: 2021-10-06 10:05:30<br/>Thời lượng cuộc gọi: 00:00:29",
           "source": "Voice Out",
           "ticket_id": 9999,
           "type": 0
       },
       "ticket_no": 9999,
       "ticket_source_end_status": 0,
       "service_id": 8888,
       "requester_id": 113245755,
       "assignee_id": 3333
   },
   "action": "update",
   "call_info": {
       "answer_time": 1633489501551,
       "start_time": 1633489494000,
       "caller": "0889999999",
       "status_code": 200,
       "called": "1999999",
       "end_time": 1633489530561,
       "call_id": "20211006100454-EXGPSDDQ-9999"
   },
   "object": "ticket"
}
```

### 4. Tạo mới người dùng

```json
{
   "account_id": 1,
   "action": "create",
   "user": {
       "phone_no": "0889999999",
       "account_id": 1,
       "updated_at": 1633511901679,
       "role_id": 3,
       "created_at": 1633511901679,
       "id": 63203837,
       "username": "Tan Le"
   },
   "object": "user"
}
```

### 5. Cập nhật người dùng

```json
{
   "account_id": 1,
   "action": "update",
   "user": {
       "updated_at": 1633510473715,
       "changes": [
           {
               "field": "addition_field13",
               "value": "x123x"
           }
       ],
       "id": 63203835,
       "username": "Tan9999"
   },
   "object": "user"
}
```

### 6. Tạo mới tổ chức

```json
{
   "account_id": 1,
   "organization": {
       "note": "",
       "account_id": 1,
       "updated_at": 1633590006206,
       "organization_domain": "dev.caresoft.vn",
       "organization_id": 126,
       "created_at": 1633590006206,
       "details": "",
       "organization_name": "Công ty bột giặt"
   },
   "action": "create",
   "object": "organization"
}
```

### 7. Cập nhật tổ chức

```json
{
   "account_id": 1,
   "organization": {
       "updated_at": 1633589854414,
       "organization_id": 10,
       "changes": [
           {
               "field": "organization_name",
               "value": "Công ty cổ phần CareSoft"
           }
       ]
   },
   "action": "update",
   "object": "organization"
}
```

### 8. Tạo mới phiếu ghi

```json
{
  "account_id": 171,
  "ticket": {
    "ticket_comment": {
      "updated_at": 1684384652149,
      "commentator_id": 63215882,
      "is_public": 0,
      "created_at": 1684384652149,
      "comment": "Sample Internal note",
      "ticket_id": 322677,
      "type": 0
    },
    "ticket_no": 5,
    "ticket_status": "new",
    "last_change_status_at": 1684384652133,
    "addition_fields": [
      {
        "field": "addition_field1",
        "id": 6956,
        "label": "Abc",
        "value": "b",
         "value_id":"1242",
        "type":3
      },
      {
        "field": "addition_field2",
        "id": 6957,
        "label": "Phân loại phiếu ghi",
        "value": "Chưa phân loại",
        "value_id":"1222",
        "type":3
        
      },
      {
        "field": "addition_field3",
        "id": 6958,
        "label": "Ghi chú",
        "value": "",
        "type":"0"
      }
    ],
    "requester_id": 63215882,
    "ticket_subject": "Sample Ticket",
    "ticket_priority": "Normal",
    "ticket_source": "Web",
    "created_at": 1684384615500,
    "updated_at": 1684384652133,
    "ticket_id": 322677
  },
  "action": "create",
  "object": "ticket"
}
```

### 9. Cập nhật phiếu ghi

```json
{
  "account_id": 171,
  "ticket": { 
    "ticket_comment": {
      "updated_at": 1684385486529,
      "commentator_id": 63215882,
      "is_public": 0,
      "created_at": 1684385486529,
      "comment": "UpdateTicket",
      "ticket_id": 322677,
      "type": 1
    },
    "addition_field42": "",
    "ticket_no": 5,
    "ticket_status": "new",
    "last_change_status_at": 1684384652000,
    "addition_fields": [
      {
        "field": "addition_field1",
        "id": 6956,
        "label": "Abc",
        "value": "b",
         "value_id":"1242",
        "type":3
      },
      {
        "field": "addition_field2",
        "id": 6957,
        "label": "Phân loại phiếu ghi",
        "value": "Chưa phân loại",
        "value_id":"1222",
        "type":3
        
      },
      {
        "field": "addition_field3",
        "id": 6958,
        "label": "Ghi chú",
        "value": "",
        "type":"0"
      }
    ],
    "requester_id": 63215882,
    "ticket_subject": "Sample Ticket",
    "ticket_priority": "Normal",
    "ticket_source": "Web",
    "created_at": 1684384616000,
    "updated_at": 1684385486519,
    "assignee_id": 63215882,
    "ticket_id": 322677
  },
  "action": "update",
  "object": "ticket"
}
```

### 10.  Xóa phiếu ghi

```json
{
   "account_id": 1,
   "ticket": {"ticket_id":316702},
   "action": "delete",
   "object": "ticket"
}
```

### 11.  Ghép phiếu ghi

```json
{
   "account_id": 1,
   "mergeOption": {"copyComments":0,"secondaryTickets":[316708],"addCC":1,"primaryComment":"Phiếu ghi #220760 đã được đóng và hợp nhất vào phiếu ghi này","addFollow":1,"primaryIsPublic":0,"primaryTicket":316707,"secondaryComment":"Phiếu ghi này đã được đóng và hợp nhất vào phiếu ghi #220759","secondaryIsPublic":0},
   "action": "merge",
   "object": "ticket"
}
```

### 12. Phiếu ghi được gán

```json
{
    "object": "ticket",
    "action": "acd_assign",
    "data": {
        "assignee_id": 0,
        "ticket_id":316702,
        "assign_at": 1704961720473
    }
}
```


# Nhúng Live chat, Ticket Form

Các hướng dẫn tích hợp tính năng tạo box chat hoặc form đăng ký vào website

[Nhúng live chat vào website](/danh-muc/nhung-live-chat-ticket-form/nhung-live-chat-vao-website)

[Nhúng ticket form](/danh-muc/nhung-live-chat-ticket-form/nhung-ticket-form)


# Nhúng live chat vào website

Chat nhanh với khách hàng đang truy cập website của bạn. Tối ưu hoạt động  chăm sóc khách hàng.

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FIhF617jcIzAIqfKUTpRb%2FTichhopLiveChat.png?alt=media&amp;token=698b8d36-f448-4d0e-adbc-3698e9084475" alt=""><figcaption><p>Giao diện Live chat của Caresoft được nhúng trên trang chủ </p></figcaption></figure>

## Các bước chuẩn bị

* Tạo domain chat.
* Tạo dịch vụ &#x20;
* Chọn đúng domain chat cần lấy mã và copy mã
* Nhúng vào ứng dụng/website&#x20;

## Trình tự thực hiện&#x20;

{% hint style="info" %}
Các bước này cần tài khoản Admin truy cập vào CareSoft và thực hiện trên giao diện CareSoft
{% endhint %}

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FSZ152Em64Or2EZBsSqhK%2Fcauhinh.png?alt=media&amp;token=0dce74c9-a7b3-4d58-8410-d9962a37d458" alt=""><figcaption></figcaption></figure>

#### Tạo domain chat

Thông thường mỗi website sẽ nhúng 1 box chat riêng (có định danh riêng) để nhận diện và cấu hình độc lập nhau. Caresoft có thể tạo nhiều box chat riêng dành cho nhiều website.

Các domain có tiền tố là domain gốc CareSoft cung cấp cho khách hàng, Admin khai báo hậu tố và submit thông tin.&#x20;

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FtO1AevAYwSQjs21isIZv%2Fchat_themmoi_domain.png?alt=media&amp;token=db67ac7b-54b0-4f66-a37d-5e22294daf63" alt=""><figcaption></figcaption></figure>

Mặc định sẽ có một domain tương ứng với domain gốc của khách hàng.&#x20;

{% hint style="info" %}
Nên đặt các domain chat theo website/ứng dụng nơi nó được nhúng tới đảm bảo tính gợi nhớ thông tin dễ tra cứu sau này
{% endhint %}

#### Tạo dịch vụ chat để tiếp nhận yêu cầu.&#x20;

1 Box chat trên 1 website có thể điều hướng luồng chat tới nhiều bộ phận/chuyên viên tiếp nhận khác nhau. CareSoft gọi thành phần này là "Dịch vụ". Nếu bạn chỉ tạo 1 dịch vụ Hộp chat sẽ mặc định nhận dịch vụ đó và ẩn đi lựa chọn dịch vụ khi chat. Nếu bạn tạo nhiều hơn 1 dịch vụ. Thì trên giao diện khách hàng sẽ có thêm lựa chọn "Chọn dịch vụ".   Tương tự như tình huống vào 1 doanh nghiệp khách muốn gặp "Phòng Bán Lẻ" hay "Phòng CSKH".&#x20;

Dịch vụ là bắt buộc và cần tối thiểu 1 dịch vụ khi chat.  Dịch vụ không khởi tạo mặc định nên cần phải cấu hình.&#x20;

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2F5bDyus29eLcqSc7aCX8o%2Fchat_them_dichvu.png?alt=media&amp;token=1479c1e1-93cb-41c6-959d-7cdd4c1f58a1" alt=""><figcaption></figcaption></figure>

Sau khi tạo dịch vụ Thông qua tính năng gán độ ưu tiên, Admin có thể gán luồng chat cho chuyên viên tiếp nhận theo từng dịch vụ được tạo

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FSwcRr4DZIQoKEV29hG1q%2Fchat_danhsach_dichvu.png?alt=media&amp;token=27f2cd06-abf7-46a7-8079-ab0bbaf5528c" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Nên đặt tên dịch vụ gần với tên website/ứng dụng nơi hộp chat được nhúng vào&#x20;
{% endhint %}

#### Cấu hình hộp chat

Trong tab "Thông tin". Admin có thể tùy chỉnh thông tin hộp chat theo nhiều tùy chọn được cung cấp như "Logo", Màu Sắc, Vị trí,  Nội dung hiển thị.&#x20;

*Lưu ý chọn đúng domain chat cần cấu hình (Ô khoanh đỏ trong hình)*

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2Fm6KDJnH5Wklj1IfR4OGG%2Fchat_cauhinh_box_chat.png?alt=media&amp;token=e03c3415-6232-4d25-89a8-c0e7b9b4aa31" alt=""><figcaption></figcaption></figure>

#### Chọn mã nhúng và không gian nhúng (App hay Web)

Ở Tab Mã Nhúng, Admin lựa chọn không gian nhúng và các tùy chọn cụ thể với hộp chat sau đó copy code.&#x20;

*Cần lưu ý chọn đúng Domain cần nhúng (Phần khoanh đỏ) trong hình..*&#x20;

Copy đoạn code được CareSoft render và chuyển cho Lập trình viên thực hiện nhúng vào ứng dụng

Thông thường đoạn code nên đặt ở phần header  của giao diện trang web. Nơi được Include thông suốt vào các trang con của toàn trang web. Cần đảm bảo code nhúng được đặt vào vị trí có thể render ra giao diện HTML và có thể kiểm tra qua http request.

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2Fw5b5Hduy9j7356PACFjt%2Fchat_code_nhung.png?alt=media&amp;token=9ffbf122-183b-4a65-8af1-960b816fea71" alt=""><figcaption></figcaption></figure>

### Kiểm tra hoạt động&#x20;

Truy cập vào website/Ứng dụng đảm bảo hiển thị thông tin như mong muốn.

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FO83YaWJQmiPrpxTtr4yu%2Fchat_ketqua.png?alt=media&amp;token=0dd5b4de-935b-4285-b012-eeea19a1acf5" alt=""><figcaption><p>Trong hình dưới đây Box chat được nhúng có sẵn phần chọn dịch vụ với 2 dịch vụ được tạo phía trên. </p></figcaption></figure>


# CareSoft Live Chat SDK – API Hỗ Trợ Tương Tác Widget

CareSoft cung cấp các hàm JavaScript để tương tác trực tiếp với widget Live Chat, cho phép bạn điều khiển các hành vi trong box chat theo yêu cầu lập trình.

#### **Cách sử dụng**

Sau khi đã nhúng thành công widget Live Chat vào website, bạn có thể tương tác với box chat thông qua hàm toàn cục:

```javascript
cslw(action, params)
```

* `action` *(string)*: Tên hành động muốn thực hiện.
* `params` *(object)*: Tham số tùy chọn, chứa dữ liệu bổ sung phục vụ cho action.

⚠️ **Lưu ý:** Mọi action chỉ hoạt động sau khi box chat đã được khởi tạo thành công.

#### **Danh sách các action hỗ trợ**

| Tên Action            | Mô tả                                                | Ví dụ sử dụng                                                       |
| --------------------- | ---------------------------------------------------- | ------------------------------------------------------------------- |
| `open-widget`         | Mở widget chat lên (trạng thái hiển thị).            | `cslw('open-widget')`                                               |
| `reload-widget`       | Tải lại (re-initialize) widget chat.                 | `cslw('reload-widget')`                                             |
| `change-chat-service` | Thay đổi dịch vụ chat hiện tại theo `service_id`.    | `cslw('change-chat-service', { service_id: 123 })`                  |
| `compose-message`     | Gửi sẵn nội dung vào ô nhập tin nhắn trong box chat. | `cslw('compose-message', { message: 'Xin chào, tôi cần hỗ trợ!' })` |

#### **Ví dụ thực tế**

```html
<!-- Mở widget khi người dùng click nút -->
<button onclick="cslw('open-widget')">Chat với CSKH</button>

<!-- Chuyển sang dịch vụ hỗ trợ kỹ thuật -->
<button onclick="cslw('change-chat-service', { service_id: 456 })">Liên hệ bộ phận kỹ thuật</button>
```

***

#### 📍 **Ghi chú quan trọng**

* Chỉ nên gọi `cslw(...)` **sau khi widget đã được khởi tạo hoàn tất**.


# Nhúng ticket form

Ticket form là biểu mẫu đăng ký thông tin thường dùng để khách hàng khai báo thông tin trên website.&#x20;

Caresoft cung cấp tiện ích này giúp thông tin phản hồi từ khách hàng tới nhân viên chăm sóc khách hàng nhanh nhất và được điền trực tiếp vào các trường thông tin trên phiếu ghi &#x20;

### Autofill dữ liệu qua Url Query string

**Mục đích:**\
Hệ thống Caresoft hỗ trợ nhúng form khai báo thông tin khách hàng trực tiếp trên website. Thông tin người dùng nhập sẽ được gửi về hệ thống chăm sóc khách hàng nhanh chóng và chính xác.

#### 1. Tính năng Autofill qua URL

Sau khi tạo form thành công, bạn có thể khởi tạo link nhúng chứa các thông tin cần autofill bằng cách:

1. Truy cập giao diện “Gen link”.
2. Tick chọn các trường muốn thêm vào URL.
3. Hệ thống sẽ tự động generate link kèm theo các query string tương ứng.

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2F6uVaRYjUF7bCd16pOtkb%2Fimage.png?alt=media&amp;token=9519fd0f-5da3-46c7-b4ba-c02628368498" alt=""><figcaption></figcaption></figure>

#### 2. Cấu trúc URL được sinh ra

**Base URL:**

```
https://caresoft.vn/vi2/ticketForm/{form_id}
```

**Query Parameters (tùy theo checkbox được chọn):**

| Trường dữ liệu   | Query string sinh ra       | Ghi chú                               |
| ---------------- | -------------------------- | ------------------------------------- |
| Họ tên           | `username={{USERNAME}}`    | `{{USERNAME}}` là biến cần truyền     |
| Số điện thoại    | `userphone={{USER_PHONE}}` | `{{USER_PHONE}}` là biến cần truyền   |
| Email *(nếu có)* | `email={{USER_EMAIL}}`     | (có thể mở rộng nếu checkbox có thêm) |

**Ví dụ URL sau khi chọn 2 trường "Họ tên" và "Số điện thoại":**

```
https://caresoft.vn/vi2/ticketForm/1?username={{USERNAME}}&userphone={{USER_PHONE}}
```

👉 Bạn cần lập trình phía frontend để thay thế các placeholder `{{USERNAME}}`, `{{USER_PHONE}}` bằng dữ liệu thực tế từ hệ thống hoặc người dùng.

#### Gợi ý triển khai

* Nên sử dụng `encodeURIComponent()` để tránh lỗi khi giá trị chứa dấu cách hoặc ký tự đặc biệt.
* Chỉ truyền những trường thực sự cần autofill để tránh dư thừa dữ liệu trên URL.
* Có thể gắn link này vào button hoặc QR code để khách hàng tự động điền form.


# Hướng dẫn tích hợp Chat Caresoft vào Mobile App sử dụng React Native

Tài liệu hướng dẫn tích hợp Live chat của CareSoft vào các ứng dụng trên điện thoại của khách hàng

1. &#x20;**Mô hình hệ thống**

   <br>

   <figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2F0F00reujn8VDJSKl3l0T%2Fimage.png?alt=media&amp;token=efba14ba-2026-4d16-a22f-5464ce84dde6" alt=""><figcaption><p>Mô hình hệ thống</p></figcaption></figure>
2. **Tích hợp trên Mobile App**

**2.1:  Tạo đường link nhúng chat:**

```
let domain = “{domain_name}”;let domainId = “{domain_id}”;
let username = “”;
let email = “”;
let phone = “”;
let inApp= 1;
let queryString = "?domain=" + encodeURIComponent(domain) + "&domainId=" + encodeURIComponent(domainId) + "&username=" + encodeURIComponent(username) + "&email=" + encodeURIComponent(email) + "&phone=" + encodeURIComponent(phone)+ "&inApp=" + encodeURIComponent(inApp);
let link = “https://webchat.caresoft.vn:8091/index.html?key= Base64.btoa(queryString)&user_id={user_id};
```

**Trong đó:**

Domain: tên domain của khách hàng (Lấy trong màn hình Admin -> Quản lý dịch vụ chat)DomainId: id của domain (được caresoft cung cấp khi thực hiện tích hợp)

Link: “<https://webchat.caresoft.vn:8091/index.html?key=”> là địa chỉ server thực hiện test chat tích hợp.

Username: Tên user đăng nhập

Phone: số điện thoại của user đăng nhập

Email: Email của user đăng nhập.Base64 là thư viện mã hoá được viết sẵn (có sẵn trong project demo)

user\_id: là id định danh của end user được sử dụng làm tham số khi Caresoft gọi API nhận thông báo.\
**Tham số domain**

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FPEU5pOSrvm8Jy16FEMCW%2Fimage.png?alt=media&amp;token=ea19d4c7-a172-4b57-bc4a-40f07a99303a" alt=""><figcaption></figcaption></figure>

&#x20;**2.2: Sau khi tạo xong đường link sẽ thực hiện mở đường link đã được tạo trong webview (react-native-webview)**

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FHyPJFk7b4fG5UvOU1h47%2Fimage.png?alt=media&amp;token=062bb2c5-caf2-4224-8019-4edf2ef8d28a" alt=""><figcaption></figcaption></figure>

**2.3: Tích hợp gửi notification từ Server CareSoft**

Khách hàng mở API gửi thông báo xuống mobile cho CareSoft: Khách hàng mở 1 API service cho phép gửi thông báo xuống thiết bị. CareSoft sẽ gọi API này để gửi thông báo xuống điện thoại khách hàng khi khách hàng mất kết nối sockets


# Ứng dụng khác

Tích hợp các ứng dụng khác vào caresoft như Ladipage, Haravan, KiosViet


# Ladipage


# Case study

Một số trường hợp tích hợp điển hình

1. [Tạo phiếu ghi cuộc gọi qua API <br>](/danh-muc/case-study/tao-phieu-ghi-cho-mot-chien-dich-dang-chay)**Bài toán:** Khách hàng mua hàng rồi hủy đơn trên website. \
   Cần thực hiện tạo phiếu ghi gọi ra cho những khách hàng đó với bộ câu hỏi khảo sát? \
   Phiếu ghi sẽ nằm trong chiến dịch "Khảo sát lý do hủy đơn"? \
   Dữ liệu đơn hàng và số điện thoại của khách hàng được tự động đẩy từ CRM sang qua API
2. [Tạo phiếu ghi với thông tin trường động gửi kèm<br>](/danh-muc/restful-api-cua-caresoft/tao-phieu-ghi-lead-deal-kem-thong-tin-truong-dong)**Bài toán:**  Nhu cầu tích hợp CareSoft vào website bán hàng Online. Trong đó khi phát sinh đơn hàng, thì tạo phiếu ghi và gán phân loại đơn hàng là "mới" kèm giá trị đơn hàng là tổng tiền của đơn hàng trên CRM.<br>


# Tạo phiếu ghi cho một chiến dịch đang chạy

Hướng dẫn tạo phiếu ghi cho 1 chiến dịch đang chạy

*Bài toán:* Khách hàng mua hàng rồi hủy đơn trên website. \
Cần thực hiện tạo phiếu ghi gọi ra cho những khách hàng đó với bộ câu hỏi khảo sát? \
Phiếu ghi sẽ nằm trong chiến dịch "Khảo sát lý do hủy đơn?"\
Dữ liệu đơn hàng và số điện thoại của khách hàng được tự động đẩy từ CRM sang qua API

**Các thành phần cần chuẩn bị.**

### 1. Tạo kịch bản khảo sát khách hàng hủy đơn.

Sử dụng giao diện Caresoft. Chuyên viên tạo 1 kịch bản và ghi nhớ lại ID của kịch bản để sử dụng cho bước sau. Ở hình minh họa `script_id =506`

<div><figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FEeQ0zdORuiSAows6Xu4N%2FKichban.png?alt=media&amp;token=6ac16b92-d9bc-423c-9005-6a40f27d559c" alt=""><figcaption><p>Tạo 1 kịch bản gọi ra</p></figcaption></figure> <figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FE8mkHwqlOFtfTJ79TARt%2FScript_demo.png?alt=media&amp;token=77ba25fb-37a8-4fe9-9ec3-e78a702dd4a4" alt=""><figcaption><p>Trên giao diện quản lý kịch bản lưu giữ ID của kịch bản vừa tạo </p></figcaption></figure></div>

### &#x20;2. Tạo chiến dịch (Sử dụng giao diện caresoft)&#x20;

Sử dụng giao diện Caresoft chuyên viên được cấp quyền tạo 1 chiến dịch có tên "Khảo sát khách hàng hủy đơn" và ghi nhớ lại ID của chiến dịch để sử dụng ở bước kế tiếp. Ở hình minh họa biến `campaign_id = 387`

<div><figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FeJnzepCTzunxF6RS2qLF%2FChiendich1.png?alt=media&amp;token=6cee3d10-86ff-4b38-9fa0-f3ca0c3a7fe1" alt=""><figcaption><p>Tạo mới 1 chiến dịch</p></figcaption></figure> <figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FUBcVfB6JbQXUI7Kai3hc%2Fcampaign_demo.png?alt=media&amp;token=8cb7a995-715b-4727-b7e9-2ef14a542157" alt=""><figcaption><p>Ghi nhớ ID của chiến dịch tạo ra</p></figcaption></figure></div>

### 3. Tạo hành động chiến dịch (Sử dụng API)&#x20;

Sử dụng Api này để tạo hành động gọi ra cho chiến dịch trên. Sau đó lưu lại action\_id làm kết quả cho bước tiếp theo. Trong bước này sẽ cần `campaign_id` và `script_id` ở các bước 1 và 2 để thực hiện tạo hành động chiến dịch.

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FCe5hSqFE5aEi6vXZELdq%2FCampaign.png?alt=media&amp;token=453d2efa-40b7-4e36-bb37-9e5d6ed99e7a" alt=""><figcaption></figcaption></figure>

Mẫu request. Như trường hợp này  lưu lại biến `action_id =14897`

{% tabs %}
{% tab title="Request" %}

```json
{
    "action": {
        "description": "Khách gọi ngày 30-4-2023",
        "script_id": 506
    }
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
    "code": "ok",
    "action": {
        "updated_at": "2023-04-04 16:47:41",
        "description": "Khách gọi ngày 30-4-2023",
        "action_id": 14897,
        "created_at": "2023-04-04 16:47:41",
        "campaign_id": 387,
        "script_id": 506
    }
} 
```

{% endtab %}
{% endtabs %}

## Tạo hành động mẫu sử dụng gọi ra&#x20;

<mark style="color:orange;">`PUT`</mark> `{{domain}}/api/v1/campaigns/{{campaign_id}}/action`

Tạo hành động gọi ra cho chiến dịch mới&#x20;

#### Headers

| Name | Type   | Description                                                        |
| ---- | ------ | ------------------------------------------------------------------ |
| \*\* | String | [Thông tin xác thực chung ](/thong-tin-chung#phuong-thuc-xac-thuc) |

#### Request Body

| Name                                                | Type        | Description            |
| --------------------------------------------------- | ----------- | ---------------------- |
| action<mark style="color:red;">\*</mark>            | Object      |                        |
| action.script\_id<mark style="color:red;">\*</mark> | Int         | Id của kịch bản gọi ra |
| action.description                                  | String(100) | Tên mô tả hành động    |

{% tabs %}
{% tab title="200: OK Thành công" %}
{% tabs %}
{% tab title="Kết quả thành công" %}

```json
{
    "code": "ok",
    "action": {
        "updated_at": "2023-04-04 16:47:41",
        "description": "Khách gọi ngày 30-4-2023",
        "action_id": 14897,
        "created_at": "2023-04-04 16:47:41",
        "campaign_id": 387,
        "script_id": 506
    }
}
```

{% endtab %}
{% endtabs %}

{% endtab %}
{% endtabs %}

### 4. Tạo phiếu ghi

Chuẩn bị dữ liệu và gửi request theo mẫu dưới đây, với các biến `campaign_id`, `action_id` từ các bước trên  để thay vào.&#x20;

**Gọi vào api tạo ticket**&#x20;

## Tạo mới phiếu ghi&#x20;

<mark style="color:green;">`POST`</mark> `{{domain}}/api/v1/tickets`

Hàm tạo mới phiếu ghi và giao phiếu cho 1 chuyên viên cụ thể. Xem thêm về api [Phiếu ghi](/danh-muc/restful-api-cua-caresoft/phieu-ghi)

#### Headers

| Name                                   | Type   | Description                                                        |
| -------------------------------------- | ------ | ------------------------------------------------------------------ |
| \*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung ](/thong-tin-chung#phuong-thuc-xac-thuc) |

#### Request Body

| Name                                     | Type   | Description                      |
| ---------------------------------------- | ------ | -------------------------------- |
| \*\*\*<mark style="color:red;">\*</mark> | String | Theo object json mô tả phía dưới |

Mẫu body json tạo phiếu ghi cho chiến dịch đang chạy&#x20;

{% tabs %}
{% tab title="Mẫu body JSON gửi đi" %}

```json
{
    "ticket": {
        "phone": "0900000001",
        "username": "Nguyễn Văn Nam",
        "assignee_id": 29370874,
        "ticket_subject": "Khảo sát khách hàng hủy đơn #11222",
        "ticket_comment": "Khách hủy đơn mua 5 iphone",
        "is_public": 0,
        "campaign_id": 387,
        "campaign_action_id": "14897"
    }
}
```

{% endtab %}

{% tab title="Mô tả biến" %}

<table><thead><tr><th width="210">Trường</th><th>Ý nghia</th></tr></thead><tbody><tr><td>assignee_id</td><td>ID của chuyên viên nhận phiếu (Xem trong <a data-mention href="/danh-muc/restful-api-cua-caresoft/chuyen-vien">Chuyên viên</a>)</td></tr><tr><td>campaign_id</td><td>ID chiến dịch ở bước 2</td></tr><tr><td>campaign_action_id</td><td>ID  hành động ở bước 3</td></tr><tr><td>username</td><td>Họ tên của khách hàng trên CRM</td></tr><tr><td>ticket_subject</td><td>Tên phiếu ghi có nội dung gợi nhớ đến đơn hàng khách hủy</td></tr><tr><td>ticket_comment</td><td>Nội dung ghi chú cho chuyên viên. Có thể gửi vào mô tả chi tiết đơn hàng (Hàng gì, giá trị, số lượng, nơi mua ...) để chuyên viên có thông tin gợi nhớ cho khách hàng.</td></tr><tr><td>phone</td><td>Số điện thoại của khách hàng.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FyUAyhv4plZUe0SSMib4c%2FTicket2.png?alt=media&amp;token=1e725fce-ec16-4756-b657-375ba9655b62" alt=""><figcaption><p>Mô phỏng postman </p></figcaption></figure>

## 5. Kết quả&#x20;

Phiếu ghi được tạo với kịch bản của chiến dịch.

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FhHBYUSMpUUynG71gZkZY%2FKetqua.png?alt=media&amp;token=61d94f1f-4080-4a3a-bfec-2d23b2b036e4" alt=""><figcaption></figcaption></figure>

Dựa trên case này khách hàng có thể áp dụng vào nhiều trường hợp tương tự trong môi trường làm việc thực tế.&#x20;


# Tổng quan Chatbot

Chatbot CareSoft ngoài các tính năng cơ bản của chatbot như xây dựng các kịch bản trả lời tự động. Được kết nối trực tiếp trong hệ thống CareSoft để xử lý các kịch bản chuyên sâu.

Hỗ trợ tất cả các kênh chat được được kết nối trên CareSoft Contact Center bao gồm:\
LiveChat\
Facebook\
Instagram\
Zalo

Đăng nhập chatbot tại địa chỉ:\
<https://chatbot.caresoft.vn>


# Tích hợp hệ thống khác


# Thẻ JSON API

Cho phép cấu hình kịch bản chatbot gọi tới hệ thống khác qua API. Sử dụng phổ biến cho các trường hợp muốn tra cứu dữ liệu lưu tại hệ thống CRM ngoài.

Dữ liệu trả về từ API hỗ trợ các loại sau:\
1\. Tin nhắn văn bản\
2\. Tin nhắn văn bản có nút bấm\
3\. Tin nhắn hình ảnh\
4\. Tin nhắn video\
5\. Tin nhắn audio\
6\. Tin nhắn file\
7\. Tin nhắn slide ảnh\
8\. Tin nhắn phản hồi nhanh\
9\. Kịch bản chuyển tiếp tư vấn viên

Giao diện cấu hình thẻ JSON API trong chatbot

<div align="left"><figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FirBWwmmHJ2lhYrnG5WTm%2Fchatbot%20json%20api.png?alt=media&amp;token=95491b59-a8fc-4356-a19d-23f87baece60" alt="" width="563"><figcaption></figcaption></figure></div>

### **1. Tin nhắn văn bản**

```json
{
  "messages": [
    {
      "text": "Xin chào CareSoft!"
    },
    {
      "text": "Yêu cầu của bạn đang được xử lý!"
    }
  ]
}
```

### **2. Tin nhắn văn bản có nút bấm**

```json
{
  "messages":
  [{
    "attachment":{
      "type":"template",
      "payload":{
        "template_type":"button",
        "text":"What do you want to do next?",
        "buttons":[
          {
            "type":"postback",
            "Payload":"data sample",
            "title":"OK"
          },
          {
            "type":"web_url",
            "url":"https://caresoft.vn",
            "title":"Visit Website"
          },
          {
            "type":"phone_number",
            "title":"Call Now",
            "payload":"+842473048222"
          }
        ]
      }
    }
  }]
}
```

### 3. Tin nhắn hình ảnh

```json
{
  "messages": [
    {
      "attachment": {
        "type": "image",
        "payload": {
          "url": "https://home.caresoft.vn/assets/logo.png"
        }
      }
    }
  ]
}
```

### 4. Tin nhắn video

```json
{
  "messages": [
    {
      "attachment": {
        "type": "video",
        "payload": {
          "url": "https://caresoft.vn/assets/video.mp4"
        }
      }
    }
  ]
}
```

### 5. Tin nhắn audio

```json
{
  "messages": [
    {
      "attachment": {
        "type": "audio",
        "payload": {
          "url": "https://caresoft.vn/assets/audio.mp3"
        }
      }
    }
  ]
}
```

### 6. Tin nhắn file

```json
{
  "messages": [
    {
      "attachment": {
        "type": "file",
        "payload": {
          "url": "https://caresoft.vn/assets/guide.pdf"
        }
      }
    }
  ]
}
```

### 7. Tin nhắn slide ảnh

```json
{
  "messages": [{
      "attachment":{
        "type":"template",
        "payload":{
          "template_type":"generic",
          "image_aspect_ratio": "square",
          "elements":[
            {
              "title":"Sample Image",
              "image_url":"https://home.caresoft.vn/wp-content/themes/3c/img/logo.png",
              "subtitle":"Size: M",
              "buttons":[
                {
                  "type":"web_url",
                  "url":"https://caresoft.vn",
                  "title":"View Item"
                }
              ]
            },
            {
              "title":"Logo CS",
              "image_url":"https://home.caresoft.vn/wp-content/themes/3c/img/logo.png",
              "subtitle":"Size: L",
              "default_action": {
                "type": "web_url",
                "url": "https://caresoft.vn",
                "messenger_extensions": true
              },
              "buttons":[
                {
                  "type":"web_url",
                  "url":"https://caresoft.vn",
                  "title":"View Item"
                }
              ]
            }
          ]
        }
      }
    }]
}
```

### 8. Tin nhắn phản hồi nhanh

```json
{
  "messages": [
    {
      "text": "Chọn 1 đáp án:",
      "quick_replies": [
        {
          "content_type": "text",
          "title": "Call Center",
          "payload": "<POSTBACK_PAYLOAD>",
          "image_url": "http://example.com/img/red.png"
        },
        {
          "content_type": "text",
          "title": "Contact Center",
          "payload": "<POSTBACK_PAYLOAD>",
          "image_url": 'http://example.com/img/green.png"
        }
      ]
    }
  ]
}
```

### 9. Gặp tư vấn viên

{% code overflow="wrap" %}

```
Truyền vào danh sách ip phone của agent hoặc để rỗng nếu muốn gặp tất cả chuyên viên có kỹ năng
```

{% endcode %}

```json
{
  "connect_to_list_agent": []
}
```