Message History Sync

1. 1

   Finish Coexistence onboarding

   The business connects its Business app number through the Coexistence variant of Embedded Signup and, in the app's confirmation screen, chooses whether to share chat history. Your app must be subscribed to the history, smb_app_state_sync and smb_message_echoes webhook fields.

2. 2

   Request contacts and history

   Call POST /{PHONE_NUMBER_ID}/smb_app_data twice with the business token: once with sync_type: "smb_app_state_sync" and once with sync_type: "history". Without these calls Meta never sends the sync. Do it right after onboarding: the window is 24 hours.

3. 3

   Accept chunks fast and queue them

   Each history webhook can carry many threads. Verify the signature, write the raw payload to a queue and return 200 immediately; parse and store in workers so a slow database never causes Meta to retry.

4. 4

   Store idempotently by phase and chunk

   Key each chunk by phone number ID, phase and chunk_order, and each message by its id. Insert both messages (inbound) and message_echoes (outbound) so threads are not one-sided, and keep the original timestamps.

5. 5

   Track completion and declines

   Use progress to show a progress bar and mark the sync complete when phase 2 reaches 100. If the payload holds errors with code 2593109, the business declined sharing: show "history not shared" rather than raising an alert.

History depth

Up to 180 days of one-to-one chats

Media included

Files from the last 14 days only

Groups

Not imported

Deadline

Sync must finish within 24 hours of onboarding

Trigger

POST /{PHONE_NUMBER_ID}/smb_app_data (sync_type history)

Webhook fields

history, smb_app_state_sync (contacts)

Phases

0 = day 0–1 · 1 = day 1–90 · 2 = day 90–180

Declined sharing

errors[] with code 2593109

• Never requesting the sync

  Subscribing to the history field is not enough; nothing arrives until you call smb_app_data. Make the two requests part of the onboarding job and alert if no chunk or decline arrives within a few hours.

• Reading only messages[]

  Business replies live in message_echoes inside each thread. Ingest both arrays with the right direction, or the archive shows customers talking to nobody.

• Treating a decline as an outage

  A business choosing not to share history produces an error payload by design. Surface it to the customer in plain words and keep it out of on-call alerting.

• Processing chunks inline

  Thousands of large payloads in minutes will time out a handler that writes to the database before answering, which triggers retries and duplicates. Acknowledge, queue, and deduplicate by chunk and message ID.

• Ignoring retention rules

  You are importing months of personal conversations. Apply your data-retention and DPDP Act policies to the archive from day one, including deletion when the business offboards.

For a business moving from the app to a shared team inbox, history is what makes the switch feel safe: an agent opening a customer's thread sees last month's order discussion instead of a blank screen. For the developer, the sync is a burst of hundreds or thousands of webhook deliveries arriving in minutes, out of order and with a hard deadline, so it tests idempotency, queueing and data-retention design more than any normal day of traffic.

• Show onboarding customers a progress bar driven by progress; it removes "where are my chats?" tickets.
• Media older than 14 days will not arrive, so render a clear placeholder instead of a broken attachment.
• Some media resolves in a later history webhook shaped like a normal messages payload; handle both shapes.
• Size your queue workers for the onboarding burst, not for steady-state traffic.