Conectați-văÎncepeți perioada de probă gratuită
Meta Tech Provider

Dați memorie agentului AI: șase luni de conversații și contacte WhatsApp

Pe un număr conectat prin Coexistence, Meta poate trimite o singură dată serverului dumneavoastră contactele aplicației și conversațiile individuale din până la 180 de zile, cu condiția ca o destinație webhook directă să fie salvată în 24 de ore de la conectare și ca firma să accepte în aplicație. Fragmentele pot sosi în altă ordine, iar progresul 100 marchează sfârșitul. Stocați mesajele după id, persoanele după BSUID și transmiteți agentului ultimele replici.

easyCoexistence conectează numărul prin fluxul Coexistence al Meta și, când salvați endpoint-ul ca destinație webhook directă în 24 de ore, cere o singură dată de la Meta contactele și până la 180 de zile de conversații, care ajung direct la serverul dumneavoastră.

180 days

Cât de în urmă ajunge sincronizarea istoricului de la onboarding; tabelul de funcționalități Meta o numește cele mai recente 6 luni.

24 hours

Timpul de după onboarding în care se pot cere contactele și istoricul; fiecare cerere poate fi făcută o singură dată.

100

Valoarea metadata.progress care marchează sincronizarea istoricului ca finalizată; Meta spune că faza singură nu este suficientă.

2593109

Codul de eroare dintr-un webhook de istoric, când firma a dezactivat partajarea istoricului în aplicația WhatsApp Business.

3 phases

Faza 0 acoperă ziua 0 până la 1 înainte de onboarding, faza 1 zilele 1 până la 90, faza 2 zilele 90 până la 180.

3 MB

Cel mai mare payload webhook trimis de Meta, care stabilește limita dimensiunii corpului pe care trebuie să o accepte endpoint-ul dumneavoastră.

Ce aduce importul și ce rămâne în urmă?

Două fluxuri, ambele din aplicația WhatsApp Business de pe telefon. Contactele sosesc ca webhook-uri smb_app_state_sync, câte o intrare pentru fiecare contact, cu action add sau remove, iar același câmp raportează și contactele pe care firma le adaugă, editează sau șterge ulterior în aplicație. Conversațiile sosesc ca webhook-uri de tip history: conversații individuale din până la 180 de zile dinaintea onboarding-ului, în ambele direcții, cu starea livrării. Ce nu ajunge pe această cale este enumerat mai jos, deci memoria construită pe import nu ar trebui să se aștepte la el.

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

Cum vă asigurați că importul ajunge la serverul dumneavoastră?

Endpoint-ul trebuie să fie activ înainte de conectarea numărului, apoi trebuie salvat ca destinația webhook directă a numărului în 24 de ore de la conectare: pe pagina numărului, la Direcționați mesajele primite către propriul webhook, cu set_webhook_destination din AI-ul dumneavoastră, sau ca webhook_url într-o sesiune de conectare Partner API. Salvarea determină easyCoexistence să ceară de la Meta sincronizarea, întâi contactele și apoi istoricul, o singură dată pentru fiecare onboarding; cererea și id-urile de cerere Meta apar în jurnalul de evenimente al numărului ca history_sync_requested.

Firma trebuie să accepte partajarea istoricului atunci când aplicația o cere în timpul conectării. Un număr ale cărui mesaje trec prin easyCoexistence („Prin easyCoexistence” în cardul Unde ajung mesajele primite), chiar cu un Forward URL, nu primește niciun import, fiindcă cererea se face doar pentru o destinație directă. Dacă aveți nevoie de automatizări mai târziu, comutați după încheierea importului.

Cum sosesc fragmentele de istoric?

Fără o ordine garantată, în faze care pornesc de la cele mai noi mesaje spre cele vechi: faza 0 acoperă ultima zi dinaintea onboarding-ului, faza 1 până la ziua 90 și faza 2 până la ziua 180. Sortați după metadata.chunk_order dacă ordinea contează și tratați metadata.progress = 100 drept sfârșit, deoarece Meta notează că faza nu confirmă că o fază s-a încheiat. Id-ul unei conversații este numărul de telefon al clientului, omis atunci când nu poate fi partajat, iar contextul său conține wa_id, user_id și username. Un mesaj trimis de firmă are from setat la numărul firmei și un câmp 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" }
        }
      ]
    }]
  }]
}

Cum ar trebui stocată memoria unui agent?

Două tabele sunt suficiente. Persoanele au cheia BSUID, user_id-ul pe care Meta îl adaugă la contacte, conversații și mesaje, cu numărul de telefon păstrat alături, deoarece un utilizator cu username poate sosi fără el; referința Meta spune să folosiți user_id pentru a identifica un contact. Mesajele sunt indexate după wamid, astfel încât importul, webhook-urile live și livrările reîncercate ale aceluiași mesaj se reunesc într-un singur rând, iar un indicator from_business notează cine a vorbit. Indexați după persoană și timp, deoarece agentul cere ultimele replici ale unei singure persoane.

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);

Cum încărcați fragmentele și contactele în memorie?

