Danh sách hội thoại WhatsApp bị thiếu? Kiểm tra bộ lọc nhãn

Nếu danh sách hội thoại WhatsApp từ UnifyPort có ít cuộc trò chuyện hơn dự kiến, hãy kiểm tra truy vấn trước khi kết nối lại tài khoản. Theo tài liệu, khi không truyền label_id, WhatsApp chỉ trả về các hội thoại được gắn sao / “特别关注”. Đọc hết các trang không biến một danh sách đã lọc thành danh mục toàn bộ cuộc trò chuyện. Tìm hội thoại, tra danh bạ và lấy tin nhắn lịch sử là những tác vụ riêng.

Điểm chính

• Bỏ label_id không có nghĩa là “tất cả cuộc trò chuyện WhatsApp”.
• Danh mục nhãn trả về định nghĩa nhãn, không phải bản ghi hội thoại.
• Giữ nguyên tài khoản nhắn tin và bộ lọc trong một lượt phân trang.
• Không xóa hội thoại cục bộ chỉ vì nó không xuất hiện trong kết quả đã lọc.

Xác định bạn đang đọc danh sách nào

Trung tâm trợ giúp WhatsApp mô tả danh sách là bộ lọc cuộc trò chuyện có thể tùy chỉnh. Đây là ngữ cảnh hữu ích để hiểu giao diện có bộ lọc, nhưng không định nghĩa hành vi API UnifyPort, cũng không chứng minh mọi danh sách trong ứng dụng đều có API tương ứng.

Khi tích hợp, hãy dựa vào tài liệu List conversations. Đây là truy vấn trực tiếp tới nhà cung cấp theo thời gian thực, không phải đọc kho hội thoại từ cơ sở dữ liệu cục bộ của UnifyPort.

Thao tác đọc	Nội dung trả về	Không thể suy ra
Danh sách hội thoại WhatsApp không có label_id	Hội thoại gắn sao / được ưu tiên theo dõi	Mọi cuộc trò chuyện của tài khoản
Danh sách có label_id được chọn	Khung nhìn theo nhãn đó	Danh mục hội thoại toàn tài khoản
Danh sách nhãn hội thoại	Đối tượng nhãn có id và name	Các cuộc trò chuyện thuộc từng nhãn
Danh sách liên hệ	Mục trong danh bạ của nhà cung cấp	Mọi hội thoại hoặc tin nhắn
Danh sách nhóm	Nhóm đã tham gia, kể cả nhóm chưa có hoạt động nhắn tin	Trò chuyện riêng hoặc lịch sử tin nhắn nhóm

Lấy ID nhãn từ danh mục nhãn của đúng tài khoản, không thay bằng tên hiển thị. Bản cập nhật API tháng Sáu giới thiệu thao tác tạo nhãn và thay đổi hội thoại trong nhãn. Bài này tập trung vào phạm vi đọc: lấy đúng khung nhìn mà không nhầm nó với danh mục đầy đủ.

Kiểm tra hội thoại WhatsApp bị thiếu theo thứ tự

1. Xác nhận tài khoản và phạm vi truy vấn

Kiểm tra thông tin xác thực workspace và account_id được dùng trong yêu cầu. ID nhãn lấy từ tài khoản nhắn tin khác không phải bộ lọc đáng tin cậy cho tài khoản hiện tại. Giữ API key ở backend và loại thông tin xác thực khỏi bản ghi chẩn đoán.

Ghi rõ label_id bị bỏ hay chứa một ID thực tế. Đừng giả định chuỗi rỗng, ký tự đại diện hoặc giá trị “all” tự đặt sẽ chọn mọi hội thoại; tài liệu này không quy định bộ chọn toàn bộ như vậy.

Bộ lọc tùy chọn type nhận chính xác các giá trị user, group, channel, phân cách bằng dấu phẩy và không tự loại bỏ khoảng trắng. Ví dụ, user,group đúng cú pháp được mô tả; không tạo user, group. Nếu chỉ yêu cầu nhóm, việc không thấy trò chuyện riêng không phải bằng chứng lỗi kết nối.

2. Phân trang trong cùng phạm vi

limit nhận giá trị 1–100, mặc định 20. Tiếp tục dùng data.next_cursor khi data.has_more cho biết còn kết quả, đồng thời giữ nguyên tài khoản, nhãn và loại hội thoại. Xem cursor là giá trị không trong suốt: không giải mã, sửa đổi hay dùng chung giữa các truy vấn khác nhau.

Cursor không hợp lệ hoặc hết hạn có thể bị từ chối hoặc khiến phân trang bắt đầu lại, tùy nhà cung cấp. Biện pháp phía client được đề xuất là phát hiện cursor lặp, hợp nhất bản ghi trùng bằng conversation_id trong phạm vi tài khoản, rồi dừng và hiển thị chẩn đoán thay vì lặp vô hạn. Nếu chủ động bắt đầu lại, hãy tạo lượt đọc mới với cùng bộ lọc và tiếp tục loại trùng.

