תנו לסוכן ה-AI שלכם זיכרון: שישה חודשי צ'אטים ואנשי קשר ב-WhatsApp
בחיבור דרך Coexistence, Meta יכולה לשלוח לשרת שלכם, פעם אחת, את אנשי הקשר של האפליקציה ועד 180 יום של צ'אטים אישיים, בתנאי שיעד וובהוק (Webhook) ישיר נשמר תוך 24 שעות מהחיבור והעסק מאשר זאת באפליקציה. מקטעים עשויים להגיע בסדר שונה, וההתקדמות 100 מסמנת את הסוף. שמרו הודעות לפי מזהה ההודעה, זיהו אנשים לפי BSUID, והעבירו לסוכן את התורות האחרונות.
easyCoexistence מחבר את המספר דרך זרימת Coexistence של Meta, וכשתשמרו את נקודת הקצה שלכם כיעד הוובהוק הישיר תוך 24 שעות, היא מבקשת מ-Meta פעם אחת את אנשי הקשר ועד 180 יום של צ'אטים, שמגיעים ישירות לשרת שלכם.
עד כמה רחוק ייגע סנכרון ההיסטוריה מרגע ההטמעה; טבלת התכונות של Meta מכנה זאת 6 החודשים האחרונים.
הזמן לאחר ההטמעה שבו מבקשים אנשי קשר והיסטוריה; כל בקשה ניתנת פעם אחת בלבד.
ערך metadata.progress שמסמן את סיום סנכרון ההיסטוריה; Meta מציינת שהשלב לבדו אינו מספיק.
קוד שגיאה בוובהוק של היסטוריה כאשר העסק כיבה שיתוף היסטוריה באפליקציית WhatsApp Business.
שלב 0 מכסה יום 0 עד 1 לפני ההטמעה, שלב 1 ימים 1 עד 90, שלב 2 ימים 90 עד 180.
גודל ה-payload הגדול ביותר ש-Meta שולחת, שממנו נגזרת מגבלת גודל הגוף הדרושה לנקודת הקצה שלכם.
מה הייבוא מביא, ומה נשאר מאחור?
שני זרמים, שניהם מאפליקציית WhatsApp Business בטלפון. אנשי הקשר מגיעים ככוובהוקים של smb_app_state_sync, רשומה אחת לכל איש קשר עם פעולה של add או remove, והשדה הזה ממשיך לדווח על אנשי קשר שהעסק מוסיף, עורך או מסיר מאוחר יותר באפליקציה. הצ'אטים מגיעים ככוובהוקים של היסטוריה: שיחות אישיות מעד 180 יום לפני ההטמעה, בשני הכיוונים, עם סטטוס המסירה שלהן. מה שלא עובר מופיע בהמשך, ולכן זיכרון שנבנה על הייבוא לא צריך לצפות לו.
איך מוודאים שהייבוא מגיע לשרת שלכם?
נקודת הקצה צריכה להיות פעילה לפני שהמספר מתחבר, ואז לשמור אותה כיעד הוובהוק הישיר של המספר תוך 24 שעות מהחיבור: בדף המספר, תחת ניתוב הודעות נכנסות לוובהוק משלכם, עם set_webhook_destination מתוך ה-AI שלכם, או כ-webhook_url בסשן החיבור של Partner API. השמירה היא מה שגורם ל-easyCoexistence לבקש מ-Meta את הסנכרון, קודם אנשי הקשר ואחר כך ההיסטוריה, פעם אחת לכל הטמעה. הבקשה עצמה ומזהי הבקשה של Meta נרשמים ביומן האירועים של המספר, בסוג האירוע history_sync_requested, ואלה הפרטים שכדאי לשמור.
העסק חייב להסכים לשיתוף ההיסטוריה כשהאפליקציה שואלת במהלך החיבור. מספר שההודעות שלו עוברות דרך easyCoexistence ("Through easyCoexistence" בכרטיס Where incoming messages go), גם עם Forward URL, לא מקבל ייבוא, כי הבקשה נשלחת רק ליעד ישיר. אם תצטרכו אוטומציות בהמשך, החליפו את המצב אחרי שהייבוא מסתיים.
איך מגיעים מקטעי ההיסטוריה?
בלי סדר, בשלבים שמתחילים מההודעות החדשות ביותר ועוברים אחורה: שלב 0 מכסה את היום האחרון לפני ההטמעה, שלב 1 עד יום 90 ושלב 2 עד יום 180. מיינו לפי metadata.chunk_order אם הסדר חשוב, והתייחסו ל-metadata.progress = 100 כסוף, שכן Meta מציינת שהשלב לא אומר לכם שהשלב הסתיים. מזהה השיחה הוא מספר הטלפון של הלקוח, ומושמט כשאי אפשר לשתף אותו, וההקשר שלה כולל wa_id, user_id ו-username. הודעה שהעסק שלח נושאת את מספר העסק בשדה from, והנמען בשדה 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" }
}
]
}]
}]
}איך כדאי לשמור את הזיכרון של הסוכן?
שתי טבלאות מספיקות. אנשים מזוהים לפי BSUID, ה-user_id ש-Meta מוסיפה לאנשי הקשר, לשיחות ולהודעות, כשמספר הטלפון נשמר לצדו, כי משתמש עם username יכול להגיע בלעדיו. התיעוד של Meta עצמו קובע להשתמש ב-user_id כדי לזהות איש קשר. הודעות מזוהות לפי ה-wamid שלהן, כך שהייבוא, וובהוקים חיים ומשלוחים חוזרים של אותה הודעה מתמזגים לשורה אחת, ודגל from_business רושם מי דיבר. אינדקס לפי אדם וזמן, כי הסוכן מבקש את התורות האחרונות של אדם אחד.
-- 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);איך טוענים מקטעים ואנשי קשר לתוכו?
בהכנסות אידמפוטנטיות (idempotent), כך שסדר ושליחה חוזרת כבר לא משנים. ingestHistory קורא שינוי היסטוריה אחד: הוא רושם דחייה 2593109 ועובר הלאה, מזהה שיחה לפי context.user_id או לפי ה-id שלה, מסמן הודעה כשייכת לעסק כאשר from שווה ל-metadata.display_phone_number, ושומר מציין מיקום [type] כשאין טקסט. ingestContacts מבצע הוספה או עדכון (upsert) לפי user_id או מספר טלפון, ומסמן אנשי קשר שהוסרו במקום למחוק את ההודעות שלהם. קוראים להם עם change.value ביעד ישיר, או עם ה-value של הגוף, כשהאירוע בהעברה הוא היסטוריה או 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 };
}איך מזינים את הזיכרון לסוכן?
בגבולות, לעולם לא הכול בבת אחת. memoryFor מחזיר את שמו של האדם מספר הכתובות ואת 20 התורות האחרונות שלו, מהישנה לחדשה, כשהרשימה נפתחת בתור של לקוח, כפי שממשקי צ'אט רבים מצפים. כדאי להוסיף סיכום שמור של שיחות ישנות אם הסוכן צריך יותר. שישה חודשי צ'אטים בכל פרומפט עולים באסימונים בכל תגובה ומטשטשים את השאלה שנשאלה.
לשם השוואה, השלב המובנה Reply with AI קורא עד 20 הודעות קודמות (10 כברירת מחדל), ושלב השליחה לוובהוק שלי שולח את 10 האחרונות. שני השלבים שואבים מטקסט שנשמר לפי תקופת השמירה שבעל העסק בוחר, 30, 90 או 365 ימים (90 כברירת מחדל), מהרגע שהאוטומציות הופעלו, ולכן שישה חודשי הצ'אטים שיובאו צריכים לחיות במסד הנתונים שלכם.
איך נשמר הזיכרון עדכני אחרי הייבוא?
אותו יעד ממשיך לקבל תעבורה חיה: הודעות מלקוחות, smb_message_echoes לתשובות שנכתבו באפליקציה, ו-smb_app_state_sync כשהעסק עורך את אנשי הקשר שלו. מכניסים אותם דרך אותן טבלאות, כשהמקור מסומן כ-live או כ-echo, לפי העניין. כשלקוח משנה מספר טלפון, Meta שולחת הודעת מערכת מסוג user_changed_number או user_changed_user_id עם previous_user_id, והיא הרמז שלכם להעביר את השורות שלו ל-BSUID החדש.
הפעלת אוטומציות מאוחר יותר מסירה את היעד הישיר. הוסיפו את אותה כתובת כ-Forward URL וקראו את event ואת value מכל POST חתום, וחכו ל-progress 100 לפני המעבר, אחרת המקטעים שנותרו מגיעים רק דרך ההעברה.
איך מגדירים
- 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.
טעויות נפוצות
- שמירת היעד ביום השני. הסנכרון מתבקש רק תוך 24 שעות מהחיבור, ולכן יעד שנשמר מאוחר יותר מתחיל רק מהודעות חיות.
- הפעלת אוטומציות לפני שההתקדמות מגיעה ל-100. היעד הישיר מוסר מיד, והמקטעים המאוחרים מגיעים אליכם רק אם כבר הוגדר Forward URL.
- לראות בשלב 2 את סוף הייבוא. רק metadata.progress = 100 מציין שהסנכרון הושלם, והמקטעים אינם מגיעים בסדר רציף.
- לשמור זיכרון לפי מספר הטלפון בלבד. מזהי השיחות ואנשי הקשר מאבדים את מספר הטלפון כשמשתמש עם username לא יכול לשתף אותו, אבל user_id עדיין קיים.
הבקשה נרשמת ביומן האירועים של המספר, והמספר מנוטר 24/7 לאחר מכן. מ-US$ 9 ועד US$ 0.75 למספר בחודש, יורד ככל שמוסיפים מספרים, עם תקופת ניסיון של 3 ימים בחינם.
שאלות נפוצות
האם אפשר להריץ את הייבוא פעם שנייה?
רק דרך הטמעה חדשה. Meta מאפשרת בקשה אחת לכל הטמעה, ולכן צריך לנתק את המספר ולחבר אותו שוב, ואז הצ'אטים מגיעים שוב. הכנסה לפי מזהה הודעה מונעת הוספה כפולה בפעם השנייה.
האם easyCoexistence שומרת עותק של הצ'אטים המיובאים?
לא. ההיסטוריה ואנשי הקשר עוברים מ-Meta ישירות לנקודת הקצה שלכם ואינם נשמרים כברירת מחדל. במספר עם אוטומציות פעילות, easyCoexistence שומרת טקסט של הודעות לתקופה שתבחרו, 30, 90 או 365 ימים (90 כברירת מחדל), ומסך Conversations מציג אותו; משלוחים שהועברו נשמרים עד 7 ימים, ויומני הרצה 30 ימים.
כמה גדולים יכולים להיות ה-payloads?
וובהוק בודד של Meta יכול להכיל עד 3 MB, ומספר עמוס שולח מקטעי היסטוריה רבים. הגדילו את מגבלת הגוף של ה-framework שלכם (ברירת המחדל של Express היא 100 kb) ואשרו קבלה לפני הכתיבה למסד הנתונים.
האם הסוכן צריך את הייבוא כדי לעבוד?
לא. בלעדיו הזיכרון מתחיל מההודעה הראשונה אחרי החיבור וגדל מתעבורה חיה. הייבוא חשוב כשצ'אטים מהעבר צריכים לעצב תשובות מהיום הראשון, למשל ההזמנה האחרונה של לקוח שחוזר.
המשיכו לקרוא
מוכנים להתחיל?
מגדירים WhatsApp Coexistence בתוך דקות, לא חודשים. האפליקציה ממשיכה לעבוד בטלפון.
התחילו תקופת ניסיון בחינםנבדק ב-