SubizTài liệu API
Hội thoại và tin nhắn

API 4.1

Gửi tin nhắn vào hội thoại

Gửi tin nhắn vào một hội thoại có sẵn.

POSThttps://api.subiz.com.vn/4.1/conversations/{cid}/messages

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

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_id và data.conversation.id: giá trị cid trong 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"
    }
  }
}