Hướng dẫn October 13, 2026

Ghi chú liên hệ WhatsApp: đặt hoặc xóa tên hiển thị riêng

Để đặt tên hiển thị riêng cho một liên hệ WhatsApp qua UnifyPort, dùng POST /v1/accounts/{account_id}/contacts/note với contact_id và chuỗi note. Muốn xóa ghi chú, hãy gửi rõ note: "". Thao tác này thay đổi ghi chú liên hệ phía tài khoản, không phải hồ sơ công khai của khách hàng, tin nhắn trong cuộc trò chuyện hay bí danh CRM chỉ dành cho một nhân viên.

Điểm chính

Tài liệu hiện hỗ trợ thao tác này cho whatsapp, không phải mọi nhà cung cấp hoặc whatsapp-protocol.
note là bắt buộc. Chuỗi rỗng có nghĩa là xóa; biểu mẫu chưa chỉnh sửa thì không nên gửi yêu cầu.
“Chỉ tài khoản nhìn thấy” không đồng nghĩa với phân quyền riêng cho từng nhân viên trong hộp thư chung.
Tách việc ghi chú, đồng bộ tên danh bạ và gửi tin nhắn thành các thao tác riêng.

Xác định loại tên cần thay đổi

Thông báo quản lý danh bạ của WhatsApp mô tả quản lý liên hệ trên các thiết bị đã liên kết. Đây là bối cảnh về dữ liệu phía tài khoản, không phải đặc tả thao tác ghi chú của UnifyPort.

Mục tiêu	Lớp xử lý phù hợp
Đặt tên riêng cho liên hệ trên tài khoản đã kết nối	Ghi chú liên hệ UnifyPort
Bí danh chỉ một nhân viên được thấy	Kho lưu trữ và phân quyền của ứng dụng
Nhận thay đổi tên danh bạ từ nhà cung cấp	Mô hình dữ liệu đồng bộ tên riêng
Chia sẻ thông tin liên hệ trong cuộc trò chuyện	Tin nhắn thẻ liên hệ

Với thay đổi tên danh bạ nhận được, xem hướng dẫn đồng bộ contact.updated. Sự kiện này không ghi đè biệt danh và không được tài liệu cam kết là tín hiệu xác nhận lưu ghi chú. Nếu cần lưu hoặc chia sẻ liên hệ, đọc thêm liên hệ và gửi vCard khác nhau thế nào.

Giao diện nên tách “Tên cho tài khoản” và “Bí danh của tôi”. Đừng gọi cả hai là tên riêng rồi âm thầm lưu vào hai nơi khác nhau.

Đặt và xóa ghi chú liên hệ WhatsApp

Tài liệu Set contact note quy định phương thức, yêu cầu và phản hồi thành công. Kiểm tra ma trận hỗ trợ thao tác trước khi bật nút lưu cho một kênh. Hộp thư có cả Zalo và WhatsApp không có nghĩa là thao tác ghi chú này dùng được cho cả hai.

Chuẩn bị API key của workspace ở phía máy chủ và chọn tài khoản nhắn tin. Xác định đúng liên hệ trong cùng tài khoản theo tài liệu truy vấn liên hệ. Giữ nguyên định danh dưới dạng chuỗi opaque; không tạo từ tên hiển thị hoặc giả định mọi thao tác đều chấp nhận cùng một định dạng.

Trường	Ý nghĩa
`contact_id`	Liên hệ đích của thao tác
`note`	Tên hiển thị tùy chỉnh; `""` xóa ghi chú hiện có

Hàm JavaScript sau minh họa lệnh gọi theo tài liệu. Truyền định danh tài khoản và liên hệ thực tế do backend chọn, đồng thời lấy khóa từ cấu hình được bảo vệ. Hàm không tự thử lại và không phải một ứng dụng hộp thư hoàn chỉnh.

async function setContactNote({ apiKey, accountId, contactId, note }) {
  if (typeof note !== 'string') throw new TypeError('note must be a string');
  if (!accountId || !contactId) throw new Error('Select account and contact');

  const response = await fetch(
    `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/contacts/note`,
    {
      method: 'POST',
      headers: {
        'X-Api-Key': apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ contact_id: contactId, note })
    }
  );
  const result = await response.json();
  return { httpStatus: response.status, result };
}

