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

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

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](/developers/vi/webhooks/receiving#tạo-webhook-trong-subiz). 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.

```json
{
  "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`.

```json
{
  "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](/developers/vi#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.

```json
{
  "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.

```json
{
  "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](/developers/vi/api-reference/users/retrieve) 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.

```json
{
  "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.

```json
{
  "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](/developers/vi/api-reference/conversations/assign-agent) 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ý](/developers/vi/webhooks/receiving#xác-nhận-và-xử-lý) cho luồng của máy nhận.