Nhật ký thay đổi June 28, 2026

Cập nhật UnifyPort API: Nhãn hội thoại, tin nhắn liên hệ và theo dõi request — UnifyPort

Ba tuần sau bản phát hành ổn định v1, UnifyPort API nhận đợt tính năng đầu tiên: nhãn hội thoại để tổ chức các cuộc chat WhatsApp, loại tin nhắn danh thiếp liên hệ, theo dõi request xuyên suốt mọi lệnh gọi, và một loạt cải thiện trải nghiệm nhà phát triển giúp tài liệu tham chiếu webhook event hữu ích hơn đáng kể.

Dưới đây là nội dung cập nhật đầy đủ, với tên endpoint và trường thực tế.

Nhãn hội thoại — 4 endpoint mới

Giờ bạn có thể tạo, liệt kê, cập nhật và xóa nhãn trên hội thoại, đồng thời gắn hoặc gỡ nhãn hàng loạt. Đây là cùng hệ thống nhãn mà WhatsApp cung cấp native — UnifyPort đưa ra qua bốn endpoint thuộc danh mục Conversations.

Liệt kê nhãn

GET /v1/accounts/{account_id}/conversations/labels?limit=50&cursor=

Trả về danh sách nhãn có phân trang, mỗi nhãn gồm id và name:

{
  "data": {
    "items": [
      { "id": "label_example", "name": "VIP" }
    ],
    "next_cursor": "",
    "has_more": false
  }
}

Tạo hoặc cập nhật nhãn

POST /v1/accounts/{account_id}/conversations/labels/upsert

label_id rỗng thì tạo mới; truyền label_id có sẵn thì đổi tên:

{
  "label_id": "",
  "name": "VIP"
}

Xóa nhãn

POST /v1/accounts/{account_id}/conversations/labels/delete

{
  "label_id": "label_example"
}

Gắn hoặc gỡ nhãn trên hội thoại

POST /v1/accounts/{account_id}/conversations/labels

action là add hoặc remove; conversation_ids phải chứa ít nhất một ID:

{
  "label_id": "label_example",
  "action": "add",
  "conversation_ids": ["peer_example"]
}

Cả bốn endpoint hiện chỉ hỗ trợ WhatsApp. Các provider khác trả về 501 unsupported_by_provider. Các mã lỗi tương ứng — list_conversation_labels_failed, upsert_label_failed, delete_label_failed, set_label_members_failed — đã được ghi nhận trong tài liệu lỗi.

Loại tin nhắn liên hệ (vCard)

POST /v1/messages giờ chấp nhận message.type: "contact" với mảng contacts có cấu trúc. UnifyPort tự động tạo vCard — bạn gửi JSON có cấu trúc, người nhận nhận được thẻ liên hệ chuẩn.

{
  "account_id": "acc_example",
  "to": {
    "id": "user_example",
    "type": "user"
  },
  "message": {
    "type": "contact",
    "contacts": [
      {
        "name": "Jane Doe",
        "phones": [{ "number": "+8613800000000", "type": "CELL" }],
        "emails": [{ "address": "jane@example.com" }],
        "organization": "ACME",
        "title": "PM"
      }
    ]
  }
}

Mỗi thẻ bắt buộc có name. Các trường phones[].number, emails[].address, organization và title là tùy chọn. Có thể gửi một hoặc nhiều thẻ — WhatsApp ánh xạ thẻ đơn sang loại contact, nhiều thẻ sang contact_array.

Mảng contacts rỗng hoặc thẻ thiếu name trả về 400 invalid_request. Các provider ngoài WhatsApp trả về 400 unsupported_message_type cho đến khi hỗ trợ được triển khai.

Theo dõi request — request_id và X-Request-Id

Mọi phản hồi API — thành công hay lỗi — giờ đều mang trường request_id cấp cao nhất và trả cùng giá trị qua header phản hồi X-Request-Id. Trích dẫn ID này khi báo lỗi hoặc debug các lệnh gọi thất bại.

Để đối chiếu phía client, gửi header request X-Request-Id tùy chỉnh và nó sẽ được echo lại dưới dạng client_request_id trong phản hồi. Điều này cho phép bạn liên kết các lệnh gọi API gửi đi với ID request nội bộ mà không cần duy trì lớp ánh xạ riêng.

Mẫu payload webhook thực tế

Tài liệu API giờ bao gồm các cấu trúc payload thực từ bộ phân tích webhook thiết bị (Telegram và WhatsApp).

message.received hiển thị payload theo loại nội dung — văn bản, hình ảnh, giọng nói, tài liệu và vị trí — để bạn thấy cấu trúc trường chính xác cho mỗi biến thể thay vì đoán từ placeholder data: {} rỗng.

group.updated hiển thị payload theo loại thay đổi:

Đổi tên — changes[].kind: "renamed" với name nhóm mới
Thêm/xóa thành viên — changes[].kind: "member_added" hoặc "member_removed" với mảng members[] chứa ID thành viên
Thăng/giáng quản trị viên — changes[].kind: "promoted" hoặc "demoted" với members[]

Một sự kiện group.updated có thể chứa nhiều thay đổi cùng lúc — ví dụ, đổi tên cộng thêm thành viên trong cùng một snapshot.

Ba công cụ mới cho nhà phát triển

Trang công cụ bổ sung ba tiện ích chạy trên trình duyệt, tất cả hoạt động phía client:

Trình tạo chữ ký HMAC — tạo và xác minh chữ ký HMAC-SHA1/SHA256/SHA512 trên trình duyệt; hữu ích khi debug xác minh webhook signing_secret
Trình chuyển đổi Unix Timestamp — chuyển đổi qua lại giữa Unix timestamp và ngày giờ đọc được, tự động phát hiện giây và mili giây
Trình định dạng JSON — định dạng, nén và xác thực JSON với highlight cú pháp và sao chép JSON Path một lần nhấp

Thay đổi phá vỡ: loại bỏ hai trường

Hai trường chưa triển khai đã bị xóa khỏi tài liệu POST /v1/messages để khớp với bề mặt API thực tế:

idempotency_key — đã xóa. Trường này có trong tài liệu nhưng chưa bao giờ được triển khai trong API thiết bị.
provider_data.reply_to — đã xóa khỏi bề mặt tài liệu. Object provider_data giờ ghi nhận parse_mode làm trường ví dụ.

Nếu code của bạn đang gửi idempotency_key hoặc provider_data.reply_to, hãy kiểm tra xem bạn có đang dựa vào hành vi thực chất là no-op không. Cả hai trường đều không được API xử lý.

Nhãn hội thoại và tin nhắn liên hệ ra mắt ưu tiên WhatsApp vì API upstream của WhatsApp hỗ trợ native các tính năng này. Khi các provider khác bổ sung khả năng tương đương — hoặc khi lớp chuẩn hóa có thể bù đắp — chúng sẽ hoạt động trên các kênh bổ sung với cùng bề mặt endpoint. Phản hồi 501 unsupported_by_provider là có chủ đích: nó cho bạn biết chính xác provider nào chưa hỗ trợ tính năng, thay vì âm thầm bỏ qua request.

Tài liệu API đầy đủ có tại unifyport.ai/docs.