InloggenGratis proefperiode starten
easyCoexistence Officiële API's

Hoe je de chatgeschiedenis en contacten van de WhatsApp Business-app via de API importeert

Een WhatsApp Business-app-nummer dat via Coexistence is verbonden, kan zijn bestaande contacten en tot 180 dagen aan één-op-één-gesprekken eenmalig naar de API sturen, binnen 24 uur na de onboarding. Contacten komen aan als smb_app_state_sync-webhooks en chats als history-webhooks, in chunks gesorteerd op metadata.chunk_order; metadata.progress op 100 markeert de import als voltooid. Het bedrijf kiest in de app zelf of chats worden gedeeld.

easyCoexistence verbindt de WhatsApp Business-app-nummers van je klanten via Coexistence en vraagt bij Meta hun contacten en chatgeschiedenis op zodra je webhook klaarstaat, zodat de geschiedenis rechtstreeks naar je endpoint gaat zonder dat er onderweg iets wordt opgeslagen, en elk nummer wordt 24/7 bewaakt.

180 days

Hoe ver de history-webhooks teruggaan, gerekend vanaf de onboarding van het bedrijf op de Cloud API.

24 hours

Tijd na de onboarding waarbinnen de contacten en de berichtengeschiedenis van een bedrijf gesynchroniseerd moeten zijn.

2593109

Foutcode op de history-webhook wanneer het bedrijf het delen van geschiedenis in de WhatsApp Business-app heeft uitgeschakeld.

Once

Hoe vaak elke synchronisatie kan draaien; voor een herhaling moet de klant zich afmelden en Embedded Signup opnieuw doorlopen.

100

De progress-waarde die een history-synchronisatie als voltooid markeert.

Hoe start de import?

Met een webhook-bestemming op het nummer. Wanneer het nummer verbindt met webhook_url al ingesteld in de connect-sessie, of wanneer je er binnen 24 uur na verbinden een instelt met PUT /connections/{id}/webhook, vraagt easyCoexistence de data eenmalig op bij Meta: POST /{phone_number_id}/smb_app_data met sync_type smb_app_state_sync voor contacten, daarna history voor chats, de volgorde die Meta documenteert. De eventlog van het nummer registreert history_sync_requested met de request_id-waarden van Meta voor support, of history_sync_failed met de reden.

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

Wat bevatten de contactwebhooks?

Veld smb_app_state_sync, met een state_sync-array in de value. Elk item heeft type contact; een contactobject met full_name, first_name en phone_number; een actie van add of remove; en metadata.timestamp. De namen worden weggelaten bij remove. Meta blijft deze webhooks na de import sturen telkens wanneer het bedrijf een contact toevoegt, bewerkt of verwijdert in de WhatsApp Business-app, zodat je adresboek gelijk blijft met de telefoon.

Wat bevatten de history-webhooks?

Veld history, met een history-array in de value. Elk item bevat metadata, met phase, chunk_order en progress, en threads, één per klant: de thread-id is het nummer van de klant, en messages bevat dat één-op-één-gesprek, inkomend en uitgaand, met from die aangeeft welke kant elk bericht heeft verstuurd. Een bericht heeft id, timestamp, type, de inhoud onder de naam van het type, en history_context.status, zoals READ of DELIVERED. Groepschats zijn niet inbegrepen.

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

Hoe worden mediaberichten geïmporteerd?

Eerst als placeholders. Een mediabericht komt binnen met type media_placeholder, zonder inhoud en zonder media-ID. Meta stuurt daarna aparte history-webhooks met de media-ID's, maar alleen voor media die binnen 14 dagen na de onboarding is verstuurd; haal die bestanden bij Meta op met het token van de klant. Media die ouder is dan dat, blijft een placeholder, dus toon het als een bijlage die niet beschikbaar is in plaats van een gat in de thread te laten.

In welke volgorde komen de chunks binnen, en wanneer is de import klaar?

Niet noodzakelijk in volgorde. Meta splitst de chats in drie fases, de nieuwste eerst: fase 0 is de dag vóór de onboarding, fase 1 gaat terug tot dag 90 en fase 2 tot dag 180. Chunks kunnen buiten volgorde binnenkomen, dus sorteer ze op metadata.chunk_order. metadata.progress is het percentage van de hele synchronisatie, en 100 betekent dat die voltooid is; het fasenummer alleen zegt niet dat een fase klaar is.

