Hướng dẫn November 5, 2026

Đồng bộ tên tài khoản WhatsApp bằng account.profile.updated

Để đồng bộ tên của chính tài khoản WhatsApp đã kết nối, hãy xử lý sự kiện UnifyPort account.profile.updated. Đọc data.profile.display_name: tên này ưu tiên tên doanh nghiệp, sau đó mới dùng tên push. Chỉ cập nhật phần hiển thị hồ sơ tài khoản, không sửa liên hệ khách hàng, nhãn nội bộ hay trạng thái kết nối. Nguồn kích hoạt được tài liệu mô tả là sự kiện tên WhatsApp, không phải luồng thay đổi hồ sơ chung cho mọi kênh.

Điểm chính

Xác định tài khoản bằng workspace, provider và account_id, không dùng tên hiển thị làm khóa.
Tách name trong cấu hình tài khoản khỏi tên công khai trên nền tảng.
full_sync cho biết nguồn của hồ sơ, không chứng minh đã khôi phục xong lịch sử tin nhắn.
Thông báo hồ sơ không xác nhận tài khoản đã được xác thực hoặc đang kết nối.

Xác định tên nào cần xuất hiện trên giao diện

Bộ chọn tài khoản hỗ trợ có thể hiển thị cả nhãn vận hành của nhóm và tên công khai trên kênh. Đổi tên không nên âm thầm đổi người phụ trách, quy tắc định tuyến hay quyền truy cập.

Giá trị hoặc sự kiện	Ý nghĩa	Vị trí hiển thị đề xuất
`name` trong cấu hình tài khoản	Nhãn quản lý qua cấu hình	Nhãn tài khoản nội bộ
`data.profile.display_name`	Tên công khai lấy từ hồ sơ nền tảng	Dòng tên kênh riêng
`data.profile.business_name` / `push_name`	Các thành phần tên trong tài liệu sự kiện	Chi tiết hồ sơ tùy chọn
`contact.updated`	Tên liên hệ trong danh bạ	Dữ liệu liên hệ khách hàng
`account.status.updated`	Trạng thái xác thực hoặc runtime	Khu vực trạng thái kết nối

Hướng dẫn đồng bộ tên liên hệ giải quyết phía khách hàng, không phải tài khoản của bạn. Dùng chung bộ xử lý có thể cập nhật nhầm đối tượng. Tên người gửi trong tin nhắn khách hàng cũng không chứng minh tài khoản của bạn vừa đổi tên.

Tài liệu Get account trả cấu hình và provider_profile riêng biệt, phù hợp để nạp màn hình ban đầu. Nếu thiếu tên công khai, hãy hiển thị chưa có dữ liệu; đừng coi nhãn nội bộ là tên đã quan sát được từ nền tảng.

Hiểu đúng phạm vi account.profile.updated

Ví dụ dưới đây theo tài liệu sự kiện. Các giá trị là mẫu trong tài liệu, không phải bản ghi của khách hàng:

{
  "id": "evt_profile_7e91d2c4",
  "type": "account.profile.updated",
  "provider": "whatsapp",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-08-28T09:51:51Z",
  "data": {
    "account": { "provider_account_ref": "provider_account_example" },
    "profile": {
      "display_name": "Example Business",
      "business_name": "Example Business",
      "push_name": "Example Account"
    },
    "event": {
      "kind": "account_profile_updated",
      "source": "self_rename"
    }
  }
}

Dùng display_name đã được cung cấp thay vì tự đặt quy tắc ưu tiên khác. Khi tên doanh nghiệp đang được ưu tiên, push_name thay đổi có thể không làm tên trên màn hình thay đổi.

Hai giá trị được mô tả cho data.event.source là:

self_rename: tài khoản đã kết nối thay đổi tên của chính mình.
full_sync: hồ sơ đến từ ảnh chụp dữ liệu của lần đồng bộ đầy đủ.

Không giá trị nào xác định người thực hiện thao tác. Đừng tạo nhật ký kiểm toán gán cho một nhân viên khi chưa có bằng chứng. full_sync cũng không xác nhận mọi tin nhắn, liên hệ, ảnh đại diện và dữ liệu khác đều đã đồng bộ.

Tạo phần hiển thị hồ sơ độc lập

Quy trình triển khai đề xuất:

