SubizTài liệu API
Bắt đầu

API 4.0 · 4.1

Subiz API

Kết nối hệ thống của bạn với khách hàng, hội thoại, tin nhắn và webhook của Subiz.

Dùng Subiz API để đồng bộ hồ sơ khách hàng với CRM, gửi tin nhắn, điều phối agent và nhận cập nhật trên máy chủ của bạn.

Trong Subiz, user là khách hàng và agent là nhân viên của doanh nghiệp. Một hội thoại (conversation) kết nối những người tham gia với tin nhắn và lịch sử sự kiện của họ.

Bắt đầu từ đây

  1. Đọc các khái niệm cốt lõi bên dưới để hiểu các đối tượng và ID bạn sẽ dùng.
  2. Làm theo Xác thực để tạo access token cho tài khoản của bạn.
  3. Kiểm tra token bằng /4.1/me, rồi chọn một tác vụ bên dưới.

Giữ token trên máy chủ của bạn. Yêu cầu dùng quyền của agent đã tạo token. Thay ID và giá trị mẫu bằng dữ liệu của tài khoản bạn đang tích hợp.

Chọn tác vụ

Tôi muốn… Bắt đầu với
Đồng bộ hồ sơ khách hàng Tạo khách hàng hoặc cập nhật thông tin khách hàng.
Trả lời trong một hội thoại có sẵn Gửi tin nhắn vào hội thoại, dùng ID hội thoại.
Gửi qua kênh của khách hàng Gửi tin nhắn cho khách hàng, dùng ID khách hàng và đích đến trên kênh.
Điều phối agent Mời agent tham gia, hoặc giao agent phụ trách hội thoại.
Phản ứng khi khách hàng hoặc tin nhắn thay đổi Thiết lập máy nhận webhook và đọc ví dụ dữ liệu sự kiện.

Với nội dung phong phú, xem Định dạng tin nhắn cho văn bản, block và liên kết, và Tệp đính kèm cho ảnh, video, âm thanh và tệp.

Mối quan hệ giữa các đối tượng

Khi Alex liên hệ với doanh nghiệp của bạn, Alex là một user. Sam, nhân viên trả lời, là một agent. Cuộc trao đổi của họ diễn ra trong một hội thoại. Mỗi tin nhắn được mang trong một sự kiện (event).

Đối tượng Đại diện cho
Account Tài khoản doanh nghiệp mà tích hợp của bạn kết nối tới.
User Hồ sơ khách hàng, gồm thuộc tính và định danh kênh.
Agent Nhân viên phục vụ khách hàng.
Conversation Một tương tác có người tham gia, người phụ trách và lịch sử sự kiện.
Event Một việc đã xảy ra, như một tin nhắn hoặc một lần giao việc.
Message Văn bản, block phong phú hoặc tệp đính kèm bên trong một sự kiện.

Các ví dụ hiển thị một số trường được chọn từ schema đối tượng dùng chung của Subiz. Chúng dùng giá trị giả lập và ID nhất quán; đây không phải phản hồi API đầy đủ hay body của yêu cầu tạo. Mỗi endpoint quy định trường nào được nhận hoặc trả về. Trường rỗng hoặc tùy chọn có thể bị lược bỏ.

Không nhầm lẫn các ID. ID khách hàng, ID hội thoại và ID hồ sơ bên ngoài chỉ những thứ khác nhau. Lưu ID tài khoản cùng ID tài nguyên khi tích hợp nhiều doanh nghiệp.

Account

Account đại diện cho một doanh nghiệp trong Subiz. Định danh của chính nó là id; các đối tượng khác tham chiếu tới nó qua account_id. owner_id là agent sở hữu tài khoản.

{
  "id": "account_example",
  "name": "Example Store",
  "owner_id": "agent_example",
  "state": "activated"
}

Dùng access token của đúng tài khoản. Xem Xác thực.

Agent

Agent là một nhân viên trong tài khoản. Dùng id của agent khi mời agent hoặc đặt assignee của hội thoại.

{
  "id": "agent_example",
  "account_id": "account_example",
  "fullname": "Sam Example",
  "email": "sam@example.com",
  "state": "active"
}

fullname là trường trực tiếp của agent. Tên khách hàng thì dùng thuộc tính.

Khách hàng và định danh kênh

User là một khách hàng. Khách hàng này có định danh Facebook: channel_source xác định trang (page), còn profile_id xác định hồ sơ trên trang đó.

