SubizTài liệu API
Webhook

Webhook · Không phụ thuộc phiên bản API

Ví dụ dữ liệu sự kiện

Đọc sự kiện tin nhắn, khách hàng và hội thoại trong một lần gửi webhook.

Các ví dụ dưới đây là payload rút gọn với giá trị giả lập. Chúng cho thấy các trường được hỗ trợ, không phải danh mục sự kiện đầy đủ hay cam kết rằng trường tùy chọn luôn có mặt.

Chọn loại sự kiện

Sự kiện Đối tượng dữ liệu Dùng để
message_sent data.message Nhận tin nhắn và liên kết chúng với hội thoại.
user_created data.user Tạo hoặc liên kết hồ sơ khách hàng trong CRM.
user_info_updated data.user Đồng bộ thông tin khách hàng.
conversation_assigned data.conversation Cập nhật agent phụ trách.
conversation_unassigned data.conversation Bỏ agent phụ trách.

Chọn ba loại đầu tiên trong Tùy chỉnh sự kiện khi tạo webhook. Sự kiện giao việc được backend hỗ trợ nhưng chưa có trong form tạo hiện tại; các ví dụ giao việc chỉ áp dụng cho những đăng ký đã được cấu hình sẵn cho các loại đó.

Đọc phần bao của sự kiện

Trường Ý nghĩa
id ID sự kiện. Kết hợp với account_id để loại trùng khi xử lý.
account_id Tài khoản Subiz mà sự kiện thuộc về.
type Tên sự kiện. Dùng để chọn cách đọc data.
created Thời điểm Subiz ghi nhận sự kiện, tính bằng mili giây Unix.
event_time Thời điểm xảy ra gốc, nếu có, tính bằng mili giây Unix. Dùng created nếu không có.
by Ngữ cảnh tác nhân, nếu có. by.type là loại tác nhân; by.id xác định tác nhân.
data Dữ liệu của loại sự kiện này.

Các đường dẫn này tính từ mỗi phần tử trong events, ví dụ events[0].id. Đừng nhầm ID sự kiện với ID user, ID hội thoại hay header X-Subiz-Delivery.

Trường có giá trị rỗng có thể bị lược bỏ. by có thể không có hoặc chỉ chứa ngữ cảnh như thông tin thiết bị. Kiểm tra những gì bộ xử lý của bạn cần và chấp nhận các trường bổ sung.

Tin nhắn được gửi

Sự kiện message_sent có thể là tin nhắn của khách hàng, câu trả lời của agent hoặc nội dung tự động. Bản thân nó không xác nhận tin đã tới kênh bên ngoài.

{
  "events": [
    {
      "id": "event_example_1",
      "account_id": "account_example",
      "created": 1794614400000,
      "type": "message_sent",
      "by": {
        "id": "user_example",
        "type": "user"
      },
      "data": {
        "message": {
          "conversation_id": "conversation_example",
          "format": "plaintext",
          "text": "Can you help with my order?"
        }
      }
    }
  ]
}

Dùng data.message.conversation_id để liên kết tin nhắn với hội thoại. Kiểm tra by.type để phân biệt khách hàng (user) với agent (agent), và kiểm tra data.message.is_internal trước khi coi tin nhắn là hiển thị với khách hàng. Đừng tự động trả lời mọi sự kiện message_sent: chính câu trả lời của bạn cũng có thể kích hoạt loại sự kiện này.

Block trong tin nhắn phong phú

Khi format là block, đọc data.message.block như một cây. content chứa các nút con; nút văn bản có thể có định dạng như bold.

{
  "events": [
    {
      "id": "event_example_2",
      "account_id": "account_example",
      "created": 1794614401000,
      "type": "message_sent",
      "by": {
        "id": "agent_example",
        "type": "agent"
      },
      "data": {
        "message": {
          "conversation_id": "conversation_example",
          "format": "block",
          "text": "Hello Alex",
          "block": {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Hello "
              },
              {
                "type": "text",
                "text": "Alex",
                "bold": true
              }
            ]
          }
        }
      }
    }
  ]
}

Nội dung này hiển thị là “Hello Alex”. Giữ cây block khi lưu nội dung phong phú; chỉ dùng text sẽ mất định dạng. Tin nhắn cũng có thể chứa attachments, và tin nhắn không có văn bản chưa chắc đã rỗng. Xem Tin nhắn định dạng phong phú bằng block.

