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

API 4.0 · 4.1

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](#mối-quan-hệ-giữa-các-đối-tượng) để hiểu các đối tượng và ID bạn sẽ dùng.
2. Làm theo [Xác thực](/developers/vi/get-started/authentication) để tạo access token cho tài khoản của bạn.
3. [Kiểm tra token bằng `/4.1/me`](/developers/vi/get-started/authentication#kiểm-tra-access-token), 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](/developers/vi/api-reference/users/create) hoặc [cập nhật thông tin khách hàng](/developers/vi/api-reference/users/update). |
| Trả lời trong một hội thoại có sẵn | [Gửi tin nhắn vào hội thoại](/developers/vi/api-reference/messages/send), 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](/developers/vi/api-reference/messages/send-to-user), dùng ID khách hàng và đích đến trên kênh. |
| Điều phối agent | [Mời agent](/developers/vi/api-reference/conversations/invite-agent) tham gia, hoặc [giao agent](/developers/vi/api-reference/conversations/assign-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](/developers/vi/webhooks/receiving) và đọc [ví dụ dữ liệu sự kiện](/developers/vi/webhooks/payloads). |

Với nội dung phong phú, xem [Định dạng tin nhắn](/developers/vi/messages/formats) cho văn bản, block và liên kết, và [Tệp đính kèm](/developers/vi/messages/attachments) 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.

```json
{
  "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](/developers/vi/get-started/authentication).

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

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

```json
{
  "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](/developers/vi/api-reference/users/identity) để 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:

```json
{
  "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 đó:

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

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

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

[Mời agent](/developers/vi/api-reference/conversations/invite-agent) thêm một agent có sẵn làm người tham gia. [Giao agent](/developers/vi/api-reference/conversations/assign-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:

```json
{
  "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](/developers/vi/api-reference/messages/send) đặ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](/developers/vi/api-reference/messages/send-to-user) 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`:

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

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

```json
{
  "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](/developers/vi/api-reference/conversations/history) 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](/developers/vi/messages/formats).

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

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

```json
{
  "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](/developers/vi/messages/attachments) để 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:

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

```json
{
  "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](/developers/vi/webhooks/receiving) để thiết lập và [Ví dụ dữ liệu sự kiện](/developers/vi/webhooks/payloads) 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](/developers/vi/changelog) để 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

- Đọc [Giới hạn sử dụng](/developers/vi/get-started/usage-limits) để biết hạn mức theo token, tài khoản và tin nhắn của agent. Xếp hàng yêu cầu và tuân theo `Retry-After` khi bị giới hạn.
- Làm theo [Xử lý lỗi](/developers/vi/get-started/errors) để xử lý thất bại. Sau khi gửi tin nhắn bị hết thời gian chờ, kiểm tra kết quả trước khi thử lại để tránh trùng lặp.
- Khi nhận webhook, [xác minh chữ ký và xử lý sự kiện trùng lặp](/developers/vi/webhooks/receiving).

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

Đọc [trang này dưới dạng Markdown](/developers/vi/index.md). Với công cụ AI, dùng [mục lục tài liệu](/developers/llms.txt) hoặc [toàn bộ tài liệu](/developers/llms-full.txt).