Log inStart Free Trial
easyCoexistence Official APIs

How to import WhatsApp Business app chat history and contacts through the API

A WhatsApp Business app number connected through Coexistence can send its existing contacts and up to 180 days of one-to-one chats to the API once, within 24 hours of onboarding. Contacts arrive as smb_app_state_sync webhooks and chats as history webhooks, in chunks ordered by metadata.chunk_order; metadata.progress at 100 marks the import complete. The business chooses in the app whether to share chats.

easyCoexistence connects your customers' WhatsApp Business app numbers through Coexistence and asks Meta for their contacts and chat history the moment your webhook is in place, so the history goes straight to your endpoint with nothing stored on the way, and every number monitored 24/7.

180 days

How far back the history webhooks reach, counted from when the business was onboarded onto the Cloud API.

24 hours

Time after onboarding in which a business's contacts and message history must be synchronized.

2593109

Error code on the history webhook when the business has turned history sharing off in the WhatsApp Business app.

Once

How often each sync can run; repeating it needs the customer to offboard and complete Embedded Signup again.

100

The progress value that marks a history synchronization as complete.

How does the import start?

With a webhook destination on the number. When it connects with webhook_url already set on the connect session, or when you set one with PUT /connections/{id}/webhook within 24 hours of connecting, easyCoexistence asks Meta for the data once: POST /{phone_number_id}/smb_app_data with sync_type smb_app_state_sync for contacts, then history for chats, the order Meta documents. The number's event log records history_sync_requested with Meta's request_id values for support, or history_sync_failed with the reason.

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

What do the contact webhooks carry?

Field smb_app_state_sync, with a state_sync array in the value. Each item has type contact; a contact object with full_name, first_name and phone_number; an action of add or remove; and metadata.timestamp. The names are left out on remove. Meta keeps sending these webhooks after the import whenever the business adds, edits or removes a contact in the WhatsApp Business app, so your address book stays in step with the phone.

What do the history webhooks carry?

Field history, with a history array in the value. Each item holds metadata, with phase, chunk_order and progress, and threads, one per customer: the thread id is the customer's number, and messages lists that one-to-one conversation, incoming and outgoing, with from telling which side sent each one. A message carries id, timestamp, type, its content under the type's name, and history_context.status, such as READ or DELIVERED. Group chats are not included.

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" }
                      }
                    ]
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  ]
}

How are media messages imported?

As placeholders first. A media message comes with type media_placeholder, with no content and no media ID. Meta then sends separate history webhooks carrying the media IDs, but only for media sent within 14 days of onboarding; fetch those files from Meta with the customer's token. Media older than that stays a placeholder, so show it as an attachment that is not available rather than leaving a gap in the thread.

In what order do chunks arrive, and when is the import done?

Not necessarily in order. Meta splits the chats into three phases, newest first: phase 0 is the day before onboarding, phase 1 reaches back to day 90 and phase 2 to day 180. Chunks can arrive out of sequence, so sort them by metadata.chunk_order. metadata.progress is the percentage of the whole sync, and 100 means it is complete; the phase number alone does not tell you that a phase has finished.

What if the business declines to share chats?

During the connection, the WhatsApp Business app asks the business whether to share its chat history. Declining arrives as a history webhook with no messages and an errors array whose code is 2593109, titled History sync is turned off by the business from the WhatsApp Business App. Contacts still arrive, and live messages flow as usual from the moment the number connected.

Can the import run again?

Not on the same connection. Meta allows each sync once, within 24 hours of onboarding, and it cannot be replayed. Running it again takes the customer disconnecting the number and connecting it again, which counts as a new onboarding: with your destination still on file, easyCoexistence asks for the import again, so deduplicate on each message's id. That includes a number coming back after the 14-day rule.

What should be ready before you send the connect link?

Your endpoint, up and answering. Meta checks the URL with its GET handshake when the destination is applied, and the import is requested once, straight after. If the handshake fails, the number still connects but without a destination, the session's last_error explains why, and nothing is imported unless you fix the endpoint and set it with PUT /connections/{id}/webhook inside the 24 hours. A number with no webhook_url gets no import at all, because content sent to easyCoexistence is dropped.

How to set it up

  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.

Common mistakes

  • Rejecting large history chunks. Meta's payloads can reach 3 MB, while Express parses JSON only up to 100 KB by default, so raise the limit or the chunks fail and Meta keeps retrying them.
  • Processing chunks in arrival order. They can arrive out of sequence, so sort by metadata.chunk_order and wait for progress 100 before calling the import complete.
  • Inserting history without deduplicating. Live messages can overlap the import and a reconnection runs it again, so key each message on its id.
  • Sending the connect link before the endpoint answers Meta's handshake. The destination is then not applied, and unless you set it within 24 hours the number's history is never imported.
Doing this with EasyCoexistence

US$ 9 to US$ 0.75 per connection per month, falling as you add connections, with the first 3 days free.

easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.

Frequently asked questions

How far back does the WhatsApp chat history import go?

Up to 180 days before the number was onboarded onto the Cloud API, covering one-to-one chats in both directions.

Are group chats imported?

No. Meta leaves out messages that are part of a group chat.

Will a customer's old WhatsApp chats reach my webhook?

Yes, up to 180 days of one-to-one chats, sent once within 24 hours of onboarding, if the business chooses in the app to share them.

Does easyCoexistence keep a copy of the imported chats?

No. Meta sends the history straight to your webhook_url, like live messages, and nothing is stored on the way.

Keep reading

Connect your first channel in two minutes.

No platform reviews to wait for. Connect WhatsApp, Instagram, TikTok or another channel, then ask your AI to post, reply or report, and watch it work.

  • 3 days free
  • Cancel any time
  • Official APIs only
  • Monitored 24/7

Verified on