Comment importer l'historique des conversations et les contacts de l'app WhatsApp Business via l'API
Un numéro WhatsApp Business app connecté via Coexistence peut envoyer une seule fois ses contacts existants et jusqu'à 180 jours de conversations individuelles à l'API, dans les 24 heures suivant l'onboarding. Les contacts arrivent sous forme de webhooks smb_app_state_sync et les conversations sous forme de webhooks history, par blocs ordonnés selon metadata.chunk_order ; metadata.progress à 100 marque la fin de l'import. L'entreprise choisit dans l'application si elle partage ses conversations.
easyCoexistence connecte les numéros WhatsApp Business app de vos clients via Coexistence et demande à Meta leurs contacts et leur historique de conversations dès que votre webhook est en place.
Durée couverte par les webhooks history, comptée à partir de l'onboarding de l'entreprise sur la Cloud API.
Délai après l'onboarding pendant lequel les contacts et l'historique des messages d'une entreprise doivent être synchronisés.
Code d'erreur du webhook history lorsque l'entreprise a désactivé le partage de l'historique dans l'application WhatsApp Business.
Fréquence maximale de chaque synchronisation ; la relancer exige que le client se désabonne puis refasse l'Embedded Signup.
Valeur de progress qui marque la synchronisation de l'historique comme terminée.
Comment démarre l'import ?
Avec une destination webhook configurée sur le numéro. Lorsque le numéro se connecte avec webhook_url déjà renseigné dans la session de connexion, ou lorsque vous la définissez avec PUT /connections/{id}/webhook dans les 24 heures suivant la connexion, easyCoexistence demande une seule fois les données à Meta : POST /{phone_number_id}/smb_app_data avec sync_type smb_app_state_sync pour les contacts, puis history pour les conversations, dans l'ordre documenté par Meta. Le journal d'événements du numéro enregistre history_sync_requested avec les valeurs request_id de Meta pour le support, ou history_sync_failed avec la raison.
Que contiennent les webhooks de contacts ?
Champ smb_app_state_sync, avec un tableau state_sync dans value. Chaque élément a pour type contact ; un objet contact avec full_name, first_name et phone_number ; une action add ou remove ; et metadata.timestamp. Les noms sont omis en cas de remove. Meta continue d'envoyer ces webhooks après l'import chaque fois que l'entreprise ajoute, modifie ou supprime un contact dans l'application WhatsApp Business, afin que votre carnet d'adresses reste synchronisé avec le téléphone.
Que contiennent les webhooks history ?
Champ history, avec un tableau history dans value. Chaque élément contient metadata, avec phase, chunk_order et progress, et threads, un par client : l'id du fil est le numéro du client, et messages liste cette conversation individuelle, entrantes et sortantes, from indiquant quel côté a envoyé chaque message. Un message comporte id, timestamp, type, son contenu sous le nom du type, et history_context.status, comme READ ou DELIVERED. Les conversations de groupe ne sont pas incluses.
{
"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" }
}
]
}
]
}
]
}
}
]
}
]
}Comment les médias sont-ils importés ?
D'abord sous forme de placeholders. Un message média arrive avec type media_placeholder, sans content ni ID de média. Meta envoie ensuite des webhooks history distincts portant les ID de média, mais uniquement pour les médias envoyés dans les 14 jours suivant l'onboarding ; récupérez ces fichiers auprès de Meta avec le token du client. Un média plus ancien reste un placeholder : affichez-le comme une pièce jointe non disponible plutôt que de laisser un trou dans le fil.
Dans quel ordre arrivent les blocs, et quand l'import est-il terminé ?
Pas nécessairement dans l'ordre. Meta répartit les conversations en trois phases, de la plus récente à la plus ancienne : la phase 0 couvre la veille de l'onboarding, la phase 1 remonte jusqu'au jour 90 et la phase 2 jusqu'au jour 180. Les blocs peuvent arriver dans le désordre : triez-les par metadata.chunk_order. metadata.progress est le pourcentage de la synchronisation complète, et 100 signifie qu'elle est terminée ; le numéro de phase seul ne permet pas de savoir qu'une phase est achevée.
Que se passe-t-il si l'entreprise refuse de partager ses conversations ?
Pendant la connexion, l'application WhatsApp Business demande à l'entreprise si elle souhaite partager son historique de conversations. Un refus arrive sous forme de webhook history sans messages, avec un tableau errors dont le code est 2593109, intitulé History sync is turned off by the business from the WhatsApp Business App. Les contacts arrivent tout de même, et les messages en direct circulent normalement dès que le numéro est connecté.
L'import peut-il être relancé ?
Pas sur la même connexion. Meta autorise chaque synchronisation une seule fois, dans les 24 heures suivant l'onboarding, et elle ne peut pas être rejouée. La relancer exige que le client déconnecte le numéro puis le reconnecte, ce qui compte comme un nouvel onboarding : si votre destination est toujours enregistrée, easyCoexistence redemande l'import. Dédupliquez donc sur l'id de chaque message. Cela vaut aussi pour un numéro qui revient après la règle des 14 jours.
Qu'est-ce qui doit être prêt avant d'envoyer le lien de connexion ?
Votre endpoint, en ligne et qui répond. Meta vérifie l'URL par son handshake GET lorsque la destination est appliquée, et l'import est demandé une seule fois, juste après. Si le handshake échoue, le numéro se connecte quand même mais sans destination, le last_error de la session explique pourquoi, et rien n'est importé tant que vous ne corrigez pas l'endpoint et ne le définissez pas avec PUT /connections/{id}/webhook dans les 24 heures. Un numéro sans webhook_url ne reçoit aucun import, car le contenu envoyé à easyCoexistence est supprimé.
Comment le configurer
- 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.
Erreurs courantes
- Rejeter les gros blocs d'historique. Les payloads de Meta peuvent atteindre 3 Mo, alors qu'Express ne parse le JSON que jusqu'à 100 Ko par défaut : augmentez la limite, sinon les blocs échouent et Meta continue de les renvoyer.
- Traiter les blocs dans l'ordre d'arrivée. Ils peuvent arriver dans le désordre : triez-les par metadata.chunk_order et attendez progress 100 avant de déclarer l'import terminé.
- Insérer l'historique sans dédupliquer. Les messages en direct peuvent chevaucher l'import, et une reconnexion le relance : indexez chaque message sur son id.
- Envoyer le lien de connexion avant que l'endpoint ne réponde au handshake de Meta. La destination n'est alors pas appliquée, et si vous ne la définissez pas dans les 24 heures, l'historique du numéro n'est jamais importé.
L'historique part directement vers votre endpoint, sans être stocké en transit, et chaque numéro est surveillé 24/7. De US$ 9 à US$ 0,75 par connexion et par mois, dégressif à mesure que vous ajoutez des connexions, avec un essai gratuit de 3 jours.
Questions fréquemment posées
Jusqu'à quelle date remonte l'import de l'historique WhatsApp ?
Jusqu'à 180 jours avant que le numéro ne soit onboardé sur la Cloud API, couvrant les conversations individuelles dans les deux sens.
Les conversations de groupe sont-elles importées ?
Non. Meta exclut les messages faisant partie d'une conversation de groupe.
Les anciennes conversations WhatsApp d'un client arriveront-elles sur mon webhook ?
Oui, jusqu'à 180 jours de conversations individuelles, envoyées une seule fois dans les 24 heures suivant l'onboarding, si l'entreprise choisit dans l'application de les partager.
easyCoexistence conserve-t-il une copie des conversations importées ?
Non. Meta envoie l'historique directement à votre webhook_url, comme les messages en direct, et rien n'est stocké en transit.
Poursuivre la lecture
Connectez votre premier canal en deux minutes.
Aucune validation de plateforme à attendre. Connectez WhatsApp, Instagram, TikTok ou un autre canal, puis demandez à votre IA de publier, de répondre ou de faire un rapport, et regardez-la travailler.
- 3 jours gratuits
- Résiliable à tout moment
- API officielles uniquement
- Supervisé 24/7
Vérifié le