has_more: false kết thúc phân trang của truy vấn đó. Nó không chứng minh đã bao gồm các nhãn khác, cuộc trò chuyện không được chọn hay tin nhắn lịch sử. Vì đây là truy vấn trực tiếp, cũng không nên coi kết quả nhiều trang là một ảnh chụp bất biến được tài liệu bảo đảm.

3. Tra trực tiếp cuộc trò chuyện đã biết

Nếu ứng dụng đã có ID hội thoại từ sự kiện đáng tin cậy hoặc phản hồi API trước đó, dùng Get conversation với conversation_id trong tham số truy vấn. Tạo tham số bằng công cụ mã hóa URL thay vì đặt ID của nhà cung cấp vào đoạn đường dẫn.

Tra trực tiếp thành công nhưng không thấy trong danh sách là lý do để kiểm tra phạm vi danh sách, không phải kết luận tài khoản mất kết nối. Kết quả không tìm thấy vẫn cần kiểm tra tài khoản và ID; nó không cho phép xóa lịch sử cục bộ. Không tự dựng ID hội thoại từ tên hiển thị hoặc số điện thoại.

4. Chọn thao tác đọc đúng với câu hỏi

Với câu hỏi về danh bạ, dùng List contacts. Phạm vi của nó bao gồm các liên hệ trong danh bạ bất kể có lịch sử tin nhắn hay không. Dùng ánh xạ conversation_id được trả về cho thao tác với cuộc trò chuyện, không mặc định id liên hệ có thể thay thế. Hướng dẫn đồng bộ tên liên hệ giải thích chi tiết ranh giới định danh này.

List groups có thể trả về nhóm đã tham gia nhưng chưa từng dùng để nhắn tin. Không thao tác nào thay thế kho tin nhắn; kết hợp hai kết quả cũng không chứng minh đã tìm được mọi hội thoại riêng.

Hiển thị đúng phạm vi trong hộp thư

Tách ba khái niệm trong ứng dụng: hội thoại đã quan sát được, kết quả lọc hiện tại của nhà cung cấp và tin nhắn đã lưu. Đây là ranh giới dữ liệu cục bộ được đề xuất, không phải các trường API bổ sung.

Đặt tên khung nhìn theo phạm vi thực tế, chẳng hạn “Nhãn đã chọn” hoặc “Hội thoại ưu tiên”, thay vì “Tất cả hội thoại”. Một mục biến mất khỏi kết quả lọc chỉ nên bị bỏ khỏi khung nhìn đó, không tự động xóa hội thoại và tin nhắn cục bộ. Hiển thị lỗi đọc riêng với kết quả rỗng nhưng thành công. Nếu hộp thư cũng tích hợp Zalo, đừng áp dụng mặc định riêng của WhatsApp cho mọi kênh.

Để nhận liên tục, giao diện không chính thức của UnifyPort cung cấp các sự kiện chuẩn hóa như message.received. Tuân theo hợp đồng giao webhook: cấu hình signing_secret, xác minh HMAC-SHA256 trên X-Device-Timestamp, dấu chấm và nội dung yêu cầu nguyên bản, kiểm tra độ mới của dấu thời gian, rồi lưu bền vững trước khi trả 2xx. Giữ ID tài khoản và hội thoại quan sát được để tra cứu về sau.

Cách này không bảo đảm phát hiện cuộc trò chuyện chưa có lưu lượng mà bạn quan sát được. UnifyPort không có REST API đọc lịch sử tin nhắn và không bảo đảm phát lại dữ liệu bị bỏ lỡ. Quy trình lịch sử WhatsApp theo yêu cầu là tác vụ riêng, yêu cầu bất đồng bộ các tin nhắn cũ có sẵn của một hội thoại riêng đã biết và đủ điều kiện. Nó không liệt kê toàn bộ cuộc trò chuyện.

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

Tăng limit có hiển thị mọi cuộc trò chuyện WhatsApp không?

Không. Nó chỉ thay đổi kích thước trang trong truy vấn đã chọn, không loại bỏ phạm vi mặc định của các hội thoại được ưu tiên.

Có thể dùng ID nhãn làm ID hội thoại không?

Không. Nhãn định danh nhóm phân loại, còn hội thoại định danh cuộc trò chuyện. Đây là hai tài nguyên khác nhau.

Danh sách rỗng có nghĩa là phải xác thực lại tài khoản không?

Không. Trước hết hãy kiểm tra tài khoản, bộ lọc, phân trang và lỗi trả về. Không bắt đầu luồng xác thực mới chỉ vì một khung nhìn đã lọc bị rỗng.

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

Dùng tài khoản kiểm thử do bạn kiểm soát để đối chiếu yêu cầu với tài liệu danh sách hội thoại, rồi so sánh việc tra trực tiếp một cuộc trò chuyện đã biết với khả năng xuất hiện trong bộ lọc. Kiểm thử đổi nhãn, cursor lặp và kết quả rỗng trước khi dùng danh sách để đối soát hộp thư chung. Đây là các phép kiểm tra đề xuất, không phải kết quả vận hành đã ghi nhận.

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

• UnifyPort: List conversations
• UnifyPort: List conversation labels
• WhatsApp Help Center: How to use lists