# Tin nhắn Zalo

## 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** \
\&#xNAN;***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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.caresoft.vn/danh-muc/restful-api-cua-caresoft/tin-nhan-zalo.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.