Khách hàng được tạo

user_created chứa khách hàng trong data.user. Dùng (account_id, data.user.id) làm tham chiếu Subiz trong CRM của bạn. Khách hàng là user, không phải agent.

{
  "events": [
    {
      "id": "event_example_3",
      "account_id": "account_example",
      "created": 1794614399000,
      "type": "user_created",
      "data": {
        "user": {
          "id": "user_example",
          "account_id": "account_example",
          "attributes": [
            {
              "key": "fullname",
              "text": "Alex Example"
            },
            {
              "key": "created",
              "datetime": "2026-11-13T23:59:59Z"
            }
          ]
        }
      }
    }
  ]
}

attributes là một mảng, không phải đối tượng có khóa theo tên. Tìm thuộc tính có key là fullname, rồi đọc text. Thuộc tính ngày dùng datetime; thuộc tính khác có thể dùng number hoặc boolean. Đừng dùng vị trí trong mảng để xác định trường.

Thông tin khách hàng được cập nhật

user_info_updated mang thông tin khách hàng trong data.user. Hãy coi đây là bản cập nhật để đồng bộ, không phải danh sách chỉ gồm các trường đã thay đổi.

{
  "events": [
    {
      "id": "event_example_4",
      "account_id": "account_example",
      "created": 1794614402000,
      "type": "user_info_updated",
      "data": {
        "user": {
          "id": "user_example",
          "account_id": "account_example",
          "attributes": [
            {
              "key": "fullname",
              "text": "Alex Example",
              "modified": 1794614402000,
              "by_type": "agent",
              "by": "agent_example"
            },
            {
              "key": "created",
              "datetime": "2026-11-13T23:59:59Z"
            }
          ]
        }
      }
    }
  ]
}

Ở đây, modified ghi thời điểm cập nhật thuộc tính, tính bằng mili giây Unix. by và by_type của nó mô tả ai đã cập nhật thuộc tính đó; chúng tách biệt với đối tượng by tùy chọn ở cấp sự kiện.

Chỉ upsert các trường CRM của bạn dùng. Thuộc tính bị lược bỏ không phải là chỉ thị xóa giá trị trong CRM. Các cập nhật liên tiếp nhanh của cùng một khách hàng có thể được gộp trước khi gửi webhook, nên sự kiện này không phải là nhật ký đầy đủ mọi lần chỉnh sửa. Gọi Lấy thông tin khách hàng khi bạn cần bản ghi mới nhất.

Hội thoại được giao

conversation_assigned mang ID hội thoại và agent phụ trách trong data.conversation. Đây là quyền phụ trách, không phải tư cách thành viên hay lời mời tham gia.

{
  "events": [
    {
      "id": "event_example_5",
      "account_id": "account_example",
      "created": 1794614403000,
      "type": "conversation_assigned",
      "data": {
        "conversation": {
          "id": "conversation_example",
          "assignee": "agent_example"
        }
      }
    }
  ]
}

Bỏ người phụ trách

conversation_unassigned cho biết người phụ trách đã bị bỏ. Trong ví dụ này, assignee rỗng nên bị lược bỏ. Dùng loại sự kiện để nhận biết thay đổi; đừng coi mọi trường hợp thiếu assignee ở các loại sự kiện khác là chỉ thị bỏ người phụ trách.

{
  "events": [
    {
      "id": "event_example_6",
      "account_id": "account_example",
      "created": 1794614404000,
      "type": "conversation_unassigned",
      "data": {
        "conversation": {
          "id": "conversation_example"
        }
      }
    }
  ]
}

Xem Giao agent phụ trách cho thao tác hội thoại tương ứng.

Xử lý một lô an toàn

Với mỗi sự kiện, loại trùng theo (account_id, id), phân luồng theo type và kiểm tra đối tượng data tương ứng. Một lô có thể chứa nhiều khách hàng hoặc hội thoại. Bỏ qua an toàn các loại sự kiện không hỗ trợ và đừng giả định thứ tự gửi khớp với thứ tự tạo.

Lưu mọi công việc được chấp nhận trước khi xác nhận lô. Xem Xác nhận và xử lý cho luồng của máy nhận.