Prijavite seZapočnite besplatno probno razdoblje
Meta Tech Provider

Dajte svom AI agentu memoriju: šest mjeseci WhatsApp razgovora i kontakata

Za broj povezan kroz Coexistence Meta može jednom poslati kontakte aplikacije i do 180 dana razgovora jedan na jedan vašem poslužitelju, ako se izravno odredište webhooka spremi unutar 24 sata od povezivanja i tvrtka pristane u aplikaciji. Dijelovi mogu stići izvan redoslijeda, a napredak 100 označava kraj. Poruke pohranjujte prema ID-u, osobe prema BSUID-u, a agentu proslijedite nedavne poruke razgovora.

easyCoexistence povezuje broj kroz Coexistence tok Mete i, kad spremite endpoint kao izravno odredište webhooka unutar 24 sata, jednom traži od Mete kontakte i do 180 dana razgovora, koji idu ravno na vaš poslužitelj.

180 days

Koliko unatrag sinkronizacija povijesti seže od onboardinga; Metina tablica značajki to naziva najnovijih 6 mjeseci.

24 hours

Vrijeme nakon onboardinga za traženje kontakata i povijesti; svaki zahtjev može se poslati samo jednom.

100

Vrijednost metadata.progress koja označava da je sinkronizacija povijesti završena; Meta kaže da sama faza to ne znači.

2593109

Kôd pogreške u webhooku povijesti kad tvrtka isključi dijeljenje povijesti u aplikaciji WhatsApp Business.

3 phases

Faza 0 obuhvaća dan 0 do 1 prije onboardinga, faza 1 od 1. do 90. dana, a faza 2 od 90. do 180. dana.

3 MB

Najveći webhook payload koji šalje Meta, što određuje ograničenje veličine tijela koje vaš endpoint treba.

Što uvoz donosi, a što ostaje iza?

Dva toka, oba iz aplikacije WhatsApp Business na telefonu. Kontakti stižu kao smb_app_state_sync webhookovi, jedan unos po kontaktu s radnjom add ili remove, a isto polje prijavljuje i kontakte koje tvrtka kasnije doda, uredi ili ukloni u aplikaciji. Razgovori stižu kao webhookovi povijesti: razgovori jedan na jedan iz razdoblja do 180 dana prije onboardinga, u oba smjera, sa statusom isporuke. Ono što ne dolazi naveden je u nastavku, pa memorija izgrađena na uvozu ne bi to trebala očekivati.

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

Kako osigurati da uvoz stigne do vašeg poslužitelja?

Endpoint mora biti aktivan prije povezivanja broja, a zatim ga spremite kao izravno odredište webhooka broja unutar 24 sata od povezivanja: na stranici broja pod Usmjeri dolazne poruke na vlastiti webhook, pomoću set_webhook_destination iz vašeg AI-ja ili kao webhook_url u sesiji povezivanja Partner API-ja. Spremanje je ono što natjera easyCoexistence da od Mete zatraži sinkronizaciju, prvo kontakata pa povijesti, jednom po uvođenju; zahtjev i Metini ID-ovi pojavljuju se u dnevniku događaja broja kao history_sync_requested.

Tvrtka mora pristati na dijeljenje povijesti kad to aplikacija zatraži tijekom povezivanja. Broj čije poruke dolaze preko easyCoexistence (Preko easyCoexistence u kartici Kamo idu dolazne poruke), čak i s URL-om za prosljeđivanje, ne dobiva uvoz, jer se zahtjev šalje samo za izravno odredište. Ako kasnije trebate automatizacije, prebacite se nakon završetka uvoza.

Kako stižu dijelovi povijesti?

Izvan redoslijeda, u fazama koje idu od najnovijih poruka unatrag: faza 0 obuhvaća posljednji dan prije onboardinga, faza 1 do 90. dana, a faza 2 do 180. dana. Sortirajte prema metadata.chunk_order ako je redoslijed važan i metadata.progress = 100 smatrajte krajem, jer Meta napominje da faza sama ne govori je li neka faza završena. ID razgovora je telefonski broj kupca, izostavljen kad se ne može podijeliti, a kontekst sadrži wa_id, user_id i username. Poruka koju je poslala tvrtka ima from postavljen na broj tvrtke, a polje to na primatelja.

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" }
        }
      ]
    }]
  }]
}

Kako treba pohraniti memoriju agenta?

Dvije tablice su dovoljne. Osobe se određuju prema BSUID-u, user_id koji Meta dodaje kontaktima, razgovorima i porukama, uz telefonski broj pohranjen uz njega, jer korisnik s korisničkim imenom može stići bez njega; Metina vlastita referenca kaže da se user_id koristi za identifikaciju kontakta. Poruke se identificiraju prema wamid-u, pa se uvoz, webhookovi u stvarnom vremenu i ponovne isporuke iste poruke spajaju u jedan redak, a zastavica from_business bilježi tko je govorio. Indeksirajte prema osobi i vremenu, jer agent traži posljednje izmjene jedne osobe.

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

Kako se dijelovi i kontakti učitavaju u memoriju?

