InloggenGratis proefperiode starten
Meta Tech Provider

Geef je AI-agent geheugen: zes maanden WhatsApp-chats en contacten

Bij een nummer dat via Coexistence is verbonden, kan Meta eenmalig de contacten uit de app en tot 180 dagen aan één-op-één-chats naar je server sturen, mits binnen 24 uur na het verbinden een directe webhook-bestemming is opgeslagen en het bedrijf in de app toestemming geeft. Chunks kunnen in willekeurige volgorde aankomen en voortgang 100 markeert het einde. Sla berichten op per id, koppel personen aan hun BSUID en geef de recente gespreksbeurten aan de agent.

easyCoexistence verbindt het nummer via de Coexistence-flow van Meta en vraagt Meta, wanneer je je endpoint binnen 24 uur als directe webhook-bestemming opslaat, eenmalig om de contacten en tot 180 dagen chats, die rechtstreeks naar je server gaan.

180 days

Hoe ver de geschiedenissynchronisatie terugreikt vanaf onboarding; de functietabel van Meta noemt de meest recente 6 maanden.

24 hours

Tijd na onboarding om contacten en geschiedenis op te vragen; elk verzoek kan maar één keer worden gedaan.

100

De metadata.progress-waarde die de geschiedenissynchronisatie als voltooid markeert; Meta zegt dat de fase alleen niet genoeg is.

2593109

Foutcode in een history-webhook wanneer het bedrijf het delen van geschiedenis heeft uitgeschakeld in de WhatsApp Business-app.

3 phases

Fase 0 loopt van dag 0 tot 1 vóór onboarding, fase 1 van dag 1 tot 90, fase 2 van dag 90 tot 180.

3 MB

De grootste webhook-payload die Meta verstuurt; die bepaalt de limiet voor de body-grootte die je endpoint nodig heeft.

Wat brengt de import mee, en wat blijft achter?

Twee stromen, beide afkomstig uit de WhatsApp Business-app op de telefoon. Contacten komen binnen als smb_app_state_sync-webhooks, één item per contact met action add of remove, en hetzelfde veld meldt ook contacten die het bedrijf later in de app toevoegt, bewerkt of verwijdert. Chats komen binnen als history-webhooks: één-op-één-gesprekken van maximaal 180 dagen vóór onboarding, in beide richtingen, met hun leverstatus. Wat niet meekomt, staat hieronder vermeld, dus geheugen dat op de import is gebouwd, moet daar niet op rekenen.

Contactsfull_name, first_name, phone_number, user_id (BSUID), username
One-to-one chatsUp to 180 days, sent and received, grouped by conversation
Message statushistory_context.status: sent, delivered, read, played, pending or error
Mediamedia_placeholder without the file; separate webhooks carry ids for media from about the last 14 days
Group chatsNot included
App toolsLabels, quick replies, greeting and away messages stay on the phone

Hoe zorg je dat de import je server bereikt?

Zorg dat het endpoint live is voordat het nummer wordt verbonden, en sla het daarna op als directe webhook-bestemming van het nummer binnen 24 uur na het verbinden: op de pagina van het nummer onder Route incoming messages to your own webhook, met set_webhook_destination vanuit je AI, of als webhook_url in een Partner API connect-sessie. Het opslaan zorgt ervoor dat easyCoexistence Meta om de synchronisatie vraagt, eerst de contacten en daarna de geschiedenis, één keer per onboarding; het verzoek en de verzoek-id's van Meta verschijnen in het gebeurtenislogboek van het nummer als history_sync_requested.

Het bedrijf moet toestemming geven om geschiedenis te delen wanneer de app daarom vraagt tijdens de verbinding. Een nummer waarvan de berichten via easyCoexistence lopen (Through easyCoexistence in de kaart Where incoming messages go), zelfs met een Forward URL, krijgt geen import, omdat het verzoek alleen wordt gedaan voor een directe bestemming. Heb je later automatiseringen nodig, schakel dan over nadat de import is afgerond.

Hoe komen de geschiedenis-chunks binnen?

In willekeurige volgorde, in fasen die teruglopen vanaf de nieuwste berichten: fase 0 bestrijkt de laatste dag vóór onboarding, fase 1 tot dag 90 en fase 2 tot dag 180. Sorteer op metadata.chunk_order als de volgorde ertoe doet, en beschouw metadata.progress = 100 als het einde, want Meta merkt op dat de fase zelf niet aangeeft dat een fase klaar is. De id van een gesprek is het telefoonnummer van de klant, weggelaten wanneer dat niet gedeeld mag worden, en de context bevat wa_id, user_id en username. Een bericht dat het bedrijf heeft verstuurd, heeft in from het bedrijfsnummer en een veld to.

history webhook value, trimmed
{
  "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" }
        }
      ]
    }]
  }]
}

Hoe moet het geheugen van een agent worden opgeslagen?

Twee tabellen zijn genoeg. Personen worden gesleuteld op BSUID, de user_id die Meta toevoegt aan contacten, gesprekken en berichten, met het telefoonnummer ernaast, omdat een gebruiker met een username soms zonder telefoonnummer binnenkomt; de eigen referentie van Meta zegt dat je user_id moet gebruiken om een contact te identificeren. Berichten worden gesleuteld op hun wamid, zodat de import, live webhooks en herhaalde leveringen van hetzelfde bericht in één rij samenkomen, en een from_business-vlag legt vast wie er sprak. Indexeer op persoon en tijd, want de agent vraagt om de laatste beurten van één persoon.

memory.sql (PostgreSQL)
-- 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);

Hoe laad je chunks en contacten erin?

