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 sẽ đơn giản hơn.
Trước khi gửi
- Lấy Bearer access token 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
uidcủa đường dẫn. - Định danh kênh. Đặt
channel,channel_sourcevà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 chouidtrong đườ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. |
Một touchpoint mô tả một đích đến:
{
"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, 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:
{
"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.
Đừ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.
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"
}
}
}
]
}