{
  "id": "user_example",
  "account_id": "account_example",
  "channel": "facebook",
  "channel_source": "page_example",
  "profile_id": "profile_example",
  "attributes": [
    {
      "key": "fullname",
      "text": "Alex Example"
    }
  ]
}

Không nhầm id của Subiz với profile_id. Dùng Tìm hoặc tạo theo định danh kênh để tìm user Subiz từ kênh, nguồn và hồ sơ.

Thuộc tính

Mỗi phần tử trong user.attributes là một Attribute. Tìm thuộc tính theo key, không theo vị trí trong mảng. Thuộc tính này lưu tên khách hàng:

{
  "key": "fullname",
  "text": "Alex Example"
}

Đọc trường giá trị phù hợp với thuộc tính: text, number, boolean hoặc datetime. Giá trị datetime là chuỗi ngày giờ. Đừng giả định mọi thuộc tính đều dùng text.

Touchpoint

Touchpoint mô tả ngữ cảnh kênh của hội thoại hoặc đích đến của tin nhắn. Trong ví dụ Facebook này, source là trang và id là hồ sơ của khách hàng trên trang đó:

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

Các giá trị này tương ứng với channel, channel_source và profile_id của user ở trên. Ý nghĩa của id trong touchpoint phụ thuộc vào kênh; nó cũng có thể là một bình luận hoặc đích đến khác. Dùng giá trị của tích hợp đã kết nối, không dùng ID user của Subiz thay cho đích đến.

Hội thoại, thành viên và người phụ trách

Conversation có ID riêng, thành viên, ngữ cảnh kênh và lịch sử sự kiện. Một khách hàng có thể tham gia nhiều hội thoại. Ở đây, Sam vừa là thành viên vừa là agent phụ trách:

{
  "id": "conversation_example",
  "account_id": "account_example",
  "state": "active",
  "assignee": "agent_example",
  "members": [
    {
      "id": "user_example",
      "type": "user",
      "membership": "active"
    },
    {
      "id": "agent_example",
      "type": "agent",
      "conversation_id": "conversation_example",
      "membership": "active"
    }
  ],
  "touchpoint": {
    "channel": "facebook",
    "source": "page_example",
    "id": "profile_example"
  }
}

assignee là agent phụ trách. Trường này có thể rỗng hoặc bị lược bỏ khi hội thoại chưa được giao. members mô tả việc tham gia; nó không đồng nghĩa với quyền phụ trách.

Thành viên hội thoại

ConversationMember xác định một người tham gia bằng type và id. membership ghi trạng thái tham gia của họ.

{
  "id": "agent_example",
  "type": "agent",
  "conversation_id": "conversation_example",
  "membership": "active"
}

Mời agent thêm một agent có sẵn làm người tham gia. Giao agent thay đổi người phụ trách. Giao việc trực tiếp không thêm agent vào members.

Tin nhắn và sự kiện

Message

Message chứa nội dung. Tin nhắn văn bản thuần này thuộc hội thoại ở trên:

{
  "conversation_id": "conversation_example",
  "format": "plaintext",
  "text": "Hello Alex"
}

Đây là đối tượng tin nhắn, không phải toàn bộ body của yêu cầu gửi. Gửi tin nhắn vào hội thoại đặt nó trong data.message và lấy ID hội thoại từ URL. Gửi tin nhắn cho khách hàng dùng cấu trúc yêu cầu khác và cần ngữ cảnh đích đến trên kênh.

Dữ liệu sự kiện

Data chứa đối tượng liên quan tới sự kiện. Với message_sent, nó chứa message:

{
  "message": {
    "conversation_id": "conversation_example",
    "format": "plaintext",
    "text": "Hello Alex"
  }
}

Các loại sự kiện khác có thể mang user hoặc conversation. Kiểm tra type của sự kiện trước khi truy cập trường lồng nhau.

Tác nhân

Đối tượng By (tùy chọn) xác định ai gây ra sự kiện. Nó xuất hiện dưới dạng event.by:

{
  "id": "agent_example",
  "type": "agent"
}

type có thể là user, agent hoặc bot. Tác nhân không nhất thiết là người phụ trách hội thoại. Một số sự kiện không có by hoặc chỉ có ngữ cảnh thiết bị mà không có ID tác nhân.

Event

Event kết hợp định danh, loại, thời gian, tác nhân và dữ liệu. Đây là ví dụ đầy đủ bao quanh tin nhắn ở trên:

