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

API 4.0

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.

POSThttps://api.subiz.com.vn/4.0/accounts/{accid}/users/{uid}/messages

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 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.

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"
        }
      }
    }
  ]
}