Come importare la cronologia chat e i contatti dell'app WhatsApp Business tramite API
Un numero dell'app WhatsApp Business collegato tramite Coexistence può inviare all'API, una sola volta e entro 24 ore dall'onboarding, i contatti esistenti e fino a 180 giorni di chat uno a uno. I contatti arrivano come webhook smb_app_state_sync, le chat come webhook history, in blocchi ordinati per metadata.chunk_order; metadata.progress pari a 100 segna l'importazione come completata. È l'azienda a scegliere, nell'app, se condividere le chat.
easyCoexistence collega i numeri WhatsApp Business app dei tuoi clienti tramite Coexistence e chiede a Meta i loro contatti e la cronologia delle chat non appena il tuo webhook è attivo, così la cronologia arriva direttamente al tuo endpoint senza essere memorizzata lungo il percorso, con ogni numero monitorato 24/7.
Fino a che punto indietro arrivano i webhook della cronologia, calcolato dall'onboarding sulla Cloud API.
Tempo dopo l'onboarding entro cui i contatti e la cronologia dei messaggi di un'azienda devono essere sincronizzati.
Codice di errore del webhook della cronologia quando l'azienda ha disattivato la condivisione della cronologia nell'app WhatsApp Business.
Frequenza massima di ogni sincronizzazione; ripeterla richiede che il cliente effettui l'offboarding e completi di nuovo Embedded Signup.
Il valore di progresso che segna il completamento di una sincronizzazione della cronologia.
Come inizia l'importazione?
Con una destinazione webhook sul numero. Quando il numero si connette con webhook_url già impostato nella sessione di connessione, oppure quando la imposti con PUT /connections/{id}/webhook entro 24 ore dalla connessione, easyCoexistence chiede a Meta i dati una sola volta: POST /{phone_number_id}/smb_app_data con sync_type smb_app_state_sync per i contatti, poi history per le chat, nell'ordine documentato da Meta. Il registro eventi del numero registra history_sync_requested con i valori request_id di Meta per l'assistenza, oppure history_sync_failed con il motivo.
Cosa contengono i webhook dei contatti?
Campo smb_app_state_sync, con un array state_sync nel valore. Ogni elemento ha type contact; un oggetto contact con full_name, first_name e phone_number; un'azione add o remove; e metadata.timestamp. I nomi vengono omessi nelle rimozioni. Meta continua a inviare questi webhook dopo l'importazione ogni volta che l'azienda aggiunge, modifica o rimuove un contatto nell'app WhatsApp Business, così la tua rubrica resta allineata con il telefono.
Cosa contengono i webhook della cronologia?
Campo history, con un array history nel valore. Ogni elemento contiene metadata, con phase, chunk_order e progress, e threads, uno per cliente: l'id del thread è il numero del cliente, e messages elenca quella conversazione uno a uno, in entrata e in uscita, con from che indica quale parte ha inviato ogni messaggio. Un messaggio contiene id, timestamp, type, il suo contenuto sotto il nome del tipo e history_context.status, come READ o DELIVERED. Le chat di gruppo non sono incluse.
{
"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" }
}
]
}
]
}
]
}
}
]
}
]
}Come vengono importati i messaggi multimediali?
Inizialmente come segnaposto. Un messaggio multimediale arriva con type media_placeholder, senza contenuto e senza ID del media. Meta invia poi webhook della cronologia separati con gli ID dei media, ma solo per i contenuti inviati entro 14 giorni dall'onboarding; scarica quei file da Meta con il token del cliente. I media più vecchi restano segnaposto, quindi mostrali come allegato non disponibile invece di lasciare un vuoto nella conversazione.
In quale ordine arrivano i blocchi e quando l'importazione è completata?
Non necessariamente in ordine. Meta divide le chat in tre fasi, dalla più recente: la fase 0 è il giorno precedente l'onboarding, la fase 1 risale fino al giorno 90 e la fase 2 fino al giorno 180. I blocchi possono arrivare fuori sequenza, quindi ordinali per metadata.chunk_order. metadata.progress è la percentuale dell'intera sincronizzazione, e 100 significa completata; il numero di fase da solo non indica che una fase è terminata.
Cosa succede se l'azienda rifiuta di condividere le chat?
Durante la connessione, l'app WhatsApp Business chiede all'azienda se condividere la propria cronologia delle chat. Il rifiuto arriva come webhook della cronologia senza messaggi e con un array errors il cui codice è 2593109, con titolo History sync is turned off by the business from the WhatsApp Business App. I contatti arrivano comunque, e i messaggi in tempo reale fluiscono normalmente dal momento in cui il numero si è connesso.
L'importazione può essere eseguita di nuovo?
Non sulla stessa connessione. Meta consente ogni sincronizzazione una sola volta, entro 24 ore dall'onboarding, e non può essere riprodotta. Per rifarla il cliente deve disconnettere il numero e collegarlo di nuovo, il che conta come un nuovo onboarding: con la tua destinazione ancora salvata, easyCoexistence richiede di nuovo l'importazione, quindi deduplica su id di ciascun messaggio. Vale anche per un numero che torna dopo la regola dei 14 giorni.
Cosa deve essere pronto prima di inviare il link di connessione?
Il tuo endpoint, attivo e che risponde. Meta verifica l'URL con il suo handshake GET quando la destinazione viene applicata, e l'importazione viene richiesta una sola volta, subito dopo. Se l'handshake fallisce, il numero si connette comunque ma senza destinazione, il last_error della sessione spiega il motivo e non viene importato nulla finché non correggi l'endpoint e lo imposti con PUT /connections/{id}/webhook entro 24 ore. Un numero senza webhook_url non riceve alcuna importazione, perché i contenuti inviati a easyCoexistence vengono scartati.
Come configurarlo
- 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.
Errori comuni
- Rifiutare blocchi di cronologia grandi. I payload di Meta possono raggiungere 3 MB, mentre Express analizza il JSON fino a 100 KB per impostazione predefinita, quindi aumenta il limite o i blocchi falliscono e Meta continua a riprovarli.
- Elaborare i blocchi nell'ordine di arrivo. Possono arrivare fuori sequenza, quindi ordina per metadata.chunk_order e attendi progress 100 prima di considerare completata l'importazione.
- Inserire la cronologia senza deduplicare. I messaggi in tempo reale possono sovrapporsi all'importazione e una riconnessione la esegue di nuovo, quindi usa l'id di ogni messaggio come chiave.
- Inviare il link di connessione prima che l'endpoint risponda all'handshake di Meta. La destinazione non viene quindi applicata e, se non la imposti entro 24 ore, la cronologia del numero non viene mai importata.
Da US$ 9 a US$ 0,75 per connessione al mese, con prezzo che scende man mano che aggiungi connessioni, e con i primi 3 giorni di prova gratuita.
Domande frequenti
Fino a quanto indietro arriva l'importazione della cronologia chat di WhatsApp?
Fino a 180 giorni prima dell'onboarding del numero sulla Cloud API, includendo le chat uno a uno in entrambe le direzioni.
Vengono importate le chat di gruppo?
No. Meta esclude i messaggi che fanno parte di una chat di gruppo.
Le vecchie chat WhatsApp del cliente arriveranno al mio webhook?
Sì, fino a 180 giorni di chat uno a uno, inviate una sola volta entro 24 ore dall'onboarding, se l'azienda sceglie nell'app di condividerle.
easyCoexistence conserva una copia delle chat importate?
No. Meta invia la cronologia direttamente al tuo webhook_url, come i messaggi in tempo reale, e nulla viene memorizzato lungo il percorso.
Continua a leggere
Collega il tuo primo canale in due minuti.
Nessuna revisione delle piattaforme da aspettare. Collega WhatsApp, Instagram, TikTok o un altro canale, poi chiedi alla tua AI di pubblicare, rispondere o fare un report, e guardala al lavoro.
- 3 giorni gratis
- Disdici quando vuoi
- Solo API ufficiali
- Monitorato 24/7
Verificato il