# Chuyên viên

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FhcSyhK3uSYpjVvlMeKCE%2FCauHinhChuyenVien.png?alt=media&#x26;token=535c14f0-b870-4a51-9528-a702b0322dae" alt=""><figcaption><p>Giao diện cấu hình chuyên viên trê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 ](https://docs.caresoft.vn/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&#x26;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"
        }
```