Wat als het bedrijf weigert chats te delen?

Tijdens de verbinding vraagt de WhatsApp Business-app het bedrijf of het zijn chatgeschiedenis wil delen. Weigeren komt aan als history-webhook zonder berichten en met een errors-array waarvan de code 2593109 is, met als titel History sync is turned off by the business from the WhatsApp Business App. Contacten komen nog steeds binnen, en live berichten stromen gewoon vanaf het moment dat het nummer verbonden is.

Kan de import opnieuw draaien?

Niet op dezelfde verbinding. Meta staat elke synchronisatie één keer toe, binnen 24 uur na de onboarding, en die kan niet opnieuw worden afgespeeld. Opnieuw draaien vereist dat de klant het nummer loskoppelt en opnieuw verbindt, wat telt als een nieuwe onboarding: met je bestemming nog ingesteld vraagt easyCoexistence de import opnieuw aan, dus dedupliceer op de id van elk bericht. Dat geldt ook wanneer een nummer terugkomt na de 14-dagenregel.

Wat moet klaarstaan voordat je de connect-link verstuurt?

Je endpoint, bereikbaar en reagerend. Meta controleert de URL met zijn GET-handshake wanneer de bestemming wordt toegepast, en de import wordt direct daarna eenmalig aangevraagd. Als de handshake mislukt, verbindt het nummer nog steeds maar zonder bestemming, legt last_error van de sessie uit waarom, en wordt niets geïmporteerd tenzij je het endpoint repareert en instelt met PUT /connections/{id}/webhook binnen de 24 uur. Een nummer zonder webhook_url krijgt helemaal geen import, omdat inhoud die naar easyCoexistence wordt gestuurd, wordt weggegooid.

Zo stel je het in

  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.

Veelgemaakte fouten

  • Grote history-chunks afwijzen. De payloads van Meta kunnen tot 3 MB groot zijn, terwijl Express JSON standaard alleen tot 100 KB verwerkt, dus verhoog de limiet of de chunks mislukken en Meta blijft ze opnieuw proberen.
  • Chunks verwerken in aankomstvolgorde. Ze kunnen buiten volgorde binnenkomen, dus sorteer op metadata.chunk_order en wacht op progress 100 voordat je de import voltooid noemt.
  • Geschiedenis invoegen zonder te dedupliceren. Live berichten kunnen overlappen met de import en een herverbinding draait hem opnieuw, dus sleutel elk bericht op zijn id.
  • De connect-link versturen voordat het endpoint de handshake van Meta beantwoordt. De bestemming wordt dan niet toegepast, en tenzij je hem binnen 24 uur instelt, wordt de geschiedenis van het nummer nooit geïmporteerd.
Dit doen met EasyCoexistence

Vanaf US$ 9 per verbonden nummer per maand, dalend tot US$ 0,75 naarmate je meer nummers toevoegt, met een gratis proefperiode van 3 dagen.

Veelgestelde vragen

Hoe ver gaat de import van de WhatsApp-chatgeschiedenis terug?

Tot 180 dagen vóór de onboarding van het nummer op de Cloud API, en dat dekt één-op-één-chats in beide richtingen.

Worden groepschats geïmporteerd?

Nee. Meta laat berichten weg die deel uitmaken van een groepschat.

Komen oude WhatsApp-chats van een klant bij mijn webhook terecht?

Ja, tot 180 dagen aan één-op-één-chats, eenmalig verstuurd binnen 24 uur na de onboarding, als het bedrijf in de app kiest ze te delen.

Houdt easyCoexistence een kopie van de geïmporteerde chats bij?

Nee. Meta stuurt de geschiedenis rechtstreeks naar je webhook_url, net als live berichten, en onderweg wordt niets opgeslagen.

Lees verder

Koppel je eerste kanaal in twee minuten.

Geen platformbeoordelingen om op te wachten. Verbind WhatsApp, Instagram, TikTok of een ander kanaal, vraag je AI om te posten, te reageren of een rapport te maken, en zie het aan het werk.

  • 3 dagen gratis
  • Op elk moment opzegbaar
  • Alleen officiële API's
  • 24/7 bewaakt

Geverifieerd op