Conectați-văÎncepeți perioada de probă gratuită
easyCoexistence API-uri oficiale

Cum importați istoricul conversațiilor și contactele din aplicația WhatsApp Business prin API

Un număr WhatsApp Business conectat prin Coexistence poate trimite către API, o singură dată și în 24 de ore de la onboarding, contactele existente și conversațiile one-to-one din ultimele 180 de zile. Contactele sosesc prin webhook-urile smb_app_state_sync, iar conversațiile prin webhook-urile history, în fragmente ordonate după metadata.chunk_order; metadata.progress egal cu 100 marchează importul ca finalizat. Firma decide în aplicație dacă împărtășește conversațiile.

easyCoexistence conectează numerele WhatsApp Business ale clienților dumneavoastră prin Coexistence și cere de la Meta contactele și istoricul conversațiilor în momentul în care webhook-ul dumneavoastră este pregătit, astfel încât istoricul ajunge direct la endpoint-ul dumneavoastră, fără să fie stocat pe drum, iar fiecare număr beneficiază de monitorizare 24/7.

180 days

Până în ce moment în trecut ajung webhook-urile de istoric, numărat de la integrarea firmei în Cloud API.

24 hours

Intervalul după onboarding în care trebuie sincronizate contactele și istoricul mesajelor firmei.

2593109

Codul de eroare din webhook-ul de istoric atunci când firma a dezactivat partajarea istoricului în aplicația WhatsApp Business.

Once

Cât de des poate rula fiecare sincronizare; repetarea ei necesită ca397 clientul să facă offboarding și să finalizeze din nou Embedded Signup.

100

Valoarea progresului care marchează finalizarea unei sincronizări a istoricului.

Cum începe importul?

Cu o destinație webhook setată pentru număr. Când numărul se conectează cu webhook_url deja setat în sesiunea de conectare sau când setați una cu PUT /connections/{id}/webhook în 24 de ore de la conectare, easyCoexistence cere datele de la Meta o singură dată: POST /{phone_number_id}/smb_app_data cu sync_type smb_app_state_sync pentru contacte, apoi history pentru conversații, în ordinea documentată de Meta. Jurnalul de evenimente al numărului înregistrează history_sync_requested, cu valorile request_id furnizate de Meta pentru suport, sau history_sync_failed, cu motivul.

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

Ce transportă webhook-urile pentru contacte?

Câmpul smb_app_state_sync, cu un array state_sync în value. Fiecare element are type contact; un obiect contact cu full_name, first_name și phone_number; o acțiune add sau remove; și metadata.timestamp. Numele sunt omise la remove. Meta continuă să trimită aceste webhook-uri și după import, ori de câte ori firma adaugă, editează sau șterge un contact în aplicația WhatsApp Business, astfel încât agenda dumneavoastră rămâne sincronizată cu telefonul.

Ce transportă webhook-urile de istoric?

Câmpul history, cu un array history în value. Fiecare element conține metadata, cu phase, chunk_order și progress, și threads, câte unul pentru fiecare client: id-ul thread-ului este numărul clientului, iar messages listează conversația one-to-one respectivă, primite și trimise, câmpul from indicând ce parte a trimis fiecare mesaj. Un mesaj conține id, timestamp, type, conținutul sub numele tipului și history_context.status, de exemplu READ sau DELIVERED. Conversațiile de grup nu sunt incluse.

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

Cum sunt importate mesajele media?

Mai întâi ca substituenți. Un mesaj media vine cu type media_placeholder, fără conținut și fără ID-ul media. Apoi Meta trimite webhook-uri de istoric separate, cu ID-urile media, dar doar pentru conținutul trimis în 14 zile de la onboarding; descărcați aceste fișiere de la Meta cu token-ul clientului. Media mai veche de atât rămâne substituent, așa că afișați-o ca atașament indisponibil, nu lăsați un gol în firul conversației.

În ce ordine sosesc fragmentele și când se încheie importul?

Nu neapărat în ordine. Meta împarte conversațiile în trei faze, de la cele mai noi: faza 0 este ziua dinaintea onboarding-ului, faza 1 ajunge până la ziua 90, iar faza 2 până la ziua 180. Fragmentele pot sosi nesecvențial, așa că sortați-le după metadata.chunk_order. metadata.progress este procentul din întreaga sincronizare, iar 100 înseamnă finalizat; numărul fazei singur nu indică faptul că o fază s-a încheiat.

