> For the complete documentation index, see [llms.txt](https://api.omicall.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.omicall.com/omicall-api/khach-hang.md).

# Khách hàng

## Tạo mới khách hàng

<mark style="color:green;">`POST`</mark> `[URL]/api/v2/contact/add`

Tạo mới khách hàng

#### Headers

<table><thead><tr><th width="247">Name</th><th width="101">Type</th><th>Description</th></tr></thead><tbody><tr><td>Content-Type</td><td>String</td><td>application/json</td></tr><tr><td>Authorization</td><td>String</td><td>Bearer Access: Bearer 'token'</td></tr></tbody></table>

#### Request Body

<table><thead><tr><th width="273">Name</th><th width="102">Type</th><th>Description</th></tr></thead><tbody><tr><td>refId*</td><td>String</td><td>Mã của khách hàng bên đối tác</td></tr><tr><td>tags</td><td>array</td><td>Danh sách tên thẻ tag. Ví dụ: ["Lead", "Contact"]</td></tr><tr><td>business</td><td>array</td><td>Danh sách tên các ngành. Ví dụ: ["Food", "Education"]</td></tr><tr><td>categories</td><td>array</td><td>Danh sách tên các nhóm. Ví dụ: ["High Prioriry", "Low Priority"]</td></tr><tr><td>userOwnerEmail</td><td>string</td><td>Email của nhân viên phụ trách</td></tr><tr><td>avatarUrl</td><td>string</td><td>Avatar của khách hàng</td></tr><tr><td>fullName*</td><td>string</td><td>Tên đầy đủ của khách hàng</td></tr><tr><td>gender</td><td>string</td><td>Giới tính của khách hàng. Chấp nhận 1 trong các giá trị sau: male, female, other</td></tr><tr><td>passport</td><td>string</td><td>Hộ chiếu hoặc ID card</td></tr><tr><td>jobTitlte</td><td>string</td><td>Nghề nghiệp</td></tr><tr><td>address</td><td>string</td><td>Địa chỉ</td></tr><tr><td>refCode</td><td>string</td><td>Mã code của khách hàng bên đối tác</td></tr><tr><td>refType</td><td>string</td><td>Type của khách hàng bên đối tác</td></tr><tr><td>note</td><td>string</td><td>Ghi chú </td></tr><tr><td>phones*</td><td>array</td><td><p>Danh sách đối tượng PHONE<br>Ví dụ:</p><p>[</p><p>      {</p><p>             data  : "0989xxxxxx",</p><p>             type  : "home",</p><p>             valueType : "Nhà"</p><p>      }</p><p>]</p><p>//type => home, personal, office</p><p>//valueType => "Nhà", "Cá nhân", "Công ty"</p></td></tr><tr><td>emails</td><td>array</td><td><p>Danh sách đối tượng EMAIL<br>Ví dụ:</p><p>[</p><p>      {</p><p>             data : "xxx@gmail.com",</p><p>             type  : "home",</p><p>             valueType : "Nhà"</p><p>      }</p><p>]</p><p>//type => home, personal, office</p><p>//valueType => "Nhà", "Cá nhân", "Công ty"</p></td></tr><tr><td>filterContacts</td><td>array</td><td><p>Phễu khách hàng </p><p>Ví dụ:</p><p>[</p><p>      {</p><p>             id : "xxx",</p><p>             index : 1,</p><p>             secondLevelIndex : 1</p><p>      }</p><p>]</p><p>//id: Id của phễu</p><p>//index: thứ tự trạng thái cấp 1</p><p>//secondLevelIndex : thứ tự trạng thái cấp 2 (nếu có)</p></td></tr><tr><td></td><td></td><td></td></tr></tbody></table>

{% tabs %}
{% tab title="200 Dữ liệu trả về khi yêu cầu thành công" %}

```
{
    "status_code": 9999,
    "instance_id": "stg",
    "instance_name": "DESKTOP-3I0NHO0",
    "payload": true /false,
    "key_enabled": false
}
```

{% endtab %}
{% endtabs %}

## Tạo nhiều khách hàng

<mark style="color:green;">`POST`</mark> `[URL]/api/v2/contact/addMany`

Tạo mới khách hàng

#### Headers

<table><thead><tr><th width="247">Name</th><th width="101">Type</th><th>Description</th></tr></thead><tbody><tr><td>Content-Type</td><td>String</td><td>application/json</td></tr><tr><td>Authorization</td><td>String</td><td>Bearer Access: Bearer 'token'</td></tr></tbody></table>

#### Request Body

<table><thead><tr><th width="251">Name</th><th width="102">Type</th><th>Description</th></tr></thead><tbody><tr><td>data</td><td>array</td><td><p>Mảng thông tin các khách hàng cần thêm vào. Mẫu như sau:</p><p>[</p><p>      {</p><p>             refId : "",</p><p>             tags" : [],</p><p>             business : [],</p><p>             categories : [],</p><p>             userOwnerEmail : "",</p><p>             avatarUrl : "",</p><p>             fullName : "",</p><p>             gender  : "",</p><p>             passport : "",</p><p>             jobTitle : "",</p><p>             address : "",</p><p>             refCode : "",</p><p>             refType : "",</p><p>             note : "",</p><p>             phones : [],</p><p>             emails : [],</p><p>             filterContacts : []</p><p>      }</p><p>]</p><p>// kiểu giá trị của các trường tham khảo ở API Tạo mới khách hàng</p></td></tr><tr><td></td><td></td><td></td></tr><tr><td></td><td></td><td></td></tr></tbody></table>

{% tabs %}
{% tab title="200 Dữ liệu trả về khi yêu cầu thành công" %}

```
{
    "status_code": 9999,
    "instance_id": "stg",
    "instance_name": "DESKTOP-3I0NHO0",
    "payload": {"success" : true || "error" : {}},
    "key_enabled": false
}
```

{% endtab %}
{% endtabs %}

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

<mark style="color:green;">`POST`</mark> `[URL]/api/v2/contact/update`

Sửa thông tin khách hàng V2

#### Headers

<table><thead><tr><th width="251">Name</th><th width="103">Type</th><th>Description</th></tr></thead><tbody><tr><td>Authorization</td><td>string</td><td>Access Token : Bearer 'token'</td></tr><tr><td>Content-type</td><td>string</td><td>application/json</td></tr></tbody></table>

#### Request Body

<table><thead><tr><th width="253">Name</th><th width="284">Type</th><th>Description</th></tr></thead><tbody><tr><td>refId</td><td>string</td><td>Mã của khách hàng bên đối tác</td></tr><tr><td>_id</td><td></td><td>Id định danh khách hàng ở phía OMI (Trong trường hợp không sử dụng refId)</td></tr><tr><td>tags</td><td>array</td><td>Danh sách tên thẻ tag cần thêm vào. Ví dụ: ["Company"]</td></tr><tr><td>business</td><td>array</td><td>Danh sách tên các ngành cần thêm vào. Ví dụ: ["E-Commerce"]</td></tr><tr><td>categories</td><td>array</td><td>Danh sách tên các nhóm. Ví dụ: ["Medium"]</td></tr><tr><td>tagRemoves</td><td>array</td><td>Danh sách tên thẻ tag cần xóa. Ví dụ: ["Contact"]</td></tr><tr><td>businessRemoves</td><td>array</td><td>Danh sách tên các ngành cần xóa. Ví dụ: ["Food"]</td></tr><tr><td>categoriesRemoves</td><td>array</td><td>Danh sách tên các nhóm cần xóa. Ví dụ: ["High Priority"]</td></tr><tr><td>userOwnerEmail</td><td>string</td><td>Email của nhân viên phụ trách</td></tr><tr><td>avatarUrl</td><td>string</td><td>Avatar khách hàng</td></tr><tr><td>fullName</td><td>string</td><td>Tên khách hàng</td></tr><tr><td>gender</td><td>string</td><td>Giới tính khách hàng. Chấp nhận 1 trong các giá trị sau: male, female, other</td></tr><tr><td>passport</td><td>String</td><td>Hộ chiếu hoặc ID card</td></tr><tr><td>jobTitle</td><td>String</td><td>Nghề nghiệp</td></tr><tr><td>address</td><td>String</td><td>Địa chỉ</td></tr><tr><td>note</td><td>String</td><td>Ghi chú</td></tr><tr><td>phones</td><td>array</td><td><p>Danh sách đối tượng PHONE<br>Ví dụ:</p><p>[</p><p>      {</p><p>             data  : "0989xxxxxx",</p><p>             type  : "home",</p><p>             valueType : "Nhà"</p><p>      }</p><p>]</p><p>//type => home, personal, office</p><p>//valueType => "Nhà", "Cá nhân", "Công ty"</p></td></tr><tr><td>emails</td><td>array</td><td><p>Danh sách đối tượng EMAIL<br>Ví dụ:</p><p>[</p><p>      {</p><p>             data : "xxx@gmail.com",</p><p>             type  : "home",</p><p>             valueType : "Nhà"</p><p>      }</p><p>]</p><p>//type => home, personal, office</p><p>//valueType => "Nhà", "Cá nhân", "Công ty"</p></td></tr><tr><td>filterContacts</td><td>array</td><td><p>Phễu khách hàng </p><p>Ví dụ:</p><p>[</p><p>      {</p><p>             id : "xxx",</p><p>             index : 1,</p><p>             secondLevelIndex : 1</p><p>      }</p><p>]</p><p>//id: Id của phễu</p><p>//index: thứ tự trạng thái cấp 1</p><p>//secondLevelIndex : thứ tự trạng thái cấp 2 (nếu có)</p></td></tr><tr><td>otherDynamicUpdates</td><td>array</td><td><p>Cập nhật các trường thuộc tính động khác.</p><p>Ví dụ:</p><p>[</p><p>      {</p><p>             fieldCode: "xxx",</p><p>             values:  [</p><p>                     {</p><p>                              data : "yyy",</p><p>                              type  : "",</p><p>                              valueType : ""</p><p>                      }</p><p>              ]</p><p>      }</p><p>]</p></td></tr></tbody></table>

{% tabs %}
{% tab title="200 Dữ liệu thông tin khách hàng trả về, khi sửa thông tin thành công" %}

```
{
    "status_code": 9999,
    "instance_id": "stg",
    "instance_name": "DESKTOP-3I0NHO0",
    "payload": {//Thông tin KH sau update},
    "key_enabled": false
}
```

{% endtab %}
{% endtabs %}

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

<mark style="color:green;">`POST`</mark> `[URL]/api/v2/contact/changeAvatar`

Thay đổi Avatar KH V2

#### Headers

<table><thead><tr><th width="251">Name</th><th width="103">Type</th><th>Description</th></tr></thead><tbody><tr><td>Authorization</td><td>string</td><td>Access Token : Bearer 'token'</td></tr><tr><td>Content-type</td><td>string</td><td>application/json</td></tr></tbody></table>

#### Body FormData

<table><thead><tr><th width="253">Name</th><th width="284">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>Id định danh khách hàng ở phía OMI</td></tr><tr><td></td><td>file</td><td>File avatar cần thay đổi</td></tr></tbody></table>

{% tabs %}
{% tab title="200 Dữ liệu thông tin khách hàng trả về, khi sửa thông tin thành công" %}

```
{
    "status_code": 9999,
    "instance_id": "stg",
    "instance_name": "DESKTOP-3I0NHO0",
    "payload": {//Thông tin KH sau update},
    "key_enabled": false
}
```

{% endtab %}
{% endtabs %}

## Tìm kiếm khách hàng

<mark style="color:green;">`POST`</mark> `[URL]/api/v2/contact/search`

Tìm kiếm khách hàng

#### Query Parameters

<table><thead><tr><th width="259">Name</th><th width="107">Type</th><th>Description</th></tr></thead><tbody><tr><td>page</td><td>number</td><td>Trang. Bắt đầu từ 1. Mặc định là 1</td></tr><tr><td>size</td><td>number</td><td>Kích thước trang. Mặc định là 50</td></tr></tbody></table>

#### Headers

<table><thead><tr><th width="260">Name</th><th width="109">Type</th><th>Description</th></tr></thead><tbody><tr><td>Authorization</td><td>string</td><td>Bearer Access: Bearer 'token'</td></tr><tr><td>Content-type</td><td>string</td><td>application/json</td></tr></tbody></table>

#### Request Body

<table><thead><tr><th width="260">Name</th><th width="112">Type</th><th>Description</th></tr></thead><tbody><tr><td>keyword</td><td>String</td><td>Từ khóa tìm kiếm. Có thể một trong các giá trị<br>- Số điện thoại<br>- Email<br>- Họ và tên</td></tr><tr><td>tags</td><td>Array</td><td><p>Lọc theo tags</p><p>"tags": ["Demo"]</p></td></tr><tr><td>business</td><td>Array</td><td><p>Lọc theo ngành</p><p>"business": ["Demo"]</p></td></tr><tr><td>categories</td><td>Array</td><td>Lọc theo nhóm<br>"categories" :["Demo"]</td></tr><tr><td>ranges</td><td>Array</td><td><p>Lọc theo thời gian<br>"ranges" :[{</p><p>"field": "created_date",</p><p>"from": 1704819600000,</p><p>"to": 1704905999999</p><p>}]</p></td></tr><tr><td>includeIds</td><td>Array</td><td><p>Lọc khách hàng có id thuộc mảng</p><p>"includeIds":["123", "345"]</p></td></tr><tr><td>excludeIds</td><td>Array</td><td><p>Lọc khách hàng có id không thuộc mảng</p><p>"excludeIds":["123", "345"]</p></td></tr><tr><td>filterContactIds</td><td>Array</td><td>Lọc theo trạng thái khách hàng<br>"filterContactIds":["6465a66d61422d32ad0e4d40"]</td></tr></tbody></table>

{% tabs %}
{% tab title="200 Dữ liệu trả về thành công" %}

```
{
    "status_code": 9999,
    "instance_id": "stg",
    "instance_name": "DESKTOP-3I0NHO0",
    "payload": {
        "next_page": 1,
        "page_number": 1,
        "has_previous": false,
        "has_next": false,
        "total_pages": 1,
        "previous_page": 1,
        "total_items": 1,
        "page_size": 50
        "items": [
            {
                "public_id": "", // Id
                "create_by": {
                    "name": "TestBoss 123"
                },
                "last_update_by": {
                    "name": "TestBoss 123"
                },
                "created_date": 1576229754881,
                "last_updated_date": 1580807004410,
                "contact_type": "contact",
                "tags_view": null,
                "is_deleted": false, // Trạng thái
                "tags": [], // Thẻ tags khách hàng
                "attribute_structure": [
                    {
                        "identify": false,
                        "field_code": "full_name",
                        "field_type": "single_text",
                        "value": [
                            {
                                "display_value": "Trần Văn,
                                "data_type": null,
                                "value_type": null
                            }
                        ]
                    },
                    {
                        "identify": false,
                        "field_code": "job_title",
                        "field_type": "single_text",
                        "value": [
                            {
                                "display_value": "Giám đốc",
                                "data_type": null,
                                "value_type": null
                            }
                        ]
                    },
                    {
                        "identify": false,
                        "field_code": "gender",
                        "field_type": "radio",
                        "value": [
                            {
                                "display_value": "male",
                                "data_type": null,
                                "value_type": null
                            }
                        ]
                    },
                    {
                        "identify": false,
                        "field_code": "phone_number",
                        "field_type": "phone",
                        "value": [
                            {
                                "display_value": "0395187319",
                                "data_type": "personal",
                                "value_type": "Cá nhân"
                            }
                        ]
                    },
                    {
                        "identify": false,
                        "field_code": "mail",
                        "field_type": "email",
                        "value": [
                            {
                                "display_value": "tientv1212@gmail.com",
                                "data_type": "personal",
                                "value_type": "Cá nhân"
                            }
                        ]
                    },
                    {
                        "identify": false,
                        "field_code": "address",
                        "field_type": "single_text",
                        "value": [
                            {
                                "display_value": "Số 6 , đường 16, Hiệp Bình Chánh, Thủ Đức, HCM",
                                "data_type": null,
                                "value_type": null
                            }
                        ]
                    },
                    {
                        "identify": false,
                        "field_code": "passport",
                        "field_type": "single_text",
                        "value": [
                            {
                                "display_value": "",
                                "data_type": null,
                                "value_type": null
                            }
                        ]
                    },
                    {
                        "identify": false,
                        "field_code": "note",
                        "field_type": "multi_text",
                        "value": [
                            {
                                "display_value": "Khách hàng VIP, cần được chăm sóc kĩ",
                                "data_type": null,
                                "value_type": null
                            }
                        ]
                    },
                    {
                        "identify": false,
                        "field_code": "more_infomation",
                        "field_type": "customize",
                        "value": [
                            {
                                "display_value": "Nguyễn Văn B",
                                "data_type": "value1",
                                "value_type": "Người thân"
                            },
                            {
                                "display_value": "Vàng",
                                "data_type": "label2",
                                "value_type": "Màu sắc yêu thích"
                            }
                        ]
                    }
                ],
				"filter_contacts": [ //Thông tin trạng thái khách hàng, xem phần filter_contacts_view
                    {
                        "id": "62d8b0d1a89196134b65409c",
                        "index": 2,
                        "second_level_index": null,
                        "last_updated_date": 1715915262700,
                        "work_list": null,
                        "interactive_time": null,
                        "level": 99999,
                        "filter_contact": null,
                        "status_deals": null,
                        "total_deals": null,
                        "total_deals_rate": null,
                        "products": null,
                        "close_date_opportunity": null,
                        "rate": null,
                        "opportunity_expired": null,
                        "note": null,
                        "total_deals_string": null
                    },
                    {
                        "id": "62d91fa1b07a7920a8616693",
                        "index": 3,
                        "second_level_index": 2,
                        "last_updated_date": 1717138986593,
                        "work_list": [],
                        "interactive_time": null,
                        "level": 9999,
                        "filter_contact": null,
                        "status_deals": null,
                        "total_deals": null,
                        "total_deals_rate": null,
                        "products": null,
                        "close_date_opportunity": null,
                        "rate": null,
                        "opportunity_expired": null,
                        "note": null,
                        "total_deals_string": null
                    }
                ],
				"filter_contacts_view": [
                    {
                        "id": "62d8b0d1a89196134b65409c", //Id của bộ trạng thái
                        "name": "Trạng thái khách hàng", //Tên của bộ trạng thái
                        "first_index": 2, //Chỉ số hiện tại của bộ trạng thái
                        "first_name": "Có nhu cầu - Đang dùng thử" //Tên trạng thái hiện tại
                    },
                    {
                        "id": "62d91fa1b07a7920a8616693",//Id của bộ trạng thái
                        "name": "Trạng thái mới", //Tên của bộ trạng thái
                        "first_index": 3, //Chỉ số hiện tại của bộ trạng thái cấp 1
                        "first_name": "Có nhu cầu",//Tên trạng thái hiện tại cấp 1
                        "second_index": 2,//Chỉ số hiện tại của bộ trạng thái cấp 2
                        "second_name": "Đang dùng thử2"//Tên trạng thái hiện tại cấp 2
                    }
                ]
            }
        ]
    },
    "key_enabled": false
}
```

{% endtab %}
{% endtabs %}

## Xóa khách hàng

<mark style="color:red;">`DELETE`</mark> `[URL]/api/contacts/delete/:id`

Xóa khách hàng thông qua Id

#### Path Parameters

| Name | Type   | Description   |
| ---- | ------ | ------------- |
| id   | string | Id khách hàng |

#### Headers

| Name          | Type   | Description                 |
| ------------- | ------ | --------------------------- |
| Authorization | string | AccessToken. Bearer 'token' |
| Content-type  | string | application/json            |

{% tabs %}
{% tab title="200 Xóa khách hàng thành công" %}

```
{
    "status_code": 9999,
    "instance_id": "stg",
    "instance_name": "DESKTOP-3I0NHO0",
    "payload": true,
    "key_enabled": false
}
```

{% endtab %}
{% endtabs %}

## Tạo tương tác ghi chú

<mark style="color:green;">`POST`</mark> `[URL]/api/contacts/add-note`

Tạo nhiều tương tác. Request Body là Mảng đối tượng chứa các thuộc tính bên dưới

#### Request Body

| Name                                      | Type  | Description              |
| ----------------------------------------- | ----- | ------------------------ |
| note\_by                                  | Strig | Email nhân viên          |
| content<mark style="color:red;">\*</mark> | Sting | Nội dung ghi chú         |
| phone<mark style="color:red;">\*</mark>   | Strig | Số điện thoại khách hàng |

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

```javascript
{
    "status_code": 9999,
    "instance_id": "stg",
    "instance_version": "1.2.163",
    "payload": 1, // Số tương tác đã gửi đi
    "key_enabled": false
}
```

{% endtab %}
{% endtabs %}

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

<mark style="color:blue;">`GET`</mark> `[URL]/api/v2/contact/get/:id`

Lấy thông tin chi tiết của một khách hàng

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
| id   | String | Id contact  |

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

```javascript
{
    // Thông tin chi tiết 1 contact, xem mô tả trong phần API search
}
```

{% endtab %}
{% endtabs %}

## Danh sách các thuộc tính động

<mark style="color:blue;">`GET`</mark> `[URL]/api/v2/contact/layout/list`

Lấy danh sách thuộc tính động V2

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

```javascript
{
    // Thông tin các thuộc tính động
}
```

{% endtab %}
{% endtabs %}

## Danh sách bộ trạng thái khách hàng

<mark style="color:blue;">`GET`</mark> `[URL]/api/v2/contact/filterContact/list`

Lấy danh sách bộ trạng thái khách hàng

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

```javascript
{
    // Thông tin các bộ trạng thái
}
```

{% endtab %}
{% endtabs %}

## Chuyển đổi nhân viên phụ trách khách hàng

<mark style="color:green;">`POST`</mark> `[URL]/api/v3/agent/contact/transfer`&#x20;

Chuyển toàn bộ khách hàng do nhân viên gốc phụ trách hoặc có liên quan đến nhân viên gốc sang cho nhân viên mới

#### Headers

| Name      | Type   | Description |
| --------- | ------ | ----------- |
| x-api-key | String | API Key     |

#### Request Body

<table><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>sourceEmail<mark style="color:red;">*</mark></td><td>String</td><td>Email nhân viên gốc</td></tr><tr><td>targetEmail<mark style="color:red;">*</mark></td><td>String</td><td>Email nhân viên mới</td></tr><tr><td>previewChanges</td><td>Boolean</td><td><ul><li>true: Xem trước số lượng khách hàng sẽ bị thay đổi sau cập nhật (không khởi tạo tiến trình cập nhật) </li><li>false (mặc định): Khởi tạo tiến trình cập nhật</li></ul></td></tr><tr><td>callbackResultConfig</td><td>Object</td><td><p>Thông tin hook nhận kết quả sau khi hoàn tất tiến trình:</p><ul><li>url: url nhận hook</li><li>headers (optional): danh sách headers muốn gửi kèm khi nhận hook</li></ul><pre class="language-json"><code class="lang-json">{
    "url": "https://...",
    "headers": {
        "key1": "value1"
    }
}
</code></pre></td></tr></tbody></table>

{% tabs %}
{% tab title="202 Khởi tạo tiến trình thành công " %}

```json
{
    "instance_id": "stg",
    "payload": {
        "requestId": "270ea881-a6e1-44fb-9400-a89eb4ceab4b" // unique request id, trả về kèm theo webhook nếu có khai báo "callbackResultConfig"
    },
    "instance_version": "1.2.164",
    "key_enabled": false,
    "status_code": 9999
}
```

{% endtab %}

{% tab title="Webhook" %}

```json
{
  "requestId": "270ea881-a6e1-44fb-9400-a89eb4ceab4b", // unique request id
  "requestTimeMs": 1769163675593, // thời gian request
  "action": "CONTACT_AGENT_TRANSFER", // loại tiến trình
  "status": "SUCCESS", // trạng thái SUCCESS/ERROR
  "responseTimeMs": 1769163675890, // thời gian kết thúc
  "payload": {
    "updatedRecords": 8 // Số lượng record được cập nhật
  }
}
```

{% endtab %}
{% endtabs %}