{
  "id": "event_example_1",
  "account_id": "account_example",
  "created": 1794614400000,
  "type": "message_sent",
  "by": {
    "id": "agent_example",
    "type": "agent"
  },
  "data": {
    "message": {
      "conversation_id": "conversation_example",
      "format": "plaintext",
      "text": "Hello Alex"
    }
  }
}

created là thời điểm Subiz ghi nhận, tính bằng mili giây Unix. event_time, nếu có, là thời điểm xảy ra gốc. id của event định danh sự kiện; đừng thay bằng ID tin nhắn hay ID hội thoại lồng bên trong.

Lịch sử hội thoại chứa sự kiện, không chỉ tin nhắn. Một sự kiện message_sent hoặc một phản hồi gửi thành công không tự nó xác nhận tin đã tới kênh bên ngoài.

Tin nhắn định dạng phong phú bằng block

Hướng dẫn đầy đủ về văn bản thuần, liên kết và kiểu chữ có trong Định dạng tin nhắn.

Block

Block là một nút trong cây nội dung phong phú. type chọn loại nút, content chứa các nút con, và nút văn bản dùng text. Nút văn bản có thể có bold, italic hoặc underline.

{
  "type": "paragraph",
  "content": [
    {
      "type": "text",
      "text": "Hello "
    },
    {
      "type": "text",
      "text": "Alex",
      "bold": true
    }
  ]
}

Nội dung này hiển thị là “Hello Alex”. Block là một đối tượng JSON, không phải chuỗi HTML.

Tin nhắn phong phú

Đặt block vào message.block và đặt format là block:

{
  "conversation_id": "conversation_example",
  "format": "block",
  "block": {
    "type": "paragraph",
    "content": [
      {
        "type": "text",
        "text": "Hello "
      },
      {
        "type": "text",
        "text": "Alex",
        "bold": true
      }
    ]
  }
}

Subiz có thể tạo văn bản thuần từ block mà vẫn giữ cây block. Lưu cây block nếu bạn cần định dạng. Mô hình này cũng hỗ trợ ảnh, liên kết, danh sách và bảng; cách hiển thị phụ thuộc vào kênh đích.

Tệp đính kèm

Xem Tệp đính kèm để có ví dụ về ảnh, video, âm thanh, tệp và nội dung tương tác.

Mỗi phần tử trong message.attachments là một Attachment. Ví dụ tệp này dùng URL giả lập; size tính bằng byte:

{
  "type": "file",
  "mimetype": "application/pdf",
  "url": "https://example.com/guide.pdf",
  "name": "guide.pdf",
  "size": 2048
}

Đặt đối tượng đính kèm trong mảng attachments, không đặt trong block.content. Tin nhắn có thể có tệp đính kèm ngay cả khi text rỗng.

Webhook kết nối hệ thống của bạn

Lời gọi API yêu cầu thực hiện hành động; webhook thông báo sự kiện cho tích hợp của bạn. Một lần gửi webhook bọc các sự kiện trong mảng events. Cùng sự kiện ví dụ ở trên sẽ có dạng:

{
  "events": [
    {
      "id": "event_example_1",
      "account_id": "account_example",
      "created": 1794614400000,
      "type": "message_sent",
      "by": {
        "id": "agent_example",
        "type": "agent"
      },
      "data": {
        "message": {
          "conversation_id": "conversation_example",
          "format": "plaintext",
          "text": "Hello Alex"
        }
      }
    }
  ]
}

Một lần gửi có thể chứa nhiều sự kiện. Xác minh chữ ký, sau đó xử lý từng sự kiện theo type và loại trùng theo (account_id, id).

Xem Nhận sự kiện webhook để thiết lập và Ví dụ dữ liệu sự kiện cho các loại sự kiện khác. Phần bao của lần gửi không phải là đối tượng cấu hình Webhook.

Yêu cầu API và phiên bản

Gửi yêu cầu tới https://api.subiz.com.vn. Mỗi trang endpoint hiển thị URL đầy đủ, phương thức HTTP, header và body JSON khi cần.

Tài liệu này bao gồm API 4.0 và 4.1. Dùng đúng phiên bản trong URL của từng endpoint như đã ghi; các thao tác khác nhau có thể dùng phiên bản khác nhau. Xem Nhật ký thay đổi để biết cập nhật tài liệu và thông báo thay đổi API.

Trước khi chạy thật

Dùng với công cụ của bạn

Đọc trang này dưới dạng Markdown. Với công cụ AI, dùng mục lục tài liệu hoặc toàn bộ tài liệu.