Hướng dẫn October 2, 2026

Đồng bộ tên liên hệ WhatsApp bằng webhook contact.updated

Để cập nhật tên liên hệ WhatsApp trong hộp thư dùng chung, hãy xử lý contact.updated của UnifyPort như bản cập nhật một phần của danh bạ, không phải thao tác thay thế toàn bộ liên hệ. Áp dụng các chuỗi tên được gửi, giữ nguyên trường bị lược bỏ và coi chuỗi rỗng là yêu cầu xóa giá trị. null không hợp lệ. Tách định danh liên hệ khỏi định danh hội thoại; không ghi đè biệt danh do nhân viên đặt hoặc hồ sơ của chính tài khoản nhắn tin đang kết nối.

Điểm chính

Tài liệu xác định sự kiện này cho provider: whatsapp, không phải whatsapp-protocol hay mọi kênh trong hộp thư chung.
Không có trường tên và tên có giá trị rỗng là hai tình huống khác nhau.
Lưu riêng tên danh bạ, biệt danh nội bộ và tên của chính tài khoản.
Xác thực rồi lưu bền vững sự kiện trước khi cập nhật dữ liệu hiển thị.

Tên nào đã thay đổi?

Thông báo chính thức về quản lý liên hệ của WhatsApp mô tả việc quản lý liên hệ từ các thiết bị liên kết. Đây là bối cảnh giải thích vì sao tên có thể đổi bên ngoài ứng dụng hỗ trợ. Thông báo đó không định nghĩa sự kiện UnifyPort và không bảo đảm mọi lần chỉnh sửa đều phát sự kiện.

Tài liệu sự kiện chuẩn của UnifyPort định nghĩa contact.updated là thay đổi tên trong danh bạ WhatsApp. Việc này khác với thêm liên hệ hay gửi thông tin liên hệ cho người khác. Với hai thao tác chủ động đó, xem hướng dẫn thêm liên hệ so với gửi vCard.

Dữ liệu	Ý nghĩa	Ranh giới lưu trữ đề xuất
`data.contact.id`	Định danh tài nguyên liên hệ	Khóa trong phạm vi workspace, provider và tài khoản nhắn tin
`data.contact.conversation_id`	Định danh hội thoại liên quan khi được cung cấp	Lưu ánh xạ rõ ràng, không suy ra từ ID liên hệ
`data.contact.address_book`	Các trường tên được gửi trong lần này	Chỉ hợp nhất trường được hỗ trợ và thực sự có mặt
Biệt danh nội bộ của nhân viên	Nhãn do ứng dụng tự đặt	Lưu riêng, không để sự kiện này ghi đè
`account.profile.updated`	Hồ sơ tên công khai của chính tài khoản kết nối	Chuyển sang bộ xử lý riêng

Đổi tên liên hệ khách hàng không phải đổi tên tài khoản doanh nghiệp, cũng không phải sửa tin nhắn. Nếu nhóm dùng cả WhatsApp và Zalo trong cùng giao diện, vẫn phải giữ các ranh giới này.

Đọc payload như một bản cập nhật từng phần

Ví dụ dưới đây theo cấu trúc trong tài liệu. Tên và định danh chỉ để minh họa, không phải sự kiện của khách hàng thực tế:

{
  "id": "0000000000000000000000000000000000000000000000000000000000000191",
  "type": "contact.updated",
  "provider": "whatsapp",
  "account_id": "acc_example",
  "occurred_at": "2026-09-20T03:00:00Z",
  "data": {
    "contact": {
      "id": "15550000002@s.whatsapp.net",
      "conversation_id": "100000000000002@lid",
      "address_book": {
        "full_name": "Example customer",
        "first_name": "Example"
      }
    },
    "event": {
      "kind": "contact_updated",
      "source": "address_book",
      "changed_fields": ["address_book.full_name", "address_book.first_name"],
      "changed_at": "2026-09-20T03:00:00Z"
    }
  }
}

Dùng giá trị thực sự có trong address_book. Nếu changed_fields nhắc đến một trường nhưng đối tượng không cung cấp giá trị, đừng coi đó là yêu cầu xóa và đừng tự điền "".

Giá trị đầu vào	Cách xử lý
Chuỗi không rỗng	Đặt giá trị cho trường danh bạ đó
`""`	Xóa giá trị trường đó
Bị lược bỏ	Giữ nguyên giá trị trước
`null` hoặc kiểu không phải chuỗi	Không áp dụng bản cập nhật, chuyển sang kiểm tra hợp lệ

JavaScript dưới đây chỉ là hàm hợp nhất hai trường tên được tài liệu mô tả. Nó không phải bộ nhận webhook hoàn chỉnh, bộ phân giải định danh hay cơ chế sắp xếp sự kiện:

function mergeAddressBook(current, patch) {
  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
    throw new Error('Invalid address_book object');
  }
  const fields = ['full_name', 'first_name'];
  for (const field of fields) {
    if (Object.hasOwn(patch, field) && typeof patch[field] !== 'string') {
      throw new Error('Invalid address-book name');
    }
  }
  const next = { ...current };
  for (const field of fields) {
    if (Object.hasOwn(patch, field)) next[field] = patch[field];
  }
  return next;
}

