Mpe wakala wako wa AI kumbukumbu: miezi sita ya mazungumzo ya WhatsApp na anwani
Kwenye nambari iliyounganishwa kupitia Coexistence, Meta inaweza kutuma mara moja kwa server yako anwani za programu ya WhatsApp Business na hadi siku 180 za mazungumzo ya mtu mmoja mmoja, mradi webhook ya moja kwa moja imehifadhiwa ndani ya saa 24 tangu muunganisho na biashara ikikubali ndani ya programu. Vipande vinaweza kufika visivyofuatana, na maendeleo 100 ndiyo mwisho. Hifadhi ujumbe kwa id, watu kwa BSUID, kisha lisha wakala zamu za hivi karibuni za mazungumzo.
easyCoexistence huunganisha nambari kupitia mtiririko wa Coexistence wa Meta, na ukihifadhi endpoint yako kama direct webhook destination ya nambari ndani ya saa 24, huomba Meta mara moja anwani na hadi siku 180 za mazungumzo, ambazo hufika moja kwa moja kwenye server yako.
Umbali wa nyuma ambao usawazishaji wa historia unafikia tangu uanzishaji; jedwali la vipengele la Meta linauita miezi 6 ya karibuni zaidi.
Muda baada ya uanzishaji wa kuomba anwani na historia; kila ombi linaweza kufanywa mara moja tu.
Thamani ya metadata.progress inayoonyesha kwamba usawazishaji wa historia umekamilika; Meta inasema phase peke yake haitoshi.
Msimbo wa hitilafu katika webhook ya historia wakati biashara imezima kushiriki historia katika programu ya WhatsApp Business.
Phase 0 inahusu siku 0 hadi 1 kabla ya uanzishaji, phase 1 siku 1 hadi 90, phase 2 siku 90 hadi 180.
Payload kubwa zaidi ambayo Meta hutuma, ambayo huamua kikomo cha ukubwa wa mwili unaohitajika na endpoint yako.
Uagizaji huleta nini, na nini hubaki nyuma?
Mitiririko miwili, yote kutoka kwenye programu ya WhatsApp Business kwenye simu. Anwani hufika kama webhook za smb_app_state_sync, ingizo moja kwa kila anwani lenye action add au remove, na sehemu hiyo hiyo huripoti pia anwani ambazo biashara baadaye huziongeza, kuzihariri au kuziondoa kwenye programu. Mazungumzo hufika kama webhook za historia: mazungumzo ya mtu mmoja mmoja kutoka hadi siku 180 kabla ya uanzishaji, pande zote mbili, pamoja na hali yake ya uwasilishaji. Kisichokuja kimeorodheshwa hapa chini, kwa hiyo kumbukumbu inayojengwa juu ya uagizaji huu isitarajie.
Unahakikishaje uagizaji unafika kwenye server yako?
Hakikisha endpoint iko hewani kabla nambari haijaunganishwa, kisha uihifadhi kama direct webhook destination ya nambari ndani ya saa 24 tangu muunganisho: kwenye ukurasa wa nambari chini ya "Elekeza ujumbe unaoingia kwenye webhook yako mwenyewe", kwa set_webhook_destination kutoka AI yako, au kama webhook_url katika kipindi cha kuunganisha Partner API. Kuihifadhi ndiko kunakomfanya easyCoexistence aombe usawazishaji kutoka Meta, kwanza anwani kisha historia, mara moja kwa kila uanzishaji. Ombi pamoja na ids za Meta huonekana kwenye kumbukumbu ya matukio ya nambari kama history_sync_requested.
Biashara lazima ikubali kushiriki historia programu inapoomba wakati wa muunganisho. Nambari ambayo ujumbe wake unapitia easyCoexistence (Kupitia easyCoexistence kwenye kadi ya Ujumbe unaoingia unaenda wapi), hata ukiwa na Forward URL, haipati uagizaji, kwa sababu ombi hufanywa tu kwa destination ya moja kwa moja. Ukihitaji automations baadaye, badilisha baada ya uagizaji kumalizika.
Vipande vya historia vinafikaje?
Visivyofuatana, katika awamu zinazoenda kutoka ujumbe wa karibuni kurudi nyuma: phase 0 inahusu siku ya mwisho kabla ya uanzishaji, phase 1 hadi siku 90 na phase 2 hadi siku 180. Panga kwa metadata.chunk_order ikiwa mpangilio ni muhimu, na chukulia metadata.progress = 100 kama mwisho, kwa sababu Meta inaeleza kwamba phase haikuambii awamu imekamilika. Id ya mazungumzo ni nambari ya simu ya mteja, iliyoachwa nje pale isipoweza kushirikiwa, na muktadha wake una wa_id, user_id na username. Ujumbe ulioutumwa na biashara una from iliyowekwa kwenye nambari ya biashara, pamoja na sehemu ya 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" }
}
]
}]
}]
}Kumbukumbu ya wakala inapaswa kuhifadhiwaje?
Majedwali mawili yanatosha. Watu wanatambuliwa kwa BSUID, yaani user_id ambayo Meta huongeza kwenye anwani, mazungumzo na ujumbe, huku nambari ya simu ikihifadhiwa pembeni yake, kwa sababu mtumiaji mwenye username anaweza kufika bila nambari. Marejeo ya Meta yenyewe yanasema utumie user_id kumtambua mtu wa anwani. Ujumbe unatambuliwa kwa wamid yake, hivyo uagizaji, webhook za moja kwa moja na uwasilishaji uliojaribiwa upya wa ujumbe mmoja huungana kuwa safu moja, na bendera from_business hurekodi aliyezungumza. Weka index kwa mtu na wakati, kwa sababu wakala huomba zamu za hivi karibuni za mtu mmoja.
-- 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);Vipande na anwani vinapakiwaje humo?
Kwa kuingiza kwa idempotent, ili mpangilio na uwasilishaji upya visiwe na umuhimu tena. ingestHistory husoma badiliko moja la historia: hurekodi kukataliwa kwa 2593109 kisha huendelea, huweka mazungumzo kwa context.user_id au id yake, huweka alama ujumbe kuwa wa biashara pale from inapolingana na metadata.display_phone_number, na huhifadhi kishikilia nafasi cha [type] pale maandishi yasipokuwepo. ingestContacts huingiza au kusasisha kwa user_id au nambari ya simu, na huweka alama kwenye anwani zilizoondolewa badala ya kufuta ujumbe wao. Ziite na change.value kwenye destination ya moja kwa moja, au na value ya body pale event ya forward ni history au 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 };
}Kumbukumbu hiyo inalishwaje kwa wakala?
Kwa kiasi kinachodhibitiwa, si yote kwa mara moja. memoryFor hurejesha jina la mtu kutoka kitabu cha anwani na zamu zake 20 za mwisho, za zamani kwanza, zikianza na zamu ya mteja kama API nyingi za mazungumzo zinavyotarajia. Ongeza muhtasari uliohifadhiwa wa mazungumzo ya zamani ikiwa wakala anahitaji zaidi. Miezi sita ya mazungumzo katika kila prompt hugharimu token kwa kila jibu na kufunika swali linaloulizwa.
Kwa kulinganisha, hatua ya Reply with AI iliyojengwa ndani husoma upeo wa ujumbe 20 uliotangulia (10 kwa chaguo-msingi), na hatua ya Call my webhook hutuma 10 za mwisho. Zote mbili zinategemea maandishi yaliyohifadhiwa kwa muda wa uhifadhi anaochagua mmiliki, siku 30, 90 au 365 (90 kwa chaguo-msingi), kuanzia wakati automations zilipowashwa, ndiyo sababu miezi sita ya mazungumzo yaliyoagizwa lazima iishi kwenye database yako mwenyewe.
Kumbukumbu inabaki ya kisasa vipi baada ya uagizaji?
Destination hiyo hiyo bado hupokea trafiki ya moja kwa moja: ujumbe kutoka kwa wateja, smb_message_echoes kwa majibu yaliyoandikwa kwenye programu, na smb_app_state_sync biashara inapohariri anwani zake. Ziingize kwenye majedwali yale yale ukiwa na source live au echo. Mteja akibadilisha nambari ya simu, Meta hutuma ujumbe wa mfumo wa aina user_changed_number au user_changed_user_id wenye previous_user_id, ambao ni ishara yako ya kuhamisha safu zake kwenda BSUID mpya.
Kuwasha automations baadaye huondoa destination ya moja kwa moja. Weka URL hiyo hiyo kama Forward URL, soma event na value kutoka kila POST iliyosainiwa, na subiri progress 100 kabla ya kubadilisha, vinginevyo vipande vilivyobaki vitakufikia tu kupitia forward hiyo.
Jinsi ya kuisanidi
- 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.
Makosa ya kawaida
- Kuhifadhi destination siku ya pili. Usawazishaji huombwa tu ndani ya saa 24 tangu muunganisho, kwa hiyo endpoint iliyohifadhiwa baadaye huanza na ujumbe wa moja kwa moja pekee.
- Kuwasha automations kabla maendeleo hayajafika 100. Destination ya moja kwa moja huondolewa mara moja, na vipande vya baadaye hukufikia tu ikiwa Forward URL tayari imewekwa.
- Kuchukulia phase 2 kama mwisho wa uagizaji. Ni metadata.progress = 100 pekee inayosema usawazishaji umekamilika, na vipande havifikishwi kwa mpangilio.
- Kutambua kumbukumbu kwa nambari ya simu peke yake. Id za mazungumzo na anwani huacha nambari ya simu pale mtumiaji mwenye username asipoweza kuishiriki, ilhali user_id bado ipo.
Ombi hurekodiwa kwenye kumbukumbu ya matukio ya nambari, na baadaye nambari hufuatiliwa saa 24 kwa siku. Kuanzia US$ 9 kwa kila nambari iliyounganishwa kwa mwezi hadi US$ 0.75 kadri unavyoongeza nambari, na siku 3 za kwanza ni kipindi cha majaribio bila malipo.
Maswali yanayoulizwa mara kwa mara
Je, uagizaji unaweza kuendeshwa mara ya pili?
Kupitia uanzishaji mpya tu. Meta inaruhusu ombi moja kwa kila uanzishaji, kwa hiyo nambari lazima ikatwe na kuunganishwa tena, na mazungumzo hufika tena. Kuingiza kwa id ya ujumbe kunazuia pasi ya pili kuongeza chochote mara mbili.
Je, easyCoexistence huweka nakala ya mazungumzo yaliyoagizwa?
Hapana. Historia na anwani hutoka Meta moja kwa moja kwenda endpoint yako na hazihifadhiwi kwa chaguo-msingi. Kwa nambari yenye automations zilizowashwa, easyCoexistence huhifadhi maandishi ya ujumbe kwa muda unaochagua, siku 30, 90 au 365 (90 kwa chaguo-msingi), na skrini ya Mazungumzo huyaonyesha; uwasilishaji uliosambazwa huhifadhiwa hadi siku 7, na kumbukumbu za kuendesha siku 30.
Payload zinaweza kuwa kubwa kiasi gani?
Webhook moja ya Meta inaweza kubeba hadi 3 MB, na nambari yenye shughuli nyingi hutuma vipande vingi vya historia. Ongeza kikomo cha body cha framework yako (Express huanza na 100 kb) na thibitisha kupokea kabla ya kuandika kwenye database.
Je, wakala anahitaji uagizaji ili ufanye kazi?
Hapana. Bila hiyo, kumbukumbu huanza na ujumbe wa kwanza baada ya muunganisho na kukua kutoka trafiki ya moja kwa moja. Uagizaji unajali pale mazungumzo ya zamani yanapopaswa kuathiri majibu tangu siku ya kwanza, kama vile agizo la mwisho la mteja anayerudi.
Endelea kusoma
Uko tayari kuanza?
Sanidi WhatsApp Coexistence kwa dakika chache, si miezi. Programu inaendelea kufanya kazi kwenye simu.
Anza kipindi cha majaribio bila malipoImethibitishwa kwenye