SubizTài liệu API
Khách hàng

API 4.0 · 4.1

Định dạng khách hàng và thuộc tính

Hiểu đối tượng khách hàng và cách lưu giá trị thuộc tính.

Trong API, khách hàng là một User. Phần lớn dữ liệu khách hàng, như tên, email và số điện thoại, được lưu trong mảng attributes. Trang này mô tả cả hai đối tượng. Mọi ID và giá trị bên dưới chỉ mang tính minh họa.

User

Ví dụ dưới đây là một số trường của đối tượng User, như được trả về bởi Lấy thông tin khách hàng:

{
  "id": "user_example",
  "account_id": "account_example",
  "channel": "facebook",
  "channel_source": "page_example",
  "profile_id": "profile_example",
  "attributes": [
    {
      "key": "fullname",
      "text": "Alex Example"
    },
    {
      "key": "emails",
      "text": "alex@example.com"
    }
  ],
  "created": 1763107200000,
  "updated": 1763193600000
}
Trường Kiểu Mô tả
id string ID user Subiz. Dùng trong các endpoint khách hàng và tin nhắn.
account_id string Tài khoản mà khách hàng thuộc về.
attributes array Dữ liệu khách hàng. Xem Thuộc tính.
channel string Kênh khách hàng đến từ, như facebook hoặc zalo.
channel_source string Trang hoặc tài khoản đã kết nối trên kênh đó.
profile_id string ID của khách hàng trên kênh đó.
labels array Nhãn đã gắn cho khách hàng trong Subiz.
created, updated integer Dấu thời gian Unix tính bằng mili giây.

channel, channel_source và profile_id cùng tạo thành định danh kênh của khách hàng. Không nhầm chúng với id của Subiz. Xem Tìm hoặc tạo theo định danh kênh.

Đối tượng có nhiều trường hơn ví dụ. Bỏ qua các trường tích hợp của bạn không dùng.

Thuộc tính

Mỗi phần tử trong attributes lưu một mẩu dữ liệu khách hàng:

{
  "key": "fullname",
  "text": "Alex Example",
  "modified": 1763193600000
}
Trường Kiểu Mô tả
key string Khóa thuộc tính, như fullname. Xác định thuộc tính.
type string Chỉ đọc. text, number, boolean hoặc datetime.
text string Giá trị của thuộc tính text.
number number Giá trị của thuộc tính number.
boolean boolean Giá trị của thuộc tính boolean.
datetime string Giá trị của thuộc tính datetime, theo định dạng RFC 3339.
other_values array of strings Các giá trị bổ sung của thuộc tính văn bản, như thêm địa chỉ email.
modified integer Thời điểm giá trị thay đổi gần nhất, tính bằng mili giây Unix.

Mỗi thuộc tính dùng đúng một trường giá trị, chọn theo kiểu của nó. Trong yêu cầu, chỉ gửi key và trường giá trị tương ứng.

Kiểu giá trị

Dùng trường giá trị khớp với kiểu của thuộc tính.

Text — tên, email, số điện thoại và các chuỗi khác:

{
  "key": "job_title",
  "text": "Purchasing manager"
}

Number — số thập phân, không phải chuỗi:

{
  "key": "loyalty_points",
  "number": 1250
}

Boolean — true hoặc false:

{
  "key": "newsletter_opt_in",
  "boolean": true
}

Datetime — chuỗi ngày giờ RFC 3339, có múi giờ:

{
  "key": "birthdate",
  "datetime": "1990-05-20T00:00:00Z"
}

loyalty_points và newsletter_opt_in là ví dụ thuộc tính tùy chỉnh. Chúng chỉ tồn tại nếu tài khoản của bạn định nghĩa.

Nhiều giá trị

Một số thuộc tính văn bản, như emails và phones, có thể chứa nhiều giá trị. Giá trị chính nằm trong text; các giá trị khác nằm trong other_values:

{
  "key": "emails",
  "text": "alex@example.com",
  "other_values": [
    "alex.work@example.com"
  ]
}

Khi chỉ cần một email hoặc số điện thoại, dùng text. Để tìm khách hàng theo bất kỳ địa chỉ nào của họ, kiểm tra cả hai trường.

Thuộc tính có sẵn

Mọi tài khoản đều có các thuộc tính sau:

Khóa Kiểu Mô tả
fullname text Họ và tên.
display_name text Tên hiển thị.
emails text Địa chỉ email.
phones text Số điện thoại.
address, city, district text Địa chỉ.
gender text Giới tính.
job_title text Chức danh.
birthdate datetime Ngày sinh.
avatar_url text URL ảnh đại diện.
timezone text Múi giờ của khách hàng.

Subiz tự quản lý một số thuộc tính có sẵn và chúng là chỉ đọc, ví dụ created, modified, seen, total_conversations và last_message_sent. Bạn đọc được nhưng không thay đổi được chúng.

Thuộc tính tùy chỉnh

Tài khoản của bạn có thể định nghĩa thêm thuộc tính riêng ngoài các thuộc tính có sẵn. Dùng đúng khóa trong tài khoản và gửi giá trị theo kiểu của thuộc tính.

Đọc thuộc tính an toàn

  • Tìm thuộc tính theo key. Thứ tự của mảng không cố định.
  • Xử lý thuộc tính bị thiếu. Thuộc tính có thể không có khi khách hàng chưa có giá trị.
  • Lường trước giá trị mặc định bị lược bỏ. Chuỗi rỗng, 0 và false bị lược khỏi JSON. Thuộc tính boolean không có trường boolean nghĩa là false.
  • Đọc theo kiểu. Đừng giả định mọi giá trị đều nằm trong text.

Ghi thuộc tính

Tạo khách hàng và Cập nhật thông tin khách hàng nhận mảng attributes theo định dạng này:

{
  "attributes": [
    {
      "key": "fullname",
      "text": "Alex Example"
    },
    {
      "key": "birthdate",
      "datetime": "1990-05-20T00:00:00Z"
    }
  ]
}

Chỉ gửi key và giá trị. Các trường chỉ đọc như type và modified do Subiz đặt. Có giới hạn kích thước; xem Giới hạn thuộc tính khách hàng.