Hàm kiểm tra mọi trường mục tiêu trước khi áp dụng bất kỳ trường nào, tránh bản cập nhật sai làm tên đổi dở dang. Trường chưa biết không được sao chép vào dữ liệu hiển thị. Nếu chính sách lưu trữ cho phép, giữ riêng sự kiện đã xác thực để xem xét thay đổi schema sau này.

Thiết kế bộ nhận theo trạng thái từng trường

Đăng ký có chủ đích. Thêm contact.updated mà không bỏ các sự kiện đang cần. Hướng dẫn bộ lọc sự kiện giải thích danh sách chỉ định và wildcard. Giữ nguyên cấu hình ký hiện có.
Xác thực và lưu. Tuân theo hợp đồng phân phối webhook: dùng signing_secret kiểm tra HMAC-SHA256 của X-Device-Timestamp, dấu chấm và phần thân request nguyên gốc. Kiểm tra độ mới của timestamp. Lưu bền vững sự kiện đã xác thực trước khi trả 2xx. Sự kiện có chữ ký đúng nhưng cấu trúc sai cần được cách ly để kiểm tra, không âm thầm áp dụng.
Xác định đúng thực thể. Phân luồng theo loại sự kiện và provider. Giới hạn data.contact.id theo workspace, provider và account_id. Chỉ lưu conversation_id được cung cấp rõ ràng; không tạo ID hội thoại từ số điện thoại hoặc ID liên hệ. Thiếu ánh xạ không phải lý do hợp nhất các bản ghi không liên quan.
Xử lý trùng và sai thứ tự. Với sự kiện thông thường, khử trùng theo event ID trong workspace. Thứ tự phân phối không được bảo đảm. Đề xuất lưu occurred_at đã áp dụng gần nhất và event ID để phân định khi trùng thời gian cho từng trường tên, không chỉ cho toàn bộ liên hệ. Sự kiện cũ có thể chứa trường mà bản cập nhật mới hơn chưa đụng tới. Đây là quy tắc quản lý nội bộ của ứng dụng, không phải trường API bổ sung hay bảo đảm tái tạo hoàn hảo thứ tự nhân quả từ nguồn.
Xác định nguồn tên hiển thị. Ví dụ, ưu tiên biệt danh nội bộ rồi đến tên đầy đủ trong danh bạ. Sau khi xóa giá trị, tính lại tên hiển thị từ các nguồn còn được phép; không khôi phục giá trị vừa xóa từ cache cũ.

Thực hiện khử trùng, kiểm tra phiên bản từng trường và cập nhật dữ liệu trong cùng transaction hoặc worker tuần tự. Nếu đánh dấu đã xử lý trước khi ghi cơ sở dữ liệu, sự cố giữa chừng có thể làm mất bản cập nhật.

Kiểm thử và giới hạn

Kiểm thử bản cập nhật chỉ có tên đầy đủ, chỉ có tên riêng, xóa bằng chuỗi rỗng, trường bị lược bỏ, null không hợp lệ, phân phối trùng, bản cập nhật từng phần đến sai thứ tự và cùng ID liên hệ trong các tài khoản nhắn tin khác nhau. Đồng thời xác nhận biệt danh nội bộ và hồ sơ tài khoản không đổi. Đây là các ca kiểm thử đề xuất, không phải kết quả chạy production.

UnifyPort là giao diện không chính thức. Sự kiện này không phải ảnh chụp toàn bộ danh bạ, cơ chế phát lại được bảo đảm hay tín hiệu xóa liên hệ. Đừng xóa liên hệ chỉ vì tên bị xóa giá trị. Đăng ký hợp lệ cũng không bảo đảm nhận được mọi thay đổi từ nguồn; hãy hiển thị trung thực trạng thái cũ hoặc chưa xác nhận và kiểm tra hành vi với tài khoản kết nối trước khi phụ thuộc vào tính năng.

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

Thiếu full_name có nghĩa là tên đã bị xóa không?

Không. Giữ giá trị trước đó. Chỉ chuỗi rỗng được gửi rõ ràng mới xóa giá trị trường này.

Có thể dùng contact.id làm đích trả lời không?

Đừng mặc định nó bằng ID hội thoại. Liên hệ và hội thoại là hai tài nguyên khác nhau. Dùng ánh xạ hội thoại theo tài liệu cho thao tác chat.

Sự kiện này có đồng bộ tên LINE hoặc Zalo không?

Tài liệu không xác định hỗ trợ đó cho sự kiện này. Envelope chung không có nghĩa mọi kênh có cùng khả năng.

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

Đọc hợp đồng sự kiện chuẩn, rồi thử quy tắc hợp nhất với một liên hệ WhatsApp dùng để kiểm thử trước khi bật cập nhật hộp thư.

Nguồn được đối chiếu ngày 2026-10-02:

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