Dùng endpoint này khi bạn đã có ID hội thoại. Để liên hệ khách hàng qua định danh kênh, hãy dùng Gửi tin nhắn cho khách hàng.
Trước khi gửi
- Lấy Bearer access token.
- Tìm ID hội thoại, ví dụ từ sự kiện webhook hoặc Lấy thông tin hội thoại.
- Dùng một hội thoại 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.
Body yêu cầu
Body là một sự kiện. Tin nhắn đặt trong data.message.
| Trường | Kiểu | Mô tả |
|---|---|---|
cid (đường dẫn) |
string | Hội thoại cần gửi tới. |
type |
string | Tùy chọn. Mặc định là message_sent. |
data.message.format |
string | plaintext hoặc block. Xem Định dạng tin nhắn. |
data.message.text |
string | Nội dung văn bản cho plaintext. |
data.message.block |
object | Cây block cho tin nhắn block. |
data.message.attachments |
array | Tùy chọn: tệp, nút bấm hoặc thẻ. Xem Tệp đính kèm. |
Một tin nhắn văn bản thuần:
{
"type": "message_sent",
"data": {
"message": {
"format": "plaintext",
"text": "Hello! How can we help?"
}
}
}
Trường do Subiz đặt
Bạn không cần gửi các trường này. Subiz đặt chúng cho mọi yêu cầu:
created: thời điểm hiện tại, tính bằng mili giây Unix.account_id: tài khoản của access token.data.message.conversation_idvàdata.conversation.id: giá trịcidtrong URL. Giá trị trong body sẽ bị thay thế.
Phản hồi
Yêu cầu thành công trả HTTP 200 cùng sự kiện đã gửi dưới dạng JSON, không có lớp bọc thêm. Một số trường:
{
"id": "event_example",
"account_id": "account_example",
"type": "message_sent",
"created": 1763107200000,
"data": {
"message": {
"conversation_id": "conversation_example",
"format": "plaintext",
"text": "Hello! How can we help?"
}
}
}
Trường rỗng bị lược bỏ. Lưu id của sự kiện nếu bạn cần đối chiếu tin nhắn sau này trong lịch sử tin nhắn hoặc sự kiện webhook.
Phản hồi 200 nghĩa là Subiz đã nhận tin nhắn. Nó không xác nhận tin đã tới kênh bên ngoài như Facebook hoặc Zalo.
Giới hạn
- Tin nhắn gửi bằng token của agent được tính vào hạn mức của agent đó: 5 tin mỗi giây, 60 tin mỗi phút và 5.000 tin mỗi ngày UTC. Xem Giới hạn gửi tin nhắn.
- Kích thước văn bản, tệp đính kèm và trường bị giới hạn. Xem Giới hạn tin nhắn.
Lỗi và thử lại
Kiểm tra mã trạng thái HTTP trước khi đọc body. Yêu cầu có thể thất bại do JSON không hợp lệ, lỗi xác thực, người gửi bị chặn, giới hạn tốc độ (429) hoặc kiểm tra dữ liệu ở dịch vụ hội thoại. 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, và endpoint này không có khóa idempotency. Hãy kiểm tra lịch sử tin nhắn trước.
Yêu cầu HTTP
Thay YOUR_CID bằng ID hội thoại và YOUR_ACCESS_TOKEN bằng token của bạn.
POST https://api.subiz.com.vn/4.1/conversations/YOUR_CID/messages
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
{
"type": "message_sent",
"data": {
"message": {
"text": "Hello! How can we help?",
"format": "plaintext"
}
}
}