Jak zaimportować historię czatów i kontakty z aplikacji WhatsApp Business przez API
Numer aplikacji WhatsApp Business połączony przez Coexistence może jednorazowo wysłać do API swoje istniejące kontakty oraz do 180 dni czatów jeden na jeden, w ciągu 24 godzin od onboardingu. Kontakty przychodzą jako webhooki smb_app_state_sync, a czaty jako webhooki history, w porcjach uporządkowanych według metadata.chunk_order; wartość metadata.progress równa 100 oznacza, że import jest zakończony. Firma decyduje w aplikacji, czy udostępnić czaty.
easyCoexistence łączy numery aplikacji WhatsApp Business Twoich klientów przez Coexistence i prosi Meta o ich kontakty oraz historię czatów w chwili, gdy Twój webhook jest gotowy, więc historia trafia prosto do Twojego endpointu bez zapisywania po drodze czegokolwiek, a każdy numer jest monitorowany 24/7.
Jak daleko wstecz sięgają webhooki historii, liczone od chwili, gdy firma przeszła onboarding do Cloud API.
Czas po onboardingu, w którym muszą zostać zsynchronizowane kontakty i historia wiadomości firmy.
Kod błędu w webhooku historii, gdy firma wyłączyła udostępnianie historii w aplikacji WhatsApp Business.
Jak często może działać każda synchronizacja; jej powtórzenie wymaga, by klient przeszedł offboarding i ponownie ukończył Embedded Signup.
Wartość postępu, która oznacza zakończenie synchronizacji historii.
Jak zaczyna się import?
Od miejsca docelowego webhooka przypisanego do numeru. Gdy numer łączy się z już ustawionym webhook_url w sesji połączenia albo gdy ustawisz go przez PUT /connections/{id}/webhook w ciągu 24 godzin od połączenia, easyCoexistence raz prosi Meta o dane: POST /{phone_number_id}/smb_app_data z sync_type smb_app_state_sync dla kontaktów, a następnie history dla czatów, w kolejności, jaką dokumentuje Meta. Dziennik zdarzeń numeru zapisuje history_sync_requested z wartościami request_id od Meta do wsparcia albo history_sync_failed z przyczyną.
Co zawierają webhooki kontaktów?
Pole smb_app_state_sync z tablicą state_sync w value. Każdy element ma type contact; obiekt contact z full_name, first_name i phone_number; działanie add lub remove oraz metadata.timestamp. Przy remove nazwy są pomijane. Meta wysyła te webhooki także po imporcie, zawsze gdy firma doda, edytuje lub usunie kontakt w aplikacji WhatsApp Business, dzięki czemu Twoja książka adresowa pozostaje zgodna z telefonem.
Co zawierają webhooki historii?
Pole history z tablicą history w value. Każdy element ma metadata z phase, chunk_order i progress oraz threads, po jednym na klienta: identyfikator wątku to numer klienta, a messages zawiera tę rozmowę jeden na jeden, przychodzącą i wychodzącą, przy czym from wskazuje, która strona wysłała wiadomość. Wiadomość ma id, timestamp, type, treść pod nazwą typu oraz history_context.status, np. READ lub DELIVERED. Czaty grupowe nie są uwzględniane.
{
"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" }
}
]
}
]
}
]
}
}
]
}
]
}Jak importowane są wiadomości z multimediami?
Najpierw jako symbole zastępcze. Wiadomość multimedialna przychodzi z type media_placeholder, bez treści i bez identyfikatora mediów. Meta następnie wysyła osobne webhooki historii z identyfikatorami mediów, ale tylko dla mediów wysłanych w ciągu 14 dni od onboardingu; pliki pobierz z Meta tokenem klienta. Starsze media pozostają symbolem zastępczym, więc pokaż je jako załącznik niedostępny, zamiast zostawiać lukę w wątku.
W jakiej kolejności przychodzą porcje i kiedy import jest zakończony?
Niekoniecznie w kolejności. Meta dzieli czaty na trzy fazy, od najnowszych: faza 0 to dzień przed onboardingiem, faza 1 sięga do 90 dnia wstecz, a faza 2 do 180 dnia wstecz. Porcje mogą przychodzić poza kolejnością, więc sortuj je według metadata.chunk_order. metadata.progress to procent całej synchronizacji, a 100 oznacza zakończenie; sam numer fazy nie mówi, że faza się skończyła.
Co, jeśli firma nie zgodzi się udostępnić czatów?
Podczas połączenia aplikacja WhatsApp Business pyta firmę, czy udostępnić historię czatów. Odmowa przychodzi jako webhook historii bez wiadomości, z tablicą errors, której code to 2593109, zatytułowaną History sync is turned off by the business from the WhatsApp Business App. Kontakty nadal przychodzą, a wiadomości na żywo płyną normalnie od chwili połączenia numeru.
Czy import można uruchomić ponownie?
Nie na tym samym połączeniu. Meta pozwala na jedną synchronizację w ciągu 24 godzin od onboardingu i nie można jej odtworzyć. Ponowne uruchomienie wymaga, by klient rozłączył numer i połączył go ponownie, co liczy się jako nowy onboarding: jeśli miejsce docelowe nadal jest zapisane, easyCoexistence ponownie prosi o import, więc deduplikuj według id każdej wiadomości. Dotyczy to także numeru wracającego po zasadzie 14 dni.
Co musi być gotowe przed wysłaniem linku do połączenia?
Twój endpoint, uruchomiony i odpowiadający. Meta sprawdza adres URL handshakiem GET przy ustawianiu miejsca docelowego, a import jest zlecany raz, zaraz po nim. Jeśli handshake się nie powiedzie, numer połączy się, ale bez miejsca docelowego, a last_error sesji wyjaśni przyczynę; nic nie zostanie zaimportowane, dopóki nie naprawisz endpointu i nie ustawisz go przez PUT /connections/{id}/webhook w ciągu 24 godzin. Numer bez webhook_url nie dostaje żadnego importu, ponieważ treści wysłane do easyCoexistence są odrzucane.
Jak to skonfigurować
- 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.
Typowe błędy
- Odrzucanie dużych porcji historii. Ładunki Meta mogą sięgać 3 MB, a Express domyślnie parsuje JSON tylko do 100 KB, więc podnieś limit, bo inaczej porcje się nie powiodą, a Meta będzie je ponawiać.
- Przetwarzanie porcji w kolejności przybycia. Mogą przychodzić poza kolejnością, więc sortuj według metadata.chunk_order i czekaj na progress 100, zanim uznasz import za zakończony.
- Wstawianie historii bez deduplikacji. Wiadomości na żywo mogą nakładać się na import, a ponowne połączenie uruchamia go jeszcze raz, więc klucz każdej wiadomości według jej id.
- Wysłanie linku do połączenia, zanim endpoint odpowie na handshake Meta. Miejsce docelowe wtedy nie zostaje zastosowane, a jeśli nie ustawisz go w ciągu 24 godzin, historia numeru nigdy nie zostanie zaimportowana.
Od US$ 9 do US$ 0.75 za połączenie miesięcznie, im więcej połączeń, tym taniej, z pierwszymi 3 dniami bezpłatnie.
Najczęściej zadawane pytania
Jak daleko wstecz sięga import historii czatów WhatsApp?
Do 180 dni przed przyłączeniem numeru do Cloud API, obejmując czaty jeden na jeden w obu kierunkach.
Czy importowane są czaty grupowe?
Nie. Meta pomija wiadomości będące częścią czatu grupowego.
Czy stare czaty WhatsApp klienta trafią do mojego webhooka?
Tak, do 180 dni czatów jeden na jeden, wysłanych raz w ciągu 24 godzin od onboardingu, jeśli firma zdecyduje w aplikacji, że je udostępnia.
Czy easyCoexistence przechowuje kopię zaimportowanych czatów?
Nie. Meta wysyła historię prosto na Twój webhook_url, tak jak wiadomości na żywo, i nic nie jest zapisywane po drodze.
Czytaj dalej
Połącz pierwszy kanał w dwie minuty.
Bez czekania na weryfikację przez platformy. Połącz WhatsApp, Instagram, TikTok lub inny kanał, a potem poproś swoją AI o opublikowanie posta, odpowiedź lub raport i zobacz, jak działa.
- 3 dni za darmo
- Rezygnacja w każdej chwili
- Tylko oficjalne API
- Monitorowanie 24/7
Zweryfikowano w