Cu inserări idempotente, astfel încât ordinea și redistribuirea nu mai contează. ingestHistory citește o modificare de istoric: înregistrează un refuz 2593109 și trece mai departe, indexează o conversație după context.user_id sau după id, marchează un mesaj ca fiind al firmei când from este egal cu metadata.display_phone_number și stochează un marcaj [type] când nu există text. ingestContacts face upsert după user_id sau numărul de telefon și marchează contactele eliminate, fără să șteargă mesajele lor. Apelați-le cu change.value pe o destinație directă sau cu valoarea din corpul cererii când evenimentul unei redirecționări este history sau smb_app_state_sync.

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 };
}

Cum alimentați această memorie agentul?

Limitată, niciodată integral. memoryFor returnează numele persoanei din agenda de contacte și ultimele 20 de replici, de la cea mai veche la cea mai nouă, deschizând cu o replică a clientului, cum așteaptă majoritatea API-urilor de chat; adăugați un rezumat stocat al conversațiilor mai vechi dacă agentul are nevoie de mai mult. Șase luni de conversații în fiecare prompt costă tokeni la fiecare răspuns și ascunde întrebarea adresată.

Pentru comparație, pasul încorporat Răspunde cu AI citește cel mult 20 de mesaje anterioare (implicit 10), iar pasul Apelează webhook-ul meu trimite ultimele 10. Ambele se bazează pe text păstrat pe durata de retenție aleasă de proprietar, 30, 90 sau 365 de zile (implicit 90), din momentul în care automatizările au fost pornite, motiv pentru care cele șase luni de conversații importate trebuie să stea în propria bază de date.

Cum rămâne memoria actuală după import?

Aceeași destinație continuă să primească trafic live: mesajele clienților, smb_message_echoes pentru răspunsurile scrise în aplicație și smb_app_state_sync când firma își editează contactele. Inserați-le prin aceleași tabele cu sursa live sau echo. Când un client își schimbă numărul de telefon, Meta trimite un mesaj de sistem de tip user_changed_number sau user_changed_user_id, cu previous_user_id, ceea ce vă arată că trebuie să mutați rândurile lui pe noul BSUID.

Activarea ulterioară a automatizărilor elimină destinația directă. Adăugați același URL ca Forward URL, citiți event și value din fiecare POST semnat și așteptați progresul 100 înainte de comutare, altfel fragmentele rămase ajung la dumneavoastră doar prin redirecționare.

Cum să îl configurați

  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.

Greșeli frecvente

  • Salvarea destinației a doua zi. Sincronizarea se cere doar în 24 de ore de la conectare, deci un endpoint salvat mai târziu pornește doar de la mesajele live.
  • Pornirea automatizărilor înainte ca progresul să ajungă la 100. Destinația directă se elimină imediat, iar fragmentele ulterioare ajung la dumneavoastră doar dacă un Forward URL este deja setat.
  • Tratarea fazei 2 drept sfârșitul importului. Doar metadata.progress = 100 spune că sincronizarea este completă, iar fragmentele nu sosesc în ordine.
  • Indexarea memoriei doar după numărul de telefon. Id-urile conversațiilor și contactele pierd numărul de telefon atunci când un utilizator cu username nu îl poate partaja, în timp ce user_id rămâne prezent.
Faceți acest lucru cu EasyCoexistence

Cererea este înregistrată în jurnalul de evenimente al numărului, iar numărul este monitorizat 24/7 după aceea. De la US$ 9 până la US$ 0,75 per număr pe lună, pe măsură ce adăugați numere, cu primele 3 zile gratuite.

Întrebări frecvente

Importul poate rula a doua oară?

Doar printr-un onboarding nou. Meta permite o singură cerere pentru fiecare onboarding, deci numărul trebuie deconectat și conectat din nou, iar conversațiile sosesc apoi din nou. Inserarea după id-ul mesajului împiedică ca a doua trecere să adauge ceva de două ori.

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

Nu. Istoricul și contactele merg de la Meta direct la endpoint-ul dumneavoastră și nu sunt stocate implicit. Pentru un număr cu automatizări pornite, easyCoexistence păstrează textul mesajelor pe perioada pe care o alegeți, 30, 90 sau 365 de zile (implicit 90), iar ecranul Conversații îl afișează; livrările redirecționate sunt păstrate până la 7 zile, iar jurnalele de rulare 30 de zile.

Cât de mari pot fi payload-urile?

Un singur webhook Meta poate conține până la 3 MB, iar un număr activ trimite multe fragmente de istoric. Ridicați limita de corp a framework-ului dumneavoastră (Express are implicit 100 kb) și confirmați primirea înainte de a scrie în baza de date.

Are nevoie agentul de import ca să funcționeze?

Nu. Fără el, memoria începe cu primul mesaj după conectare și crește din traficul live. Importul contează atunci când conversațiile anterioare trebuie să modeleze răspunsurile din prima zi, de exemplu ultima comandă a unui client care revine.

Continuați să citiți

Gata să începeți?

Configurați WhatsApp Coexistence în câteva minute, nu luni. Aplicația continuă să funcționeze pe telefon.

Începeți perioada de probă gratuită

Verificat la