Để lưu, truyền chuỗi đã được người dùng xác nhận. Để xóa, gọi cùng hàm với chuỗi rỗng. Không chuyển giá trị biểu mẫu bị thiếu thành chuỗi rỗng: như vậy “không sửa” sẽ trở thành xóa dữ liệu. Từ chối null ngay trong ứng dụng thay vì tự đặt thêm quy ước xóa.

Thành công được tài liệu mô tả là 200 OK với data.ok: true. Hãy kiểm tra kết quả trước khi báo đã lưu; fetch hoàn tất không tự động có nghĩa là thành công.

Tránh để yêu cầu cũ ghi đè chỉnh sửa mới

Các bước sau là khuyến nghị thiết kế ứng dụng, không phải trường API bổ sung hay bảo đảm kiểm soát đồng thời từ máy chủ:

Giới hạn trình chỉnh sửa và tác vụ theo workspace, tài khoản nhắn tin và liên hệ. Tên trùng nhau không phải khóa định danh.
Phân biệt chưa thay đổi, đã chỉnh sửa và chủ động xóa. Yêu cầu xác nhận xóa khi phù hợp.
Tuần tự hóa các lần ghi cho cùng một mục tiêu trong ứng dụng. Chặn nhấp đúp và loại tác vụ cũ trước khi gửi.
Lưu giá trị yêu cầu, kết quả và request_id theo chính sách lưu giữ phù hợp. Không ghi API key vào log.
Khi hết thời gian chờ, hiển thị kết quả chưa rõ. Không lập tức báo thất bại hoặc tự gửi lại giá trị cũ, vì một người khác có thể đã lưu ghi chú mới.

Tuần tự hóa cục bộ không thể điều phối mọi máy khách đã liên kết. Tài liệu công khai không định nghĩa điều kiện phiên bản, trường đọc lại ghi chú chuyên biệt hay webhook thay đổi ghi chú được bảo đảm gửi tới. Không xây vòng xác nhận dựa trên trường tự nghĩ ra. Kiểm tra hành vi phía tài khoản trong thử nghiệm có kiểm soát; giữ trạng thái chưa rõ khi không thể quan sát kết quả.

Tài liệu lỗi dùng set_contact_note_failed cho lỗi ghi chú phía máy chủ hoặc hệ thống nguồn, và unsupported_by_provider cho thao tác không được hỗ trợ. Thiếu hỗ trợ không phải lý do để thử lại vô hạn.

Kiểm tra nghiệm thu và câu hỏi thường gặp

Nên kiểm tra đặt mới, thay thế, chủ động xóa, biểu mẫu không chỉnh sửa, dữ liệu không phải chuỗi, hai chỉnh sửa cạnh tranh, nhà cung cấp không hỗ trợ và hết thời gian chờ. Đây là danh sách đề xuất, không phải kết quả vận hành thực tế.

Đây có phải ghi chú riêng của phiếu hỗ trợ không?

Không. Tài liệu mô tả ghi chú liên hệ là tên hiển thị tùy chỉnh. Lịch sử xử lý dài và bình luận nhạy cảm của nhân viên nên nằm trong CRM có phân quyền, không phải trường tên.

Xóa ghi chú có xóa liên hệ không?

Không. Thao tác được tài liệu mô tả chỉ xóa ghi chú, không xóa liên hệ hoặc tin nhắn.

Dùng cho LINE, Zalo hoặc WhatsApp Protocol được không?

Ma trận hiện tại chỉ liệt kê thao tác ghi này cho whatsapp. Giao diện không chính thức của UnifyPort có hình thức API thống nhất, nhưng khả năng của từng kênh không giống nhau.

Có thể dùng contact.updated để xác nhận lưu không?

Không. Sự kiện này mô tả thay đổi tên danh bạ, không phải biên nhận được bảo đảm cho việc lưu ghi chú tùy chỉnh.

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

Đọc Set contact note rồi kiểm tra một liên hệ có kiểm soát trước khi bật chỉnh sửa phía tài khoản trong hộp thư chung.

Đối chiếu ngày 2026-10-13:

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