# Gửi tin nhắn cho khách hàng

Gửi tin nhắn cho khách hàng qua một kênh đã kết nối.

API 4.0

Dùng endpoint này để nhắn cho khách hàng qua định danh kênh, như hồ sơ Facebook hoặc Zalo. Bạn không cần ID hội thoại. Nếu đã có, [Gửi tin nhắn vào hội thoại](/developers/vi/api-reference/messages/send) sẽ đơn giản hơn.

## Trước khi gửi

- Lấy [Bearer access token](/developers/vi/get-started/authentication) và ID tài khoản.
- Biết định danh kênh của khách hàng: kênh, nguồn và ID hồ sơ từ tích hợp đã kết nối.
- Dùng một khách hàng thử nghiệm khi phát triển. Mỗi yêu cầu thành công đều gửi một tin nhắn thật.

## Xác định khách hàng

Chọn một trong hai cách:

- **ID user Subiz.** Đặt ID khách hàng vào phân đoạn `uid` của đường dẫn.
- **Định danh kênh.** Đặt `channel`, `channel_source` và `profile_id` ở cấp ngoài cùng của body. Subiz tìm khách hàng có định danh đó, hoặc tạo mới, và dùng khách hàng này thay cho `uid` trong đường dẫn.

Cách thứ hai cần cả `channel` và `profile_id`. Nếu thiếu, `uid` trong đường dẫn được dùng.

## Body yêu cầu

| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `accid` (đường dẫn) | string | ID tài khoản của bạn. |
| `uid` (đường dẫn) | string | ID khách hàng. Bị bỏ qua khi có định danh kênh. |
| `channel` | string | Tùy chọn. Kênh của định danh, như `facebook` hoặc `zalo`. |
| `channel_source` | string | Tùy chọn. Trang hoặc tài khoản đã kết nối, như ID trang Facebook. |
| `profile_id` | string | Tùy chọn. ID của khách hàng trên kênh đó. |
| `messages` | array | Các sự kiện tin nhắn sẽ thử, theo thứ tự. Tối đa năm. |
| `messages[].type` | string | Dùng `message_sent`. |
| `messages[].touchpoint` | object | Nơi gửi tới: `channel`, `source` và `id`. |
| `messages[].data.message` | object | Nội dung tin nhắn. Xem [Định dạng tin nhắn](/developers/vi/messages/formats). |

Một touchpoint mô tả một đích đến:

```json
{
  "channel": "facebook",
  "source": "page_example",
  "id": "profile_example"
}
```

`source` là trang hoặc tài khoản đã kết nối. Ý nghĩa của `id` phụ thuộc vào kênh; thường là ID hồ sơ của khách hàng trên kênh đó. Dùng giá trị từ tích hợp của bạn, không dùng ID user Subiz.

## Đích đến dự phòng

`messages` là danh sách phương án thay thế, không phải gửi hàng loạt. Subiz thử từng phần tử theo thứ tự và dừng sau lần gửi thành công đầu tiên. Dùng cách này để chuyển sang kênh khác, ví dụ Zalo khi Facebook thất bại.

Để gửi tới một đích, chỉ đưa một phần tử. Với token của agent, mảng dài hơn năm phần tử bị từ chối, và mọi phần tử đều được tính vào [giới hạn gửi tin nhắn](/developers/vi/get-started/usage-limits#giới-hạn-gửi-tin-nhắn), kể cả khi không bao giờ được gửi.

Subiz có thể dừng sớm nếu khách hàng đã hủy đăng ký nhận tin trên kênh đó.

## Phản hồi

Yêu cầu thành công trả HTTP `200` cùng một sự kiện: tin nhắn đã được gửi. Phản hồi không liệt kê kết quả của các phần tử khác. Một số trường:

```json
{
  "id": "event_example",
  "account_id": "account_example",
  "type": "message_sent",
  "created": 1763107200000,
  "data": {
    "message": {
      "format": "plaintext",
      "text": "Hello! How can we help?"
    }
  }
}
```

Phản hồi `200` không xác nhận kênh bên ngoài đã chuyển tin tới khách hàng.

## Lỗi và thử lại

Kiểm tra mã trạng thái HTTP trước khi đọc body. Việc gửi cũng có thể bị kênh từ chối, ví dụ khi tích hợp đã ngắt kết nối hoặc kênh không cho phép tin nhắn đó. Xem [Xử lý lỗi](/developers/vi/get-started/errors).

Đừng thử lại mù quáng sau khi hết thời gian chờ; tin nhắn có thể đã được gửi.

## Yêu cầu HTTP

Thay các giá trị `YOUR_…`. Thêm `channel`, `channel_source` và `profile_id` ở cấp ngoài cùng để xác định khách hàng theo định danh kênh thay vì `uid`.

```http
POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/users/YOUR_UID/messages
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "messages": [
    {
      "type": "message_sent",
      "touchpoint": {
        "channel": "YOUR_CHANNEL",
        "source": "YOUR_SOURCE",
        "id": "YOUR_PROFILE_ID"
      },
      "data": {
        "message": {
          "text": "Hello! How can we help?",
          "format": "plaintext"
        }
      }
    }
  ]
}
```