Hướng dẫn October 31, 2026

Kiểm tra liên hệ WhatsApp đã được lưu hay chưa qua API

Để kiểm tra một người có được lưu trong danh bạ của tài khoản WhatsApp đang kết nối hay không, hãy gọi GET /v1/accounts/{account_id}/contacts/membership của UnifyPort và truyền LID do API liên hệ trả về vào contact_id. Giá trị data.is_in_contacts: false trong phản hồi thành công có nghĩa là chưa lưu, không phải yêu cầu thất bại. Phép kiểm tra này chỉ xem danh bạ của tài khoản đang kết nối, không cho biết người kia đã lưu số của bạn hay chưa.

Điểm chính

Dùng LID được API liên hệ trả về trong conversation_id; không tự tạo từ số điện thoại.
Tách ba kết quả trong ứng dụng: đã lưu, chưa lưu và chưa xác định.
Có trong danh bạ, có lịch sử trò chuyện, bị chặn và được phép gửi tiếp thị là những thông tin khác nhau.
Đây là thao tác chỉ đọc. Thêm liên hệ phải là một hành động riêng, có chủ đích.

Kết quả đã lưu chứng minh điều gì?

Hướng dẫn liên hệ chính thức của WhatsApp nêu rằng xóa liên hệ không xóa lịch sử trò chuyện. Vì vậy, một cuộc trò chuyện còn hiển thị không chứng minh người đó vẫn được lưu trong danh bạ. Hướng dẫn cũng cho biết người nhận thông tin liên hệ có thể thêm vào danh bạ hoặc nhắn tin trực tiếp: chia sẻ thông tin và lưu liên hệ là hai thao tác khác nhau.

Tài liệu kiểm tra liên hệ của UnifyPort trả lời một câu hỏi hẹp hơn: liên hệ này có thuộc danh bạ của chính tài khoản đang kết nối hay không?

Câu hỏi	Căn cứ phù hợp
Tài khoản đang kết nối đã lưu người này chưa?	Phản hồi thành công và `is_in_contacts`
Người kia đã lưu số của chúng ta chưa?	Endpoint này không trả lời được
Người này có bị chặn không?	Quy trình kiểm tra danh sách chặn riêng
Có cuộc trò chuyện hoặc từng chia sẻ thẻ liên hệ không?	Dữ liệu hội thoại hoặc tin nhắn riêng
Ứng dụng có được chủ động liên hệ người này không?	Sự cho phép và chính sách giao tiếp được xác lập riêng

Đọc Thêm liên hệ và gửi vCard khác nhau thế nào để phân biệt ghi vào danh bạ với chia sẻ thông tin. Đừng gọi API thêm liên hệ chỉ để việc kiểm tra dễ hơn: bạn sẽ thay đổi trạng thái mà mình muốn kiểm tra.

Chuẩn bị tài khoản và LID thực sự được trả về

UnifyPort cung cấp giao diện không chính thức cho tài khoản nhắn tin đã kết nối; đây không phải endpoint của WhatsApp Cloud API. Ma trận hỗ trợ thao tác theo nền tảng hiện ánh xạ phép kiểm tra này tới whatsapp, không phải LINE, Telegram, Zalo hay nền tảng riêng whatsapp-protocol. Nếu đội hỗ trợ dùng chung giao diện cho WhatsApp và Zalo, hãy hiển thị chức năng theo đúng khả năng của từng nền tảng.

Luôn giữ tài khoản đã chọn cùng với liên hệ. Các trường id, provider_user_id và conversation_id trong đối tượng liên hệ có thể khác nhau. Thao tác này yêu cầu LID mà API liên hệ trả về trong conversation_id. Hãy giữ giá trị đó từ quy trình liên hệ hợp lệ có sẵn; không nối @lid vào số điện thoại rồi coi đó là định danh đúng.

Nếu ứng dụng chỉ có số điện thoại, chưa có LID được trả về và xác minh, hãy để chức năng kiểm tra ở trạng thái chưa khả dụng cho đến khi giải quyết được ánh xạ danh tính. Endpoint này không được mô tả là công cụ tra cứu số điện thoại bất kỳ.

Yêu cầu dưới đây chỉ là ví dụ, chưa được chạy trong bài viết. Điền biến môi trường từ tài khoản đã chọn và ánh xạ liên hệ lưu trên backend; không đưa API key xuống trình duyệt:

curl --get \
  "https://api.unifyport.ai/v1/accounts/${UNIFYPORT_ACCOUNT_ID}/contacts/membership" \
  -H "X-Api-Key: ${UNIFYPORT_API_KEY}" \
  --data-urlencode "contact_id=${WHATSAPP_CONTACT_LID}"

