ログイン無料トライアルを開始
easyCoexistence 公式 API

API 経由で WhatsApp Business アプリのチャット履歴と連絡先を取り込む方法

Coexistence で接続した WhatsApp Business アプリの番号は、既存の連絡先と最大 180 日分の 1 対 1 のチャットを、オンボーディングから 24 時間以内に一度だけ API へ送信できます。連絡先は smb_app_state_sync の Webhook として、チャットは history の Webhook として届き、metadata.chunk_order の順に分割されます。metadata.progress が 100 になると取り込みは完了です。チャットを共有するかどうかは、企業がアプリ内で選択します。

easyCoexistence は、お客様の WhatsApp Business アプリの番号を Coexistence で接続し、Webhook が設定された時点で Meta に連絡先とチャット履歴を要求します。

180 days

Cloud API へのオンボーディング時点から数えて、履歴 Webhook が遡る期間。

24 hours

連絡先とメッセージ履歴を同期しなければならない、オンボーディング後の時間。

2593109

企業が WhatsApp Business アプリでチャット履歴の共有をオフにしている場合に、履歴 Webhook に返されるエラーコード。

Once

各同期を実行できる頻度。繰り返すには、顧客が接続を解除し、Embedded Signup を再度完了する必要があります。

100

履歴の同期が完了したことを示す progress の値。

取り込みはどのように始まりますか?

番号に Webhook の送信先が設定されていることから始まります。接続セッションに webhook_url が設定された状態で接続された場合、または接続後 24 時間以内に PUT /connections/{id}/webhook で設定した場合、easyCoexistence は Meta にデータを一度だけ要求します。まず連絡先について、POST /{phone_number_id}/smb_app_data を sync_type smb_app_state_sync で送信し、次にチャットについて history で送信します。これは Meta が文書化している順序です。番号のイベントログには、サポート用の Meta の request_id 値とともに history_sync_requested が記録されます。失敗した場合は、理由とともに history_sync_failed が記録されます。

1Connect sessionwebhook_url and webhook_verify_token set before the link goes out
2Customer connectsScans the QR code and chooses whether to share chats
3Contactssmb_app_state_sync, a change per contact
4Chatshistory chunks, the newest phase first
5Completemetadata.progress reaches 100

連絡先の Webhook には何が含まれますか?

フィールドは smb_app_state_sync で、value 内に state_sync 配列があります。各項目は type として contact を持ち、full_name、first_name、phone_number を含む contact オブジェクト、action として add または remove、そして metadata.timestamp を持ちます。remove の場合は名前が省略されます。Meta は、企業が WhatsApp Business アプリで連絡先を追加、編集、削除するたびに、取り込み後もこれらの Webhook を送り続けます。そのため、アドレス帳は電話機と同じ状態に保たれます。

履歴の Webhook には何が含まれますか?

フィールドは history で、value 内に history 配列があります。各項目は metadata を持ち、その中に phase、chunk_order、progress があります。また、顧客ごとの threads を持ちます。thread の id は顧客の電話番号で、messages はその 1 対 1 の会話を一覧にし、受信と送信の両方を含みます。from により、どちらの側が送ったかがわかります。各メッセージは id、timestamp、type、型名の下にある content、そして history_context.status(READ や DELIVERED など)を持ちます。グループチャットは含まれません。

