Donnez de la mémoire à votre agent IA : six mois de chats et de contacts WhatsApp
Sur un numéro connecté via Coexistence, Meta peut envoyer à votre serveur, une seule fois, les contacts de l'app et jusqu'à 180 jours de conversations individuelles, à condition qu'une destination webhook directe soit enregistrée dans les 24 heures suivant la connexion et que l'entreprise l'accepte dans l'app. Les chunks peuvent arriver dans le désordre, et une progression à 100 marque la fin. Stockez les messages par id, identifiez les personnes par BSUID et transmettez les derniers échanges à l'agent.
easyCoexistence connecte le numéro via le flux Coexistence de Meta et, lorsque vous enregistrez votre endpoint comme destination webhook directe dans les 24 heures, demande une seule fois à Meta les contacts et jusqu'à 180 jours de chats, qui arrivent directement sur votre serveur.
Profondeur de l'historique synchronisé à partir de l'onboarding ; le tableau des fonctionnalités de Meta la décrit comme les 6 derniers mois.
Délai après l'onboarding pour demander les contacts et l'historique ; chaque demande ne peut être faite qu'une fois.
Valeur de metadata.progress qui marque la synchronisation de l'historique comme terminée ; Meta indique que la phase seule ne suffit pas.
Code d'erreur dans un webhook d'historique lorsque l'entreprise a désactivé le partage de l'historique dans l'app WhatsApp Business.
La phase 0 couvre le jour 0 à 1 avant l'onboarding, la phase 1 les jours 1 à 90, la phase 2 les jours 90 à 180.
Plus gros payload webhook envoyé par Meta, qui fixe la limite de taille du corps que votre endpoint doit accepter.
Que ramène l'import, et que reste-t-il en arrière ?
Deux flux, tous deux issus de l'app WhatsApp Business sur le téléphone. Les contacts arrivent sous forme de webhooks smb_app_state_sync, une entrée par contact avec l'action add ou remove ; le même champ signale aussi les contacts que l'entreprise ajoute, modifie ou supprime ensuite dans l'app. Les conversations arrivent sous forme de webhooks history : les échanges individuels jusqu'à 180 jours avant l'onboarding, dans les deux sens, avec leur statut de remise. Ce qui n'est pas transmis est listé plus bas, la mémoire construite sur l'import ne doit donc pas s'attendre à le trouver.
Comment s'assurer que l'import atteint votre serveur ?
Mettez l'endpoint en ligne avant la connexion du numéro, puis enregistrez-le comme destination webhook directe dans les 24 heures suivant la connexion : sur la page du numéro, sous Router les messages entrants vers votre propre webhook, avec set_webhook_destination depuis votre IA, ou en webhook_url sur une session de connexion Partner API. Cet enregistrement conduit easyCoexistence à demander à Meta la synchronisation, d'abord les contacts puis l'historique, une seule fois par onboarding ; la demande et les identifiants de requête de Meta apparaissent dans le journal d'événements du numéro sous history_sync_requested.
L'entreprise doit accepter le partage de l'historique lorsque l'app le demande pendant la connexion. Un numéro dont les messages passent par easyCoexistence (Via easyCoexistence dans la carte Où vont les messages entrants), même avec une Forward URL, ne reçoit aucun import, car la demande n'est faite que pour une destination directe. Si vous avez besoin des automatisations plus tard, passez-y une fois l'import terminé.
Comment arrivent les chunks de l'historique ?
Dans le désordre, par phases qui remontent depuis les messages les plus récents : la phase 0 couvre le dernier jour avant l'onboarding, la phase 1 jusqu'au jour 90 et la phase 2 jusqu'au jour 180. Triez par metadata.chunk_order si l'ordre compte, et considérez metadata.progress = 100 comme la fin, car Meta précise que la phase ne signale pas qu'une phase est terminée. L'id d'une conversation est le numéro de téléphone du client, omis lorsqu'il ne peut pas être partagé, et son contexte contient wa_id, user_id et username. Un message envoyé par l'entreprise a from défini sur le numéro de l'entreprise et un champ to.
{
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "16315550142", "phone_number_id": "106540352242922" },
"history": [{
"metadata": { "phase": 1, "chunk_order": 2, "progress": 55 },
"threads": [{
"id": "5511987654321",
"context": { "wa_id": "5511987654321", "user_id": "BR.13491208655302741918" },
"messages": [
{
"from": "5511987654321",
"from_user_id": "BR.13491208655302741918",
"id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFDNBMDhFN0QxRjM2QTk4RTU2RTY0AA==",
"timestamp": "1789912800",
"type": "text",
"text": { "body": "Can I pick up the cake on Saturday?" },
"history_context": { "status": "read" }
},
{
"from": "16315550142",
"to": "5511987654321",
"id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABEYEjQ2RDhGMkE3QjEwQzNFOTFBMgA=",
"timestamp": "1789913100",
"type": "text",
"text": { "body": "Yes, from 9 am. See you then!" },
"history_context": { "status": "read" }
}
]
}]
}]
}Comment stocker la mémoire d'un agent ?
Deux tables suffisent. Les personnes sont identifiées par BSUID, le user_id que Meta ajoute aux contacts, conversations et messages, avec le numéro de téléphone conservé à côté, car un utilisateur ayant un username peut arriver sans numéro ; la référence de Meta indique d'utiliser user_id pour identifier un contact. Les messages sont identifiés par leur wamid, si bien que l'import, les webhooks en direct et les livraisons réessayées d'un même message se réduisent à une seule ligne, et un indicateur from_business enregistre qui a parlé. Indexez par personne et par date, car l'agent demande les derniers échanges d'une personne.
-- One row per person. Key on the BSUID (user_id); keep the phone number beside it.
create table wa_contacts (
user_key text primary key, -- user_id (BSUID) when present, else the phone number
wa_id text, -- phone number in digits, when Meta shares it
username text,
name text, -- full_name from the app's address book
removed boolean not null default false,
updated_at timestamptz not null default now()
);
-- One row per message. The wamid makes history, live events and retries collapse.
create table wa_messages (
id text primary key, -- messages[].id
user_key text not null,
from_business boolean not null,
type text not null, -- text, image, media_placeholder...
body text not null, -- the text, a caption, or a [type] placeholder
sent_at timestamptz not null,
source text not null -- history | live | echo
);
create index wa_messages_by_user on wa_messages (user_key, sent_at desc);Comment charger les chunks et les contacts dans cette mémoire ?
Avec des insertions idempotentes, pour que l'ordre et les redélivrances n'aient plus d'importance. ingestHistory lit une modification d'historique : il consigne un refus 2593109 et passe à la suite, indexe une conversation par context.user_id ou son id, marque un message comme celui de l'entreprise lorsque from est égal à metadata.display_phone_number, et stocke un marqueur [type] lorsqu'il n'y a pas de texte. ingestContacts procède à un upsert sur user_id ou le numéro de téléphone et signale les contacts supprimés au lieu d'effacer leurs messages. Appelez-les avec change.value sur une destination directe, ou avec la valeur du corps lorsque l'événement d'un transfert est history ou smb_app_state_sync.
// memory.mjs: npm i pg. Feed it the value of a "history" or "smb_app_state_sync"
// change: change.value on a direct destination, delivery.value on a forward.
import pg from "pg";
const db = new pg.Pool(); // reads the PG* environment variables
export async function ingestHistory(value) {
const business = value.metadata?.display_phone_number; // digits, like messages[].from
for (const chunk of value.history ?? []) {
if (chunk.errors?.some((e) => e.code === 2593109)) {
console.log("The business turned off history sharing in the app"); // contacts still come
continue;
}
for (const thread of chunk.threads ?? []) {
const userKey = thread.context?.user_id ?? thread.id; // thread.id is the phone, when shared
for (const m of thread.messages ?? []) {
await db.query(
`insert into wa_messages (id, user_key, from_business, type, body, sent_at, source)
values ($1, $2, $3, $4, $5, to_timestamp($6), 'history')
on conflict (id) do nothing`,
[m.id, userKey, m.from === business, m.type,
m.text?.body ?? m[m.type]?.caption ?? `[${m.type}]`, Number(m.timestamp)]
);
}
}
const { phase, chunk_order, progress } = chunk.metadata ?? {};
console.log(`history: phase ${phase}, chunk ${chunk_order}, ${progress}%`);
if (Number(progress) === 100) console.log("Import complete; late chunks still insert safely");
}
}
export async function ingestContacts(value) {
for (const s of value.state_sync ?? []) {
const c = s.type === "contact" ? s.contact ?? {} : null;
const userKey = c && (c.user_id ?? c.phone_number);
if (!userKey) continue;
await db.query(
`insert into wa_contacts (user_key, wa_id, username, name, removed)
values ($1, $2, $3, $4, $5)
on conflict (user_key) do update set
wa_id = coalesce(excluded.wa_id, wa_contacts.wa_id),
username = coalesce(excluded.username, wa_contacts.username),
name = coalesce(excluded.name, wa_contacts.name),
removed = excluded.removed, updated_at = now()`,
[userKey, c.phone_number ?? null, c.username ?? null, c.full_name ?? c.first_name ?? null,
s.action === "remove"]
);
}
}
// A bounded memory for one person: who they are and their last turns, oldest first.
export async function memoryFor(userKey, turns = 20) {
const [{ rows: [contact] }, { rows }] = await Promise.all([
db.query("select name from wa_contacts where user_key = $1 and not removed", [userKey]),
db.query(
`select from_business, body from wa_messages
where user_key = $1 order by sent_at desc limit $2`, [userKey, turns]),
]);
const history = rows.reverse().map((r) => ({ role: r.from_business ? "assistant" : "user", content: r.body }));
while (history[0]?.role === "assistant") history.shift(); // open on the customer's turn
const who = contact?.name ? `The customer is ${contact.name}.` : "The customer is not in the address book.";
return { system: `${process.env.AI_INSTRUCTIONS ?? ""}\n${who}`.trim(), history };
}Comment alimenter l'agent avec cette mémoire ?
Toujours de façon bornée, jamais en bloc. memoryFor renvoie le nom de la personne issu du carnet d'adresses et ses 20 derniers échanges, du plus ancien au plus récent, en commençant par un message client comme l'attendent la plupart des API de chat ; ajoutez un résumé stocké des conversations plus anciennes si l'agent en a besoin. Six mois de chats dans chaque prompt coûtent des tokens à chaque réponse et noient la question posée.
À titre de comparaison, l'étape intégrée Répondre avec l'IA lit au plus 20 messages antérieurs (10 par défaut), et l'étape Appeler mon webhook envoie les 10 derniers. Les deux utilisent un texte conservé pendant la durée de rétention choisie par le propriétaire, 30, 90 ou 365 jours (90 par défaut), à partir du moment où les automatisations ont été activées, ce qui oblige à conserver les six mois de chats importés dans votre propre base de données.
Comment la mémoire reste-t-elle à jour après l'import ?
La même destination continue de recevoir le trafic en direct : les messages des clients, smb_message_echoes pour les réponses saisies dans l'app, et smb_app_state_sync lorsque l'entreprise modifie ses contacts. Insérez-les dans les mêmes tables avec source live ou echo. Lorsqu'un client change de numéro de téléphone, Meta envoie un message système de type user_changed_number ou user_changed_user_id avec previous_user_id, un signal pour déplacer ses lignes vers le nouveau BSUID.
Activer les automatisations plus tard supprime la destination directe. Ajoutez la même URL comme Forward URL, lisez event et value à partir de chaque POST signé, et attendez progress 100 avant de basculer, faute de quoi les chunks restants ne vous parviendront que par ce transfert.
Comment le configurer
- Put the endpoint onlineIt must return hub.challenge as plain text on Meta's GET handshake when hub.verify_token matches, accept POST bodies of a few megabytes and answer 200 fast.
- Connect the numberRun the connection from the dashboard, and accept sharing chat history when the WhatsApp Business app asks.
- Save the destination within 24 hoursOn the number's page, under Route incoming messages to your own webhook, fill Webhook URL (with a long random path) and Verify token, then Save; or ask your AI to call set_webhook_destination.
- Store chunks until progress 100Insert contacts and messages as they come; the event log shows history_sync_requested once the request went to Meta.
- Switch modes only afterwardsIf you want automations, choose Through easyCoexistence in the card Where incoming messages go and add the same URL as the Forward URL.
Erreurs courantes
- Enregistrer la destination le deuxième jour. La synchronisation n'est demandée que dans les 24 heures suivant la connexion ; un endpoint enregistré plus tard ne reçoit donc que les messages en direct.
- Activer les automatisations avant que la progression atteigne 100. La destination directe est supprimée immédiatement, et les chunks suivants ne vous parviennent que si une Forward URL est déjà définie.
- Considérer la phase 2 comme la fin de l'import. Seul metadata.progress = 100 indique que la synchronisation est terminée, et les chunks ne sont pas livrés dans l'ordre.
- Indexer la mémoire sur le seul numéro de téléphone. Les ids de conversation et les contacts perdent le numéro lorsqu'un utilisateur ayant un username ne peut pas le partager, alors que user_id reste présent.
La demande est consignée dans le journal d'événements du numéro, et le numéro est surveillé 24h/24, 7j/7 ensuite. De US$ 9 à US$ 0,75 par numéro connecté et par mois, dégressif à mesure que vous ajoutez des numéros, avec les 3 premiers jours d'essai gratuit.
Questions fréquemment posées
L'import peut-il tourner une deuxième fois ?
Seulement lors d'un nouvel onboarding. Meta n'autorise qu'une demande par onboarding : il faut donc déconnecter puis reconnecter le numéro, et les conversations arrivent alors à nouveau. L'insertion par id de message empêche la seconde passe d'ajouter quoi que ce soit en double.
easyCoexistence conserve-t-il une copie des chats importés ?
Non. L'historique et les contacts vont directement de Meta vers votre endpoint et ne sont pas stockés par défaut. Pour un numéro dont les automatisations sont activées, easyCoexistence conserve le texte des messages pendant la durée que vous choisissez, 30, 90 ou 365 jours (90 par défaut), et l'écran Conversations l'affiche ; les envois transférés sont conservés jusqu'à 7 jours, et les journaux d'exécution 30 jours.
Quelle peut être la taille des payloads ?
Un seul webhook Meta peut atteindre 3 MB, et un numéro très actif envoie de nombreux chunks d'historique. Augmentez la limite de corps de votre framework (Express est à 100 kb par défaut) et répondez avant d'écrire dans la base de données.
Un agent a-t-il besoin de l'import pour fonctionner ?
Non. Sans lui, la mémoire commence avec le premier message après la connexion et grandit avec le trafic en direct. L'import compte lorsque les conversations passées doivent influencer les réponses dès le premier jour, par exemple la dernière commande d'un client qui revient.
Poursuivre la lecture
Prêt à commencer ?
Configurez WhatsApp Coexistence en quelques minutes, pas en quelques mois. L’application continue de fonctionner sur le téléphone.
Commencer l'essai gratuitVérifié le