Đăng ký trước khi phụ thuộc vào cập nhật. Thêm account.profile.updated vào tập sự kiện cần dùng, giữ nguyên các đăng ký khác và cấu hình chữ ký. Hướng dẫn lọc sự kiện giải thích danh sách tường minh và wildcard.
Xác minh rồi lưu bền vững. Theo hợp đồng phân phối, dùng signing_secret kiểm tra HMAC-SHA256 dạng hex của X-Device-Timestamp, dấu chấm và body nguyên gốc, đồng thời kiểm tra độ mới của timestamp. Lưu sự kiện đã xác thực trước khi trả 2xx.
Tìm tài khoản hiện có. Dùng ngữ cảnh workspace của bộ nhận cùng provider và account_id trong phong bì. Tên mới không được tạo tài khoản thứ hai hay chuyển hội thoại sang tài khoản khác.
Chỉ cập nhật phần hồ sơ. Không đổi nhãn nội bộ, tên khách hàng, xác thực hoặc runtime. Hiển thị tên dưới dạng văn bản, không phải HTML.
Lưu nguồn tại ứng dụng. Gắn ID sự kiện, thời điểm phát sinh và source với dữ liệu hiển thị. Đây là thiết kế lưu trữ nội bộ, không phải trường API bổ sung.

Hàm JavaScript sau chỉ lấy tên từ sự kiện đã xác thực. Nó không triển khai lưu trữ, sắp xếp hoặc máy chủ nhận hoàn chỉnh:

function profileNameCandidate(event) {
  if (event.type !== 'account.profile.updated' ||
      event.provider !== 'whatsapp') return null;
  if (typeof event.account_id !== 'string' || !event.account_id) {
    throw new Error('Missing account identity');
  }
  const name = event.data?.profile?.display_name;
  if (typeof name !== 'string') {
    throw new Error('Profile display name needs review');
  }
  return { accountId: event.account_id, displayName: name };
}

Các khóa trả về là biến của ứng dụng. Nếu thiếu tên hoặc sai kiểu dữ liệu, giữ sự kiện để kiểm tra thay vì thay toàn bộ hồ sơ bằng giá trị mặc định. Với chuỗi rỗng, hãy đặt chính sách hiển thị “chưa có tên” rõ ràng tại ứng dụng; không áp dụng quy tắc xóa trường của sự kiện liên hệ sang hợp đồng này.

Điều phối sự kiện cũ và lần đọc ban đầu

Khử trùng lặp các lần gửi lại sự kiện thông thường bằng ID sự kiện. Thứ tự phân phối không được bảo đảm: áp dụng sự kiện hồ sơ theo occurred_at, dùng ID làm tiêu chí xác định thứ tự khi thời gian bằng nhau. Ghi nhận đã xử lý và cập nhật dữ liệu hiển thị trong cùng một lần commit.

Tài liệu không nêu phiên bản hồ sơ chung cho REST và Webhook ở đây. Kết quả đọc ban đầu trả về chậm không được ghi đè sự kiện đã áp dụng trong lúc chờ. Có thể tuần tự hóa khởi tạo và xử lý sự kiện, hoặc dùng kết quả đọc làm nền rồi áp dụng các sự kiện đã đệm. Khi quan sát mâu thuẫn, đánh dấu cần đối chiếu thay vì khẳng định đã tái dựng chính xác thứ tự nhân quả trên nền tảng.

UnifyPort là giao diện không chính thức. Sự kiện này không phải lệnh thay đổi hồ sơ gốc, kho lưu trữ đầy đủ hay bảo đảm phát lại dữ liệu bỏ lỡ. Khi dùng WhatsApp cùng Zalo, không suy ra Zalo hỗ trợ cùng sự kiện; giới hạn đó cũng áp dụng cho LINE, Telegram và whatsapp-protocol.

Câu hỏi thường gặp

Vì sao push_name đổi nhưng display_name không đổi?

Theo tài liệu, BusinessName được ưu tiên trước PushName. Kiểm tra các thành phần tên trước khi kết luận đồng bộ thất bại.

full_sync có nghĩa lịch sử tin nhắn đã đầy đủ không?

Không. Nó chỉ cho biết nguồn của sự kiện hồ sơ này, không xác nhận tính đầy đủ hoặc kết quả khôi phục lịch sử.

Có cần PATCH name của tài khoản sau khi nhận sự kiện không?

Không nên tự động làm vậy. Đó là sửa cấu hình tài khoản, không chỉ hiển thị tên công khai đã quan sát. Việc sửa nhãn nội bộ cần là thao tác riêng, có chủ đích.

Bước tiếp theo và nguồn

Xây dựng thẻ tài khoản theo tài liệu sự kiện hồ sơ. Nên kiểm tra cả hai source, tên doanh nghiệp khác tên push, sự kiện lặp và cũ, tên thiếu hoặc rỗng, cùng kết quả đọc ban đầu trả chậm. Xác nhận danh bạ khách hàng, nhãn nội bộ và trạng thái kết nối không đổi. Đây là các kiểm tra được đề xuất, không phải kết quả đã chạy.

Nguồn được kiểm tra ngày 2026-11-05:

UnifyPort API

Biến tích hợp nhắn tin thành một pipeline sản phẩm ổn định.

Bắt đầu bằng cách gửi qua một API, rồi đưa mọi tin nhắn inbound trở lại hệ thống kinh doanh bằng sự kiện chuẩn.

Lấy API Key Xem tham chiếu API