התחברותהתחילו תקופת ניסיון
Meta Tech Provider

תנו לסוכן ה-AI שלכם זיכרון: שישה חודשי צ'אטים ואנשי קשר ב-WhatsApp

בחיבור דרך Coexistence, Meta יכולה לשלוח לשרת שלכם, פעם אחת, את אנשי הקשר של האפליקציה ועד 180 יום של צ'אטים אישיים, בתנאי שיעד וובהוק (Webhook) ישיר נשמר תוך 24 שעות מהחיבור והעסק מאשר זאת באפליקציה. מקטעים עשויים להגיע בסדר שונה, וההתקדמות 100 מסמנת את הסוף. שמרו הודעות לפי מזהה ההודעה, זיהו אנשים לפי BSUID, והעבירו לסוכן את התורות האחרונות.

easyCoexistence מחבר את המספר דרך זרימת Coexistence של Meta, וכשתשמרו את נקודת הקצה שלכם כיעד הוובהוק הישיר תוך 24 שעות, היא מבקשת מ-Meta פעם אחת את אנשי הקשר ועד 180 יום של צ'אטים, שמגיעים ישירות לשרת שלכם.

180 days

עד כמה רחוק ייגע סנכרון ההיסטוריה מרגע ההטמעה; טבלת התכונות של Meta מכנה זאת 6 החודשים האחרונים.

24 hours

הזמן לאחר ההטמעה שבו מבקשים אנשי קשר והיסטוריה; כל בקשה ניתנת פעם אחת בלבד.

100

ערך metadata.progress שמסמן את סיום סנכרון ההיסטוריה; Meta מציינת שהשלב לבדו אינו מספיק.

2593109

קוד שגיאה בוובהוק של היסטוריה כאשר העסק כיבה שיתוף היסטוריה באפליקציית WhatsApp Business.

3 phases

שלב 0 מכסה יום 0 עד 1 לפני ההטמעה, שלב 1 ימים 1 עד 90, שלב 2 ימים 90 עד 180.

3 MB

גודל ה-payload הגדול ביותר ש-Meta שולחת, שממנו נגזרת מגבלת גודל הגוף הדרושה לנקודת הקצה שלכם.

מה הייבוא מביא, ומה נשאר מאחור?

שני זרמים, שניהם מאפליקציית WhatsApp Business בטלפון. אנשי הקשר מגיעים ככוובהוקים של smb_app_state_sync, רשומה אחת לכל איש קשר עם פעולה של add או remove, והשדה הזה ממשיך לדווח על אנשי קשר שהעסק מוסיף, עורך או מסיר מאוחר יותר באפליקציה. הצ'אטים מגיעים ככוובהוקים של היסטוריה: שיחות אישיות מעד 180 יום לפני ההטמעה, בשני הכיוונים, עם סטטוס המסירה שלהן. מה שלא עובר מופיע בהמשך, ולכן זיכרון שנבנה על הייבוא לא צריך לצפות לו.

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

איך מוודאים שהייבוא מגיע לשרת שלכם?

נקודת הקצה צריכה להיות פעילה לפני שהמספר מתחבר, ואז לשמור אותה כיעד הוובהוק הישיר של המספר תוך 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, כך שכדאי לבדוק את שניהם.

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

איך כדאי לשמור את הזיכרון של הסוכן?

שתי טבלאות מספיקות. אנשים מזוהים לפי BSUID, ה-user_id ש-Meta מוסיפה לאנשי הקשר, לשיחות ולהודעות, כשמספר הטלפון נשמר לצדו, כי משתמש עם username יכול להגיע בלעדיו. התיעוד של Meta עצמו קובע להשתמש ב-user_id כדי לזהות איש קשר. הודעות מזוהות לפי ה-wamid שלהן, כך שהייבוא, וובהוקים חיים ומשלוחים חוזרים של אותה הודעה מתמזגים לשורה אחת, ודגל from_business רושם מי דיבר. אינדקס לפי אדם וזמן, כי הסוכן מבקש את התורות האחרונות של אדם אחד.

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

איך טוענים מקטעים ואנשי קשר לתוכו?

בהכנסות אידמפוטנטיות (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: 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 };
}

איך מזינים את הזיכרון לסוכן?

בגבולות, לעולם לא הכול בבת אחת. 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 לפני המעבר, אחרת המקטעים שנותרו מגיעים רק דרך ההעברה.

איך מגדירים

  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.

טעויות נפוצות

  • שמירת היעד ביום השני. הסנכרון מתבקש רק תוך 24 שעות מהחיבור, ולכן יעד שנשמר מאוחר יותר מתחיל רק מהודעות חיות.
  • הפעלת אוטומציות לפני שההתקדמות מגיעה ל-100. היעד הישיר מוסר מיד, והמקטעים המאוחרים מגיעים אליכם רק אם כבר הוגדר Forward URL.
  • לראות בשלב 2 את סוף הייבוא. רק metadata.progress = 100 מציין שהסנכרון הושלם, והמקטעים אינם מגיעים בסדר רציף.
  • לשמור זיכרון לפי מספר הטלפון בלבד. מזהי השיחות ואנשי הקשר מאבדים את מספר הטלפון כשמשתמש עם username לא יכול לשתף אותו, אבל user_id עדיין קיים.
עושים את זה עם EasyCoexistence

הבקשה נרשמת ביומן האירועים של המספר, והמספר מנוטר 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 ומזהי BSUID: מה משתנה בוובהוקים (Webhook) של Cloud APIאיך שמות משתמש ב-WhatsApp משנים את הוובהוקים של Cloud API: ה-BSUID בשדה user_id, מתי השדה wa_id נעלם, מענה לנמען ושינויים ב-Coexistence.בניית סוכן AI ל-WhatsApp ב-Node.js וב-Python על מספר Coexistenceקוד Node.js ו-Python לסוכן AI ב-WhatsApp על מספר Coexistence: אימות אירועים חתומים, השהיה כשאדם עונה, דילוג על כפילויות ובדיקת חלון 24 שעות.איך הודעות WhatsApp מגיעות לשרת שלכם: ישירות או מנוהלות, ואימות החתימהישיר: Meta שולחת לשרת שלכם. מנוהל: אוטומציות עונות ועותק חתום נשלח ל-Forward URL. ה-payload, X-EC-Signature ב-Node ו-Python, וניסיונות חוזרים.וובהוק historyהשדה שמעביר פעם אחת את היסטוריית הצ׳אט במספר Coexistence: מה מגיע, מתי ולמה.וובהוק (Webhook) smb_app_state_syncסנכרון אנשי הקשר מאפליקציית WhatsApp Business מגיע בשדה הזה. מה הוא כולל ולמה הוא נפרד מהיסטוריית ההודעות.מה בינה מלאכותית יכולה לראות ולעשות ב-WhatsApp שלי? נתונים, אחסון וניתוקמה ה-AI המחובר למספר ה-WhatsApp Business שלכם רואה ויכול לעשות, מה נשלח לספק ה-AI, מה נשמר וכמה זמן, וכיצד לנתק גישה.

מוכנים להתחיל?

מגדירים WhatsApp Coexistence בתוך דקות, לא חודשים. האפליקציה ממשיכה לעבוד בטלפון.

התחילו תקופת ניסיון בחינם

נבדק ב-