A history webhook, as Meta sends it
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WABA_ID>",
      "changes": [
        {
          "field": "history",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": { "display_phone_number": "<BUSINESS_NUMBER>", "phone_number_id": "<PHONE_NUMBER_ID>" },
            "history": [
              {
                "metadata": { "phase": 1, "chunk_order": 3, "progress": 42 },
                "threads": [
                  {
                    "id": "<CUSTOMER_NUMBER>",
                    "messages": [
                      {
                        "from": "<CUSTOMER_NUMBER>",
                        "id": "wamid.<ID>",
                        "timestamp": "1790726400",
                        "type": "text",
                        "text": { "body": "<MESSAGE_TEXT>" },
                        "history_context": { "status": "READ" }
                      }
                    ]
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  ]
}

メディアメッセージはどのように取り込まれますか?

まずプレースホルダーとして取り込まれます。メディアメッセージは type が media_placeholder で、content もメディア ID もない状態で届きます。その後 Meta は、メディア ID を含む別の history Webhook を送ります。ただし対象は、オンボーディングから 14 日以内に送信されたメディアのみです。これらのファイルは、顧客のトークンを使って Meta から取得してください。それより古いメディアはプレースホルダーのままになるため、スレッドに空白を残さず、利用できない添付ファイルとして表示してください。

チャンクはどの順序で届き、取り込みはいつ完了しますか?

必ずしも順序通りには届きません。Meta はチャットを、新しいものから順に 3 つのフェーズに分けます。フェーズ 0 はオンボーディングの前日分、フェーズ 1 は 90 日前まで、フェーズ 2 は 180 日前までを扱います。チャンクは順番が前後して届くことがあるため、metadata.chunk_order で並べ替えてください。metadata.progress は同期全体に対する割合で、100 は完了を意味します。フェーズ番号だけでは、そのフェーズが終わったかどうかはわかりません。

企業がチャットの共有を拒否した場合はどうなりますか?

接続中、WhatsApp Business アプリは企業にチャット履歴を共有するかどうかを尋ねます。共有を拒否すると、メッセージのない history Webhook が届き、コードが 2593109 の errors 配列が含まれます。そのタイトルは「History sync is turned off by the business from the WhatsApp Business App」です。連絡先は引き続き届き、番号が接続された時点からライブメッセージは通常どおり流れます。

取り込みを再実行することはできますか?

同じ接続では再実行できません。Meta は同期を各 1 回に限り、オンボーディングから 24 時間以内に実行します。再生することはできません。再実行するには、顧客が番号の接続を解除して再び接続する必要があります。これは新しいオンボーディングとして扱われます。送信先がまだ登録されていれば、easyCoexistence は取り込みを再び要求します。そのため、各メッセージの id で重複を排除してください。14 日ルールの後に番号が戻ってくる場合も同様です。

接続リンクを送る前に準備しておくべきことは何ですか?

エンドポイントが稼働し、応答していることです。送信先が適用されるとき、Meta は GET ハンドシェイクで URL を確認します。取り込みはその直後に一度だけ要求されます。ハンドシェイクが失敗しても番号は接続されますが、送信先は設定されず、セッションの last_error に理由が記録されます。エンドポイントを修正し、24 時間以内に PUT /connections/{id}/webhook で設定しない限り、何も取り込まれません。webhook_url がない番号は一切取り込まれません。easyCoexistence に送られたコンテンツは破棄されるためです。

設定方法

  1. Prepare the endpointDeploy an HTTPS URL with a random secret in its path that answers Meta's GET handshake and accepts bodies up to 3 MB.
  2. Create the connect sessionPOST /connect-sessions with webhook_url and webhook_verify_token, then send the customer the url it returns.
  3. Store contacts and chatsUpsert contacts from smb_app_state_sync, and insert history messages keyed on their id, sorted by chunk_order.
  4. Wait for progress 100Treat the import as finished when metadata.progress reaches 100, or as declined when a history webhook carries error 2593109.

よくある間違い

  • 大きな history チャンクを拒否すること。Meta のペイロードは 3 MB に達することがありますが、Express は既定では 100 KB までの JSON しか解析しません。上限を引き上げないと、チャンクは失敗し、Meta が再試行を続けます。
  • チャンクを届いた順に処理すること。順序が入れ替わることがあるため、metadata.chunk_order で並べ替え、progress が 100 になるまで待ってから取り込み完了とみなしてください。
  • 重複を排除せずに履歴を挿入すること。ライブメッセージが取り込みと重なることがあり、再接続すると取り込みが再び実行されるため、各メッセージを id で管理してください。
  • エンドポイントが Meta のハンドシェイクに応答する前に接続リンクを送ること。その場合、送信先は適用されず、24 時間以内に設定しなければ、その番号の履歴は二度と取り込まれません。
EasyCoexistence で実現する

そのため履歴は途中で保存されることなく、エンドポイントへ直接届きます。すべての番号を 24 時間 365 日監視します。接続済みの番号 1 件あたり月額 US$ 9 から、番号を増やすほど下がり US$ 0.75 まで。最初の 3 日間は無料です。

よくある質問

WhatsApp のチャット履歴の取り込みは、どこまで遡りますか?

Cloud API にオンボーディングされる前の最大 180 日分で、双方向の 1 対 1 チャットが対象です。

グループチャットは取り込まれますか?

いいえ。Meta はグループチャットに含まれるメッセージを除外します。

顧客の古い WhatsApp チャットは、私の Webhook に届きますか?

はい。企業がアプリ内で共有を選択した場合、オンボーディング後 24 時間以内に一度だけ送信される、最大 180 日分の 1 対 1 チャットが届きます。

easyCoexistence は、取り込んだチャットのコピーを保存しますか?

いいえ。Meta はライブメッセージと同様に、履歴を webhook_url に直接送信し、途中で何も保存されません。

続きを読む

最初のチャンネルを 2 分で接続しましょう。

プラットフォームの審査を待つ必要はありません。WhatsApp、Instagram、TikTok などのチャンネルを接続して、AI に投稿、返信、レポートを任せてみてください。

  • 3 日間無料
  • いつでも解約可能
  • 公式 API のみ使用
  • 24/7 監視

確認日