WhatsAppの会話一覧にチャットが足りない？ラベル条件を確認

UnifyPortで取得したWhatsAppの会話一覧が想定より少ない場合は、アカウントを再接続する前にクエリを確認してください。ドキュメント上、label_idを省略したWhatsAppの一覧は、スター付き／「特别关注」の会話だけを返します。 ページングを終えても、選択した一覧が全チャットの台帳になるわけではありません。会話の検出、連絡先の検索、過去メッセージの取得は別の処理です。

要点

• label_idの省略は「全WhatsAppチャット」を意味しません。
• ラベル一覧に含まれるのはラベル定義であり、会話レコードではありません。
• ページング中はメッセージングアカウントと絞り込み条件を固定します。
• 絞り込み結果に存在しないという理由だけで、ローカルの会話を削除しないでください。

どの一覧を取得しているか確認する

WhatsAppのヘルプセンターはリストをカスタマイズ可能なチャットフィルターと説明しています。フィルター付き画面を理解する参考にはなりますが、UnifyPort APIの仕様を定義するものではなく、アプリ内のすべてのリストに対応するAPIがあるとも限りません。

実装では会話一覧のリファレンスを基準にします。この操作はプロバイダーへのリアルタイム照会であり、UnifyPortのローカルデータベースから履歴を読む操作ではありません。

読み取り操作	返されるもの	判断できないこと
WhatsAppでlabel_idを省略した会話一覧	スター付き／特別にフォローした会話	アカウントの全チャット
指定したlabel_idでの会話一覧	選択ラベルのビュー	アカウント全体の会話台帳
会話ラベル一覧	idとnameを持つラベル	各ラベルに属するチャット
連絡先一覧	プロバイダーのアドレス帳項目	全会話やメッセージ
グループ一覧	会話していないものも含む参加済みグループ	個人チャットやグループのメッセージ履歴

対象アカウントのラベル一覧からラベルIDを取得し、表示名で代用しないでください。6月のAPI更新記事では作成やラベル付けの操作を紹介しています。本記事の焦点は、目的のビューを読み取り、その範囲を全体と取り違えないことです。

WhatsAppの会話が見つからないときの確認順序

1. アカウントと検索範囲を確認する

リクエストが使用するワークスペースの認証情報とaccount_idを確認します。別のメッセージングアカウントで取得したラベルIDを、このアカウントのフィルターとして頼ることはできません。APIキーはバックエンドに保管し、診断ログに認証情報を残さないでください。

label_idが未指定なのか、実際のIDを含むのか記録します。空文字、ワイルドカード、独自の「all」という値で全会話を取得できるとは仮定しないでください。そのような全件指定値はここでは文書化されていません。

任意のtypeは、正確なuser、group、channelをカンマ区切りで受け取り、空白の除去は行いません。たとえばuser,groupが文書化された構文であり、user, groupは生成しないでください。グループだけを指定して個人チャットが表示されなくても、接続障害とは言えません。

2. 同じ条件のままページングする

limitは1〜100、既定値は20です。data.has_moreが続きの存在を示す間は、data.next_cursorを使い、アカウント、ラベル、種類の条件を変えずに取得します。カーソルは不透明な値として扱い、解読、編集、異なるクエリ間での共有をしないでください。

無効または期限切れのカーソルは、プロバイダーによって拒否されるか、ページングを最初から開始させる場合があります。クライアント側ではカーソルの繰り返しを検知し、アカウントでスコープを区切ったconversation_idで重複を統合する設計を推奨します。循環が発生したら診断を表示して停止し、無限ループにしないでください。意図的にやり直す場合も、同じ条件で新しい取得処理を開始して重複を除去します。

has_more: falseはそのクエリのページング終了です。他のラベル、選択外のチャット、過去メッセージまで取得した証拠ではありません。リアルタイム照会なので、複数ページの結果を不変のスナップショットとみなす保証もありません。

3. 既知の会話を直接調べる

信頼できるイベントや以前のAPI応答で会話IDを取得済みなら、単一会話の取得でconversation_idをクエリパラメーターに指定します。URLエンコーダーで組み立て、プロバイダーの会話IDをパスの一部にしないでください。

直接取得できるのに一覧に存在しない場合は、接続断と決めつけず、一覧の範囲を調べます。見つからない応答の場合も、アカウントとIDの確認が必要です。ローカル履歴を消してよいという意味ではありません。表示名や電話番号から会話IDを作らないでください。

4. 知りたい対象に合う操作を選ぶ

アドレス帳の確認には連絡先一覧を使います。メッセージ履歴の有無にかかわらずアドレス帳の項目を対象にします。チャット操作には返されたconversation_idの対応関係を使い、連絡先のidと同じだと仮定しないでください。連絡先名の同期ガイドでこの識別子の境界を説明しています。

グループ一覧では、まだメッセージを交わしていない参加済みグループも取得できます。どちらの読み取りもメッセージアーカイブの代替ではなく、結果を結合しても全個人チャットの検出を証明できません。

受信トレイに正しい範囲を表示する

アプリでは「観測済みの会話」「現在のプロバイダーフィルター結果」「保存済みメッセージ」を分けて管理します。これはローカル設計の推奨事項であり、追加のAPIフィールドではありません。

ラベルまたは特別にフォローした会話だけを表示するなら、「すべての会話」ではなく、実際の範囲が分かる見出しを付けます。フィルターから消えた項目はそのビューから外すだけで、ローカルの会話やメッセージを自動削除しないでください。取得失敗と、正常に取得した空の結果も区別します。LINEを併設する受信トレイでも、このWhatsAppの既定動作を他チャネルへ一律に適用してはいけません。

継続的な受信には、UnifyPortの非公式インターフェースがmessage.receivedなどの正規化イベントを提供します。配信仕様に従いsigning_secretを設定し、X-Device-Timestamp、ピリオド、生のリクエストボディを連結した内容をHMAC-SHA256で検証します。タイムスタンプの鮮度も確認し、永続化してから2xxを返します。観測したアカウントと会話IDを後の検索用に保存してください。

ただし、観測した通信がないチャットまで発見できる保証はありません。UnifyPortにはRESTのメッセージ履歴読み取りAPIや、欠落イベントの再配信保証はありません。WhatsAppのオンデマンド履歴取得は、既知の対象個人チャットについて利用可能な過去メッセージを非同期で要求する別の処理です。全チャットを列挙する操作ではありません。

FAQ

limitを増やせば全チャットが表示されますか？

いいえ。変わるのは選択中のクエリのページサイズだけです。既定の対象範囲は解除されません。

ラベルIDを会話IDとして使えますか？

使えません。ラベルは分類、会話IDはチャットを識別します。別のリソースです。

空の一覧は再認証が必要な証拠ですか？

いいえ。先にアカウント、フィルター、ページング、返されたエラーを確認します。空のビューだけを理由に認証をやり直さないでください。

次の手順と参考資料

管理下のテストアカウントで会話一覧リファレンスとリクエストを照合し、既知の会話の直接取得と一覧への表示を比較してください。共有受信トレイの照合に使う前に、ラベル変更、カーソルの反復、空の結果をテストします。これは推奨テストであり、実運用の検証結果ではありません。

確認日：2026-10-03。

• UnifyPort：会話一覧
• UnifyPort：会話ラベル一覧
• WhatsApp Help Center：How to use lists