Met idempotente inserts, zodat volgorde en herlevering er niet meer toe doen. ingestHistory leest één history-wijziging: het logt een 2593109-weigering en gaat door, sleutelt een gesprek op context.user_id of zijn id, markeert een bericht als dat van het bedrijf wanneer from gelijk is aan metadata.display_phone_number, en slaat een [type]-placeholder op wanneer er geen tekst is. ingestContacts voert een upsert uit op user_id of telefoonnummer en markeert verwijderde contacten in plaats van hun berichten te wissen. Roep ze aan met change.value op een directe bestemming, of met de value uit de body wanneer het event van een forward history of smb_app_state_sync is.

memory.mjs: ingest and recall (Node.js, pg)
// 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 };
}

Hoe voed je dat geheugen aan de agent?

Begrensd, nooit allemaal tegelijk. memoryFor geeft de naam van de persoon uit het adresboek en diens laatste 20 beurten, de oudste eerst, beginnend met een klantbeurt zoals de meeste chat-API's verwachten; voeg een opgeslagen samenvatting van oudere gesprekken toe als de agent meer nodig heeft. Zes maanden chats in elke prompt kost tokens bij elk antwoord en verstopt de vraag die wordt gesteld.

Ter vergelijking: de ingebouwde stap Reply with AI leest maximaal 20 eerdere berichten (standaard 10), en de stap Call my webhook stuurt de laatste 10. Beide putten uit tekst die wordt bewaard gedurende de bewaartermijn die de eigenaar kiest, 30, 90 of 365 dagen (standaard 90), vanaf het moment dat automatiseringen aanstonden, en daarom moeten de zes maanden geïmporteerde chats in je eigen database staan.

Hoe blijft het geheugen actueel na de import?

Dezelfde bestemming blijft live verkeer ontvangen: berichten van klanten, smb_message_echoes voor antwoorden die in de app zijn getypt, en smb_app_state_sync wanneer het bedrijf zijn contacten bewerkt. Voeg ze via dezelfde tabellen toe met source live of echo. Wanneer een klant zijn telefoonnummer wijzigt, stuurt Meta een systeembericht van het type user_changed_number of user_changed_user_id met previous_user_id; dat is je signaal om hun rijen naar de nieuwe BSUID te verplaatsen.

Automatiseringen later inschakelen verwijdert de directe bestemming. Voeg dezelfde URL toe als Forward URL en lees event en value uit elke ondertekende POST, en wacht op progress 100 voordat je overschakelt, anders bereiken de resterende chunks je alleen via die forward.

Zo stel je het in

  1. 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.
  2. Connect the numberRun the connection from the dashboard, and accept sharing chat history when the WhatsApp Business app asks.
  3. 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.
  4. Store chunks until progress 100Insert contacts and messages as they come; the event log shows history_sync_requested once the request went to Meta.
  5. 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.

Veelgemaakte fouten

  • De bestemming op dag twee opslaan. De synchronisatie wordt alleen binnen 24 uur na het verbinden aangevraagd, dus een later opgeslagen endpoint begint alleen met live berichten.
  • Automatiseringen inschakelen voordat de voortgang 100 bereikt. De directe bestemming wordt meteen verwijderd, en latere chunks bereiken je alleen als er al een Forward URL is ingesteld.
  • Fase 2 zien als het einde van de import. Alleen metadata.progress = 100 zegt dat de synchronisatie klaar is, en chunks worden niet in volgorde geleverd.
  • Geheugen alleen op het telefoonnummer sleutelen. Gesprek-id's en contacten laten het telefoonnummer weg wanneer een gebruiker met een username het niet kan delen, terwijl user_id wel aanwezig blijft.
Dit doen met EasyCoexistence

Het verzoek wordt vastgelegd in het gebeurtenislogboek van het nummer, en het nummer wordt daarna 24/7 bewaakt. Van US$ 9 tot US$ 0,75 per nummer per maand, dalend naarmate je nummers toevoegt, met de eerste 3 dagen gratis.

Veelgestelde vragen

Kan de import een tweede keer draaien?

Alleen via een nieuwe onboarding. Meta staat één verzoek per onboarding toe, dus het nummer moet worden losgekoppeld en opnieuw verbonden, en de chats komen dan opnieuw binnen; door op bericht-id in te voegen, voegt de tweede doorgang niets dubbel toe.

Houdt easyCoexistence een kopie van de geïmporteerde chats bij?

Nee. Geschiedenis en contacten gaan van Meta rechtstreeks naar je endpoint en worden standaard niet opgeslagen. Voor een nummer met automatiseringen ingeschakeld bewaart easyCoexistence berichttekst gedurende de periode die je kiest, 30, 90 of 365 dagen (standaard 90), en het scherm Conversations toont die; doorgestuurde leveringen worden tot 7 dagen bewaard, en runlogs 30 dagen.

Hoe groot kunnen de payloads worden?

Eén Meta-webhook kan tot 3 MB bevatten, en een druk nummer stuurt veel history-chunks. Verhoog de body-limiet van je framework (Express staat standaard op 100 kb) en bevestig de ontvangst voordat je naar de database schrijft.

Heeft een agent de import nodig om te werken?

Nee. Zonder import begint het geheugen bij het eerste bericht na het verbinden en groeit het met live verkeer. De import is belangrijk wanneer eerdere gesprekken de antwoorden vanaf dag één moeten vormen, zoals de laatste bestelling van een terugkerende klant.

Lees verder

Klaar om te beginnen?

Stel WhatsApp Coexistence in enkele minuten in, niet maanden. De app blijft op je telefoon werken.

Start je gratis proefperiode

Geverifieerd op