Ce se întâmplă dacă firma refuză să împărtășească conversațiile?

În timpul conectării, aplicația WhatsApp Business o întreabă pe firmă dacă să împărtășească istoricul conversațiilor. Refuzul sosește ca un webhook de istoric fără mesaje și cu un array errors al cărui cod este 2593109, cu titlul History sync is turned off by the business from the WhatsApp Business App. Contactele sosesc în continuare, iar mesajele noi curg normal din momentul în care numărul s-a conectat.

Poate importul să ruleze din nou?

Nu pe aceeași conexiune. Meta permite fiecărei sincronizări o singură rulare, în 24 de ore de la onboarding, și nu poate fi reluată. Pentru a o rula din nou, clientul trebuie să deconecteze numărul și să-l conecteze din nou, ceea ce înseamnă un nou onboarding: cu destinația dumneavoastră încă salvată, easyCoexistence cere din nou importul, așa că deduplicați după id-ul fiecărui mesaj. Asta include și cazul unui număr care revine după regula celor 14 zile.

Ce trebuie să fie pregătit înainte să trimiteți linkul de conectare?

Endpoint-ul dumneavoastră, pornit și care răspunde. Meta verifică URL-ul prin handshake-ul GET la aplicarea destinației, iar importul este cerut o singură dată, imediat după. Dacă handshake-ul eșuează, numărul se conectează în continuare, dar fără destinație; last_error din sesiune explică motivul, iar nimic nu este importat decât dacă reparați endpoint-ul și îl setați cu PUT /connections/{id}/webhook în cele 24 de ore. Un număr fără webhook_url nu primește deloc import, pentru că343 conținutul trimis către easyCoexistence este eliminat.

Cum să îl configurați

  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.

Greșeli frecvente

  • Respingerea fragmentelor mari de istoric. Payload-urile Meta pot ajunge la 3 MB, iar Express parsează JSON-ul implicit doar până la 100 KB, așa că măriți limita, altfel fragmentele eșuează și Meta continuă să le retrimită.
  • Procesarea fragmentelor în ordinea sosirii. Ele pot sosi nesecvențial, așa că sortați după metadata.chunk_order și așteptați progress 100 înainte să considerați importul finalizat.
  • Inserarea istoricului fără deduplicare. Mesajele live se pot suprapune cu importul, iar o reconectare îl rulează din nou, așa că identificați fiecare mesaj după id.
  • Trimiterea linkului de conectare înainte ca endpoint-ul să răspundă handshake-ului Meta. Destinația nu se aplică atunci, iar dacă nu o setați în 24 de ore, istoricul numărului nu este importat niciodată.
Faceți acest lucru cu EasyCoexistence

De la US$ 9 până la US$ 0,75 per conexiune pe lună, scăzând pe măsură ce adăugați conexiuni, cu o perioadă de probă gratuită de 3 zile.

Întrebări frecvente

Cât de în urmă merge importul istoricului conversațiilor WhatsApp?

Până la 180 de zile înainte ca numărul să fi fost integrat în Cloud API, acoperind conversațiile one-to-one în ambele direcții.

Se importă conversațiile de grup?

Nu. Meta lasă deoparte mesajele care fac parte dintr-o conversație de grup.

Ajung vechile conversații WhatsApp ale unui client la webhook-ul meu?

Da, până la 180 de zile de conversații one-to-one, trimise o singură dată în 24 de ore de la onboarding, dacă firma alege în aplicație să le împărtășească.

Păstrează easyCoexistence o copie a conversațiilor importate?

Nu. Meta trimite istoricul direct la destinația webhook_url setată, la fel ca mesajele live, iar nimic nu este stocat pe drum.

Continuați să citiți

Conectați primul canal în două minute.

Fără recenzii de platformă de așteptat. Conectați WhatsApp, Instagram, TikTok sau alt canal, apoi cereți AI-ului să publice, să răspundă sau să raporteze și urmăriți-l cum lucrează.

  • 3 zile gratuit
  • Anulați oricând
  • Doar API-uri oficiale
  • Monitorizat 24/7

Verificat la