Idempotentnim umetanjem, pa redoslijed i ponovno isporučivanje više ne znače ništa. ingestHistory čita jednu promjenu povijesti: bilježi odbijanje 2593109 i ide dalje, razgovor određuje prema context.user_id ili prema njegovu ID-u, označava poruku kao tvrtkinu kad from bude jednak metadata.display_phone_number i sprema oznaku [type] kad nema teksta. ingestContacts radi upsert prema user_id ili telefonskom broju i označava uklonjene kontakte umjesto da briše njihove poruke. Pozivajte ih s change.value na izravnom odredištu ili s value iz tijela kad je događaj prosljeđivanja history ili 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 };
}

Kako se ta memorija prosljeđuje agentu?

Ograničeno, nikad sve odjednom. memoryFor vraća ime osobe iz adresara i njezinih posljednjih 20 izmjena, od najstarije prema najnovijoj, počevši s kupčevom porukom kao što većina chat API-ja očekuje; dodajte pohranjeni sažetak starijih razgovora ako agentu treba više. Šest mjeseci razgovora u svakom promptu troši tokene pri svakom odgovoru i zatrpava pitanje na koje se odgovara.

Za usporedbu, ugrađeni korak Odgovori pomoću AI-ja čita najviše 20 prethodnih poruka (podrazumijevano 10), a korak Pozovi moj webhook šalje posljednjih 10. Oba koriste tekst pohranjen koliko odredi vlasnik, 30, 90 ili 365 dana (podrazumijevano 90), od trenutka kad su automatizacije uključene, zbog čega se šest mjeseci uvezenih razgovora mora čuvati u vlastitoj bazi podataka.

Kako memorija ostaje aktualna nakon uvoza?

Isto odredište i dalje prima promet uživo: poruke od kupaca, smb_message_echoes za odgovore upisane u aplikaciji te smb_app_state_sync kad tvrtka uredi svoje kontakte. Umećite ih kroz iste tablice s oznakom source live ili echo. Kad kupac promijeni telefonski broj, Meta šalje poruku sustava tipa user_changed_number ili user_changed_user_id s previous_user_id, što je znak da zapise premjestite na novi BSUID.

Uključivanje automatizacija kasnije uklanja izravno odredište. Dodajte isti URL kao URL za prosljeđivanje, čitajte event i value iz svakog potpisanog POST zahtjeva i pričekajte da progress dosegne 100 prije prebacivanja, inače preostali dijelovi do vas stižu samo kroz to prosljeđivanje.

Kako ga postaviti

  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.

Uobičajene pogreške

  • Spremanje odredišta drugog dana. Sinkronizacija se traži samo unutar 24 sata od povezivanja, pa endpoint spremljen kasnije kreće samo od poruka uživo.
  • Uključivanje automatizacija prije nego napredak dosegne 100. Izravno odredište se odmah uklanja, a kasniji dijelovi do vas stižu samo ako je URL za prosljeđivanje već postavljen.
  • Fazu 2 smatrati krajem uvoza. Samo metadata.progress = 100 kaže da je sinkronizacija završena, a dijelovi ne stižu redom.
  • Određivanje memorije samo prema telefonskom broju. ID-ovi razgovora i kontakti izostavljaju telefonski broj kad korisnik s korisničkim imenom ne može ga podijeliti, dok je user_id i dalje prisutan.
Radite ovo uz EasyCoexistence

Zahtjev se bilježi u dnevniku događaja broja, a broj se nakon toga nadzire 24/7. Od US$ 9 do US$ 0,75 po povezanom broju mjesečno, cijena pada kako dodajete brojeve, a prva 3 dana su besplatna.

Često postavljana pitanja

Može li se uvoz pokrenuti drugi put?

Samo kroz novo uvođenje. Meta dopušta jedan zahtjev po onboardingu, pa broj treba odspojiti i ponovno povezati, a razgovori tada stižu ponovno; umetanje prema ID-u poruke sprječava da drugi prolaz išta dvostruko doda.

Čuva li easyCoexistence kopiju uvezenih razgovora?

Ne. Povijest i kontakti idu od Mete ravno na vaš endpoint i nisu zadano pohranjeni. Za broj s uključenim automatizacijama easyCoexistence čuva tekst poruka onoliko dugo koliko odaberete, 30, 90 ili 365 dana (zadano 90), a prikazuje ga zaslon Razgovori; proslijeđene isporuke čuvaju se do 7 dana, a zapisi izvođenja 30 dana.

Koliko mogu biti veliki payloadi?

Jedan Metin webhook može nositi do 3 MB, a broj s velikim prometom šalje mnogo dijelova povijesti. Povećajte ograničenje tijela vašeg okvira (Express zadano ima 100 kb) i potvrdite primitak prije upisa u bazu podataka.

Treba li agentu uvoz da bi radio?

Ne. Bez njega memorija kreće od prve poruke nakon povezivanja i raste iz prometa uživo. Uvoz je bitan kad prošli razgovori trebaju oblikovati odgovore od prvog dana, primjerice posljednja narudžba vraćajućeg kupca.

Nastavite čitati

Spremni za početak?

Postavite WhatsApp Coexistence u nekoliko minuta, a ne mjeseci. Aplikacija i dalje radi na telefonu.

Započnite besplatno probno razdoblje

Provjereno na