Mã hóa tham số truy vấn giúp truyền đúng định danh chứa @. Phản hồi thành công có data.contact_id và giá trị boolean data.is_in_contacts.

Hiển thị ba kết quả thay vì một ô đánh dấu

Một lỗi thiết kế thường gặp là chuyển mọi giá trị thiếu hoặc được đánh giá là sai thành “chưa lưu”. Khi đó, timeout, nền tảng không hỗ trợ hoặc phản hồi không hợp lệ đều bị biến thành kết luận phủ định sai.

Ví dụ JavaScript sau phân loại HTTP status đã nhận và JSON đã phân tích; nó không gửi yêu cầu mạng:

function classifyMembership(httpStatus, body) {
  if (httpStatus !== 200) return 'unknown';
  const value = body?.data?.is_in_contacts;
  if (value === true) return 'saved';
  if (value === false) return 'not_saved';
  return 'unknown';
}

Các chuỗi này là nhãn nội bộ của ứng dụng, không phải trường bổ sung trong phản hồi API. Lỗi kết nối hoặc phản hồi không phải JSON phải được xử lý là chưa xác định trước khi gọi hàm phân loại.

Quan sát	Trạng thái giao diện	Hành động đề xuất
`200` và boolean `true`	Đã lưu	Hiển thị thời điểm kiểm tra
`200` và boolean `false`	Chưa lưu	Chỉ đề xuất thao tác thêm riêng, có kiểm tra quyền, khi cần
`501 unsupported_by_provider`	Không hỗ trợ / chưa xác định	Kiểm tra nền tảng đã chọn, không tự thêm
Timeout, phản hồi lỗi hoặc thiếu boolean	Chưa xác định	Giữ thông tin chẩn đoán, điều tra hoặc làm mới

Lưu kết quả cùng tài khoản, LID và thời điểm kiểm tra do ứng dụng ghi nhận. Không dùng chung một kết quả cache cho nhiều tài khoản nhắn tin. Nếu nhân viên đã chọn liên hệ khác, hãy bỏ qua phản hồi đến muộn của lựa chọn cũ. Không trình bày kết quả cũ như một bảo đảm vĩnh viễn.

Giữ các thao tác tiếp theo độc lập

Kết quả chưa lưu không đồng nghĩa với quyền ghi dữ liệu. Nếu nhân viên thực sự muốn lưu người đó, hãy dùng API thêm liên hệ riêng, giữ các định danh trả về và kiểm tra lại khi cần xác nhận trạng thái mới nhất.

“Chưa lưu” cũng không có nghĩa là “bị chặn”. Bài So sánh tắt thông báo và chặn liên hệ giải thích các chức năng độc lập này. Không bỏ chặn, gửi tin thử hoặc sửa danh bạ như một tác dụng phụ của việc hiển thị trạng thái.

Khi xảy ra lỗi, giữ HTTP status và request_id nếu có, nhưng không ghi API key hay toàn bộ hồ sơ liên hệ vào log. Ứng dụng cũng cần giới hạn nhân viên nào được xem danh bạ của từng tài khoản.

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

Có biết người kia đã lưu số của tôi hay chưa không?

Không. API kiểm tra danh sách liên hệ của tài khoản đang kết nối, không đọc danh bạ của người kia.

`is_in_contacts: false` có phải lỗi không?

Nếu nằm trong phản hồi 200 thành công, đây là kết quả phủ định hợp lệ. Thiếu dữ liệu hoặc yêu cầu thất bại phải là chưa xác định, không phải false.

Có thể dùng JID số điện thoại thay cho LID không?

Đầu vào WhatsApp được tài liệu quy định là LID do API liên hệ trả về trong conversation_id. Hãy dùng giá trị đó, không dùng định danh suy đoán.

Nhận thẻ liên hệ có chứng minh đã lưu không?

Không. Tin nhắn chứa liên hệ và thao tác cập nhật danh bạ là hai việc riêng. Hãy kiểm tra khi sự khác biệt này quan trọng với quy trình.

Bước tiếp theo và nguồn tham khảo

Xây dựng chức năng chỉ đọc theo tài liệu kiểm tra liên hệ. Trước khi phát hành, kiểm thử true, false, thiếu dữ liệu, nền tảng không hỗ trợ, timeout và đổi liên hệ trong khi yêu cầu đang chờ. Đây là các ca kiểm thử đề xuất, không phải kết quả đã thực hiện.

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

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