Dajte svom AI agentu memoriju: šest meseci WhatsApp razgovora i kontakata
Na broju povezanom preko Coexistence, Meta jednom može poslati kontakte iz aplikacije i do 180 dana razgovora jedan na jedan na vaš server, ako je direktno odredište webhooka sačuvano u roku od 24 sata od povezivanja i ako firma to odobri u aplikaciji. Delovi mogu stići van redosleda, a napredak 100 označava kraj. Poruke čuvajte po id-ju, ključne osobe po BSUID-u, a poslednje poruke prosleđujte agentu.
easyCoexistence povezuje broj preko Metinog Coexistence toka i, kada sačuvate svoj endpoint kao direktno odredište webhooka u roku od 24 sata, od Mete jednom traži kontakte i do 180 dana razgovora, koji idu ravno na vaš server.
Dokle sinhronizacija istorije seže od početka povezivanja; Metina tabela mogućnosti navodi poslednjih 6 meseci.
Vreme posle uključivanja kada se traže kontakti i istorija; svaki zahtev može se poslati samo jednom.
Vrednost metadata.progress koja označava da je sinhronizacija istorije završena; Meta kaže da sama faza to ne znači.
Kod greške u webhooku istorije kada je firma isključila deljenje istorije u aplikaciji WhatsApp Business.
Faza 0 pokriva dan 0 do 1 pre uključivanja, faza 1 dane 1 do 90, faza 2 dane 90 do 180.
Najveći payload koji Meta šalje, što određuje potrebno ograničenje veličine tela na vašem endpointu.
Šta uvoz donosi, a šta ostaje iza?
Dva toka, oba iz aplikacije WhatsApp Business na telefonu. Kontakti stižu kao smb_app_state_sync webhookovi, jedan unos po kontaktu sa radnjom add ili remove, a isto polje javlja i kontakte koje firma kasnije doda, izmeni ili ukloni u aplikaciji. Razgovori stižu kao webhookovi istorije: razgovori jedan na jedan iz perioda do 180 dana pre uključivanja, u oba smera, sa statusom isporuke. Šta ne dolazi, navedeno je ispod, pa memorija zasnovana na uvozu ne treba to da očekuje.
Kako da budete sigurni da uvoz stiže do vašeg servera?
Endpoint mora biti aktivan pre nego što se broj poveže, pa ga zatim sačuvajte kao direktno odredište webhooka broja u roku od 24 sata od povezivanja: na stranici broja pod Preusmeri dolazne poruke na sopstveni webhook, pomoću set_webhook_destination iz vašeg AI alata, ili kao webhook_url u sesiji povezivanja Partner API-ja. Čuvanje je ono što natera easyCoexistence da od Mete zatraži sinhronizaciju, prvo kontakte pa zatim istoriju, jednom po uključivanju; zahtev i Metini id-jevi zahteva pojavljuju se u dnevniku događaja broja kao history_sync_requested.
Firma mora da pristane na deljenje istorije kada aplikacija to zatraži tokom povezivanja. Broj čije poruke stižu preko easyCoexistence (Preko easyCoexistence u kartici Kuda idu dolazne poruke), čak i sa Forward URL-om, ne dobija uvoz, jer se zahtev šalje samo za direktno odredište. Ako kasnije zatrebaju automatizacije, prebacite se tek kada se uvoz završi.
Kako stižu delovi istorije?
Van redosleda, u fazama koje idu od najnovijih poruka unazad: faza 0 pokriva poslednji dan pre uključivanja, faza 1 do dana 90, a faza 2 do dana 180. Ako je redosled bitan, sortirajte po metadata.chunk_order, a metadata.progress = 100 tretirajte kao kraj, jer Meta napominje da faza ne znači da je neka faza završena. Id razgovora je broj telefona klijenta, izostavljen kada ne sme da se podeli, a njegov kontekst sadrži wa_id, user_id i username. Poruka koju je firma poslala ima polje from postavljeno na broj firme i polje 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" }
}
]
}]
}]
}Kako treba čuvati memoriju agenta?
Dve tabele su dovoljne. Osobe se čuvaju po BSUID-u, user_id koji Meta dodaje kontaktima, razgovorima i porukama, uz broj telefona pored, jer korisnik sa korisničkim imenom može stići bez njega; Metina sopstvena referenca kaže da se kontakt identifikuje preko user_id. Poruke se čuvaju po wamid-u, pa se uvoz, webhookovi uživo i ponovljene isporuke iste poruke spoje u jedan red, a polje from_business beleži ko je govorio. Indeksirajte po osobi i vremenu, jer agent traži poslednje poruke jedne osobe.
-- 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 u memoriju učitati delove i kontakte?
Idempotentnim unosima, da redosled i ponovna isporuka više ne smetaju. ingestHistory čita jednu promenu istorije: beleži odbijanje 2593109 i ide dalje, razgovor vezuje za context.user_id ili za svoj id, poruku označava kao firminu kada from odgovara vrednosti metadata.display_phone_number, a kada nema teksta čuva oznaku [type]. ingestContacts radi upsert po user_id ili broju telefona i označava uklonjene kontakte umesto da briše njihove poruke. Pozivajte ih sa change.value kod direktnog odredišta, ili sa value iz tela kada je događaj prosleđen i ima vrednost history ili 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 };
}Kako agentu dostaviti tu memoriju?
U ograničenoj meri, nikada sve odjednom. memoryFor vraća ime osobe iz adresara i njenih poslednjih 20 poruka, od najstarijih ka najnovijim, počevši od poruke klijenta, kako većina API-ja za razgovor očekuje; dodajte sačuvani rezime starijih razgovora ako agentu treba više. Šest meseci razgovora u svakom promptu troši tokene na svakom odgovoru i guši pitanje koje se postavlja.
Za poređenje, ugrađeni korak Reply with AI čita najviše 20 ranijih poruka (podrazumevano 10), a korak Call my webhook šalje poslednjih 10. Oba koriste tekst sačuvan onoliko koliko vlasnik izabere, 30, 90 ili 365 dana (podrazumevano 90), od trenutka kada su automatizacije uključene, zato šest meseci uvezenih razgovora mora da čuvate u sopstvenoj bazi.
Kako memorija ostaje aktuelna posle uvoza?
Isto odredište i dalje prima žive događaje: poruke od klijenata, smb_message_echoes za odgovore ukucane u aplikaciji i smb_app_state_sync kada firma izmeni svoje kontakte. Unosite ih kroz iste tabele, sa source vrednošću live ili echo. Kada klijent promeni broj telefona, Meta šalje sistemsku poruku tipa user_changed_number ili user_changed_user_id sa previous_user_id, što je znak da redove tog klijenta prebacite na novi BSUID.
Kada kasnije uključite automatizacije, direktno odredište se uklanja. Dodajte isti URL kao Forward URL, čitajte polja event i value iz svakog potpisanog POST zahteva i sačekajte progress 100 pre prebacivanja, inače preostali delovi stižu samo preko tog prosleđivanja.
Kako da podesite
- 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.
Česte greške
- Čuvanje odredišta drugog dana. Sinhronizacija se traži samo u roku od 24 sata od povezivanja, pa endpoint sačuvan kasnije dobija samo žive poruke.
- Uključivanje automatizacija pre nego što progress dostigne 100. Direktno odredište se odmah uklanja, a kasniji delovi stižu vama samo ako je Forward URL već podešen.
- Tretiranje faze 2 kao kraja uvoza. Samo metadata.progress = 100 znači da je sinhronizacija završena, a delovi ne stižu redom.
- Čuvanje memorije samo po broju telefona. Id-jevi razgovora i kontakti gube broj telefona kada korisnik sa korisničkim imenom ne sme da ga podeli, dok user_id i dalje postoji.
Zahtev se beleži u dnevniku događaja broja, a broj se posle toga prati 24/7. Od US$ 9 do US$ 0.75 po broju mesečno, a cena pada kako dodajete brojeve, uz to da su prva 3 dana besplatna.
Često postavljana pitanja
Može li uvoz da se pokrene drugi put?
Samo kroz novo uključivanje. Meta dozvoljava jedan zahtev po uključivanju, pa broj mora da se isključi i ponovo poveže, a razgovori tada ponovo stižu; unos po id-ju poruke sprečava da drugi prolaz išta doda dvaput.
Da li easyCoexistence čuva kopiju uvezenih razgovora?
Ne. Istorija i kontakti idu od Mete ravno na vaš endpoint i podrazumevano se ne čuvaju. Za broj sa uključenim automatizacijama easyCoexistence čuva tekst poruka onoliko koliko izaberete, 30, 90 ili 365 dana (podrazumevano 90), a ekran Razgovori ga prikazuje; prosleđene isporuke čuvaju se do 7 dana, a zapisi izvršavanja 30 dana.
Koliko mogu da budu veliki payloadi?
Jedan Metin webhook može nositi do 3 MB, a zauzet broj šalje mnogo delova istorije. Povećajte ograničenje tela zahteva vašeg okvira (Express podrazumevano ima 100 kb) i potvrdite prijem pre upisa u bazu.
Da li agentu treba uvoz da bi radio?
Ne. Bez njega memorija počinje od prve poruke posle povezivanja i raste iz živog saobraćaja. Uvoz je važan kada prošli razgovori treba da oblikuju odgovore od prvog dana, na primer poslednja porudžbina vraćajućeg klijenta.
Nastavite sa čitanjem
Spremni da počnete?
Podesite WhatsApp Coexistence za nekoliko minuta, a ne meseci. Aplikacija nastavlja da radi na telefonu.
Započnite besplatni probni periodProvereno na