Wie Sie den Chatverlauf und die Kontakte der WhatsApp Business App über die API importieren
Eine WhatsApp-Business-App-Nummer, die über Coexistence verbunden ist, kann ihre bestehenden Kontakte und bis zu 180 Tage Einzelchats einmalig innerhalb von 24 Stunden nach dem Onboarding an die API senden. Kontakte kommen als smb_app_state_sync-Webhooks, Chats als History-Webhooks, in Blöcken, sortiert nach metadata.chunk_order. Ein metadata.progress von 100 markiert den Import als abgeschlossen. Das Unternehmen entscheidet in der App, ob Chats geteilt werden.
easyCoexistence verbindet die WhatsApp-Business-App-Nummern Ihrer Kunden über Coexistence und fordert deren Kontakte und Chatverlauf von Meta an, sobald Ihr Webhook steht.
Wie weit die History-Webhooks zurückreichen, gerechnet ab dem Zeitpunkt, an dem das Unternehmen auf die Cloud API aufgeschaltet wurde.
Zeitfenster nach dem Onboarding, innerhalb dessen Kontakte und Nachrichtenverlauf eines Unternehmens synchronisiert werden müssen.
Fehlercode im History-Webhook, wenn das Unternehmen die Weitergabe des Verlaufs in der WhatsApp Business App deaktiviert hat.
Wie oft jede Synchronisation laufen kann; eine Wiederholung erfordert, dass der Kunde das Offboarding durchführt und Embedded Signup erneut abschließt.
Der Fortschrittswert, der eine History-Synchronisation als abgeschlossen markiert.
Wie startet der Import?
Mit einem Webhook-Ziel auf der Nummer. Wenn sie mit bereits gesetzter webhook_url in der Connect-Session verbunden wird oder Sie innerhalb von 24 Stunden nach der Verbindung ein Ziel mit PUT /connections/{id}/webhook setzen, fragt easyCoexistence die Daten einmalig bei Meta an: POST /{phone_number_id}/smb_app_data mit sync_type smb_app_state_sync für Kontakte, danach history für Chats, in der von Meta dokumentierten Reihenfolge. Das Ereignisprotokoll der Nummer enthält history_sync_requested mit den request_id-Werten von Meta für den Support oder history_sync_failed mit dem Grund.
Was enthalten die Kontakt-Webhooks?
Feld smb_app_state_sync mit einem state_sync-Array im value. Jedes Element hat type contact, ein Kontaktobjekt mit full_name, first_name und phone_number, eine Aktion add oder remove sowie metadata.timestamp. Bei remove fehlen die Namen. Meta sendet diese Webhooks auch nach dem Import weiter, wann immer das Unternehmen in der WhatsApp Business App einen Kontakt hinzufügt, bearbeitet oder entfernt, sodass Ihr Adressbuch mit dem Telefon synchron bleibt.
Was enthalten die History-Webhooks?
Feld history mit einem history-Array im value. Jedes Element enthält metadata mit phase, chunk_order und progress sowie threads, einen pro Kunden: Die Thread-ID ist die Nummer des Kunden, und messages listet diesen Einzelchat auf, eingehend und ausgehend, wobei from angibt, welche Seite sie gesendet hat. Eine Nachricht enthält id, timestamp, type, ihren Inhalt unter dem Namen des Typs und history_context.status, etwa READ oder DELIVERED. Gruppenchats sind nicht enthalten.
{
"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" }
}
]
}
]
}
]
}
}
]
}
]
}Wie werden Medien-Nachrichten importiert?
Zunächst als Platzhalter. Eine Medien-Nachricht kommt mit type media_placeholder, ohne Inhalt und ohne Medien-ID. Meta sendet danach separate History-Webhooks mit den Medien-IDs, aber nur für Medien, die innerhalb von 14 Tagen nach dem Onboarding gesendet wurden. Diese Dateien holen Sie mit dem Token des Kunden von Meta ab. Ältere Medien bleiben Platzhalter. Zeigen Sie sie daher als nicht verfügbaren Anhang an, statt im Verlauf eine Lücke zu lassen.
In welcher Reihenfolge kommen die Blöcke an, und wann ist der Import fertig?
Nicht zwingend in der richtigen Reihenfolge. Meta teilt die Chats in drei Phasen auf, die neuesten zuerst: Phase 0 ist der Tag vor dem Onboarding, Phase 1 reicht bis Tag 90 und Phase 2 bis Tag 180. Blöcke können außer der Reihe eintreffen, sortieren Sie sie daher nach metadata.chunk_order. metadata.progress ist der prozentuale Anteil der gesamten Synchronisation, und 100 bedeutet abgeschlossen. Die Phasennummer allein zeigt nicht an, dass eine Phase beendet ist.
Was passiert, wenn das Unternehmen die Weitergabe von Chats ablehnt?
Während der Verbindung fragt die WhatsApp Business App das Unternehmen, ob der Chatverlauf geteilt werden soll. Eine Ablehnung kommt als History-Webhook ohne messages und mit einem errors-Array, dessen code 2593109 lautet, mit dem Titel History sync is turned off by the business from the WhatsApp Business App. Kontakte kommen trotzdem an, und Live-Nachrichten fließen ab dem Moment der Verbindung wie gewohnt.
Kann der Import erneut laufen?
Nicht auf derselben Verbindung. Meta erlaubt jede Synchronisation einmal, innerhalb von 24 Stunden nach dem Onboarding, und sie kann nicht wiederholt werden. Ein erneuter Lauf setzt voraus, dass der Kunde die Nummer trennt und erneut verbindet. Das gilt als neues Onboarding. Wenn Ihr Ziel noch hinterlegt ist, fragt easyCoexistence den Import erneut an. Entfernen Sie Duplikate daher anhand der id jeder Nachricht. Dazu gehört auch eine Nummer, die nach der 14-Tage-Regel zurückkehrt.
Was sollte bereit sein, bevor Sie den Connect-Link senden?
Ihr Endpoint, online und antwortend. Meta prüft die URL beim Setzen des Ziels mit ihrem GET-Handshake, und der Import wird direkt danach einmal angefordert. Schlägt der Handshake fehl, verbindet sich die Nummer trotzdem, aber ohne Ziel. Der last_error der Session erklärt den Grund, und es wird nichts importiert, bis Sie den Endpoint korrigieren und innerhalb der 24 Stunden mit PUT /connections/{id}/webhook setzen. Eine Nummer ohne webhook_url erhält gar keinen Import, weil Inhalte, die an easyCoexistence gesendet werden, verworfen werden.
So richten Sie es ein
- 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.
- Create the connect sessionPOST /connect-sessions with webhook_url and webhook_verify_token, then send the customer the url it returns.
- Store contacts and chatsUpsert contacts from smb_app_state_sync, and insert history messages keyed on their id, sorted by chunk_order.
- Wait for progress 100Treat the import as finished when metadata.progress reaches 100, or as declined when a history webhook carries error 2593109.
Häufige Fehler
- Große History-Blöcke abweisen. Metas Payloads können 3 MB erreichen, während Express JSON standardmäßig nur bis 100 KB parst. Erhöhen Sie das Limit, sonst schlagen die Blöcke fehl und Meta versucht sie immer wieder.
- Blöcke in Eingangsreihenfolge verarbeiten. Sie können außer der Reihe eintreffen. Sortieren Sie nach metadata.chunk_order und warten Sie auf progress 100, bevor Sie den Import als abgeschlossen melden.
- Verlauf ohne Duplikatprüfung einfügen. Live-Nachrichten können sich mit dem Import überschneiden, und eine Wiederverbindung führt ihn erneut aus. Speichern Sie jede Nachricht daher anhand ihrer id.
- Den Connect-Link senden, bevor der Endpoint Metas Handshake beantwortet. Das Ziel wird dann nicht gesetzt, und wenn Sie es nicht innerhalb von 24 Stunden setzen, wird der Verlauf der Nummer nie importiert.
Der Verlauf geht direkt an Ihren Endpoint, ohne dass etwas zwischengespeichert wird, und jede Nummer wird 24/7 überwacht. US$ 9 bis US$ 0.75 pro Verbindung und Monat, mit sinkendem Preis, je mehr Verbindungen Sie hinzufügen, die ersten 3 Tage kostenlos.
Häufig gestellte Fragen
Wie weit reicht der Import des WhatsApp-Chatverlaufs zurück?
Bis zu 180 Tage vor dem Onboarding der Nummer auf die Cloud API, mit Einzelchats in beide Richtungen.
Werden Gruppenchats importiert?
Nein. Meta lässt Nachrichten aus Gruppenchats weg.
Erreichen die alten WhatsApp-Chats eines Kunden meinen Webhook?
Ja, bis zu 180 Tage Einzelchats, einmalig innerhalb von 24 Stunden nach dem Onboarding, sofern das Unternehmen in der App die Weitergabe wählt.
Bewahrt easyCoexistence eine Kopie der importierten Chats auf?
Nein. Meta sendet den Verlauf direkt an Ihre webhook_url, wie Live-Nachrichten, und unterwegs wird nichts gespeichert.
Weiterlesen
Verbinden Sie Ihren ersten Kanal in zwei Minuten.
Keine Plattform-Prüfungen, auf die Sie warten müssen. Verbinden Sie WhatsApp, Instagram, TikTok oder einen anderen Kanal, bitten Sie dann Ihre KI, zu posten, zu antworten oder Berichte zu erstellen, und sehen Sie ihr bei der Arbeit zu.
- 3 Tage kostenlos
- Jederzeit kündbar
- Nur offizielle APIs
- Überwacht rund um die Uhr (24/7)
Verifiziert am