تسجيل الدخولابدأ الفترة التجريبية المجانية
Meta Tech Provider

امنح وكيل الذكاء الاصطناعي ذاكرة: ستة أشهر من محادثات WhatsApp وجهات الاتصال

على رقم متصل عبر Coexistence، يمكن لـMeta إرسال جهات اتصال التطبيق ومحادثات فردية تصل إلى 180 يومًا إلى خادمك مرة واحدة، بشرط حفظ وجهة خطاف الويب (webhook) المباشرة خلال 24 ساعة من الاتصال، وموافقة النشاط التجاري داخل التطبيق. قد تصل المقاطع خارج الترتيب، ويعني التقدم 100 انتهاء المزامنة. خزّن الرسائل بمعرّف الرسالة، وفهرِس الأشخاص بـBSUID، ومرّر الأدوار الأخيرة إلى الوكيل.

يربط easyCoexistence الرقم عبر تدفق Coexistence الخاص بـMeta، وعندما تحفظ endpoint كوجهة webhook مباشرة خلال 24 ساعة، يطلب من Meta مرة واحدة جهات الاتصال وحتى 180 يومًا من المحادثات، وتصل إلى خادمك مباشرة.

180 days

المدى الذي تصل إليه مزامنة السجل منذ الإعداد؛ ويسميه جدول ميزات Meta «أحدث 6 أشهر».

24 hours

الوقت بعد الإعداد الذي يمكن فيه طلب جهات الاتصال والسجل؛ ولا يُقبل كل طلب إلا مرة واحدة.

100

قيمة metadata.progress التي تعني اكتمال مزامنة السجل؛ وتقول Meta إن المرحلة وحدها لا تكفي.

2593109

رمز الخطأ في webhook السجل عندما يوقف النشاط التجاري مشاركة السجل في تطبيق WhatsApp Business.

3 phases

المرحلة 0 تغطي اليوم 0 إلى 1 قبل الإعداد، والمرحلة 1 من اليوم 1 إلى 90، والمرحلة 2 من اليوم 90 إلى 180.

3 MB

أكبر حمولة webhook ترسلها Meta، وهي تحدد حد حجم نص الطلب الذي تحتاجه نقطة النهاية (endpoint) لديك.

ما الذي يجلبه الاستيراد، وما الذي يبقى خلفه؟

تأتي البيانات من تدفقين، وكلاهما من تطبيق WhatsApp Business على الهاتف. تصل جهات الاتصال كـwebhooks من نوع smb_app_state_sync، بمدخل لكل جهة اتصال بالإجراء add أو remove، ويستمر الحقل نفسه في الإبلاغ عن جهات الاتصال التي يضيفها النشاط التجاري أو يعدّلها أو يحذفها لاحقًا في التطبيق. وتصل المحادثات عبر webhooks للسجل: محادثات فردية تمتد حتى 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

كيف تضمن وصول الاستيراد إلى خادمك؟

اجعل endpoint يعمل قبل اتصال الرقم، ثم احفظه كوجهة webhook مباشرة للرقم خلال 24 ساعة من الاتصال: في صفحة الرقم ضمن «Route incoming messages to your own webhook»، أو عبر set_webhook_destination من الذكاء الاصطناعي لديك، أو كـ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 إلى جهات الاتصال والمحادثات والرسائل، ويُحفظ رقم الهاتف إلى جانبه، لأن المستخدم الذي له اسم مستخدم قد يصل دون رقم؛ وينص مرجع 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 أو بمعرّفها، وتعدّ الرسالة صادرة عن النشاط إذا تساوى from مع metadata.display_phone_number، وتخزّن عنصرًا نائبًا بالصيغة [type] عندما لا يوجد نص. ويعمل ingestContacts بتحديث أو إدراج حسب user_id أو رقم الهاتف، ويعلّم جهات الاتصال المحذوفة بدل حذف رسائلها. استدعِ الدالتين بـchange.value على وجهة مباشرة، أو بقيمة value من الجسم عندما يكون event في رسالة Forward هو history أو 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 افتراضيًا)، وترسل خطوة Call my webhook آخر 10 رسائل. وكلتاهما تعتمد على نص محفوظ طوال مدة الاحتفاظ التي يختارها المالك، 30 أو 90 أو 365 يومًا (90 افتراضيًا)، منذ تشغيل الأتمتة، ولهذا يجب أن تعيش محادثات الأشهر الستة المستوردة في قاعدة بياناتك.

كيف تبقى الذاكرة محدّثة بعد الاستيراد؟

تستمر الوجهة نفسها في استقبال الحركة المباشرة: رسائل العملاء، وsmb_message_echoes للردود المكتوبة في التطبيق، وsmb_app_state_sync عندما يعدّل النشاط جهات اتصاله. أدرجها عبر الجداول نفسها بالقيمة source على live أو echo. وعندما يغيّر العميل رقم هاتفه، ترسل Meta رسالة نظام من نوع user_changed_number أو user_changed_user_id مع previous_user_id، وهي إشارة لنقل صفوفه إلى BSUID الجديد.

وتشغيل الأتمتة لاحقًا يزيل الوجهة المباشرة. أضف عنوان URL نفسه كـForward URL واقرأ event وvalue من كل طلب POST موقّع، وانتظر progress 100 قبل التبديل، وإلا فلن تصلك المقاطع المتبقية إلا عبر Forward URL.

كيفية إعداده

  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 ساعة من الاتصال، لذا فإن endpoint يُحفظ لاحقًا يبدأ من الرسائل المباشرة فقط.
  • تشغيل الأتمتة قبل أن يبلغ التقدم 100. تُحذف الوجهة المباشرة فورًا، ولا تصل المقاطع اللاحقة إليك إلا إذا كان Forward URL مضبوطًا من قبل.
  • اعتبار المرحلة 2 نهاية الاستيراد. لا تدل على اكتمال المزامنة إلا metadata.progress = 100، والمقاطع لا تصل بالتسلسل.
  • فهرسة الذاكرة على رقم الهاتف وحده. تفقد معرّفات المحادثات وجهات الاتصال رقم الهاتف عندما لا يستطيع المستخدم الذي له اسم مستخدم مشاركته، بينما يبقى user_id موجودًا.
إنجاز ذلك باستخدام EasyCoexistence

يُسجَّل الطلب في سجل أحداث الرقم، ويُراقب الرقم على مدار الساعة بعد ذلك. من US$ 9 لكل رقم متصل شهريًا، ينخفض إلى US$ 0.75 كلما أضفت أرقامًا، مع فترة تجريبية مجانية مدتها 3 أيام.

الأسئلة الشائعة

هل يمكن تشغيل الاستيراد مرة ثانية؟

فقط عبر إعداد جديد. تسمح Meta بطلب واحد لكل إعداد، لذا يجب فصل الرقم ثم ربطه من جديد، وتصل المحادثات عندها مرة أخرى. والإدراج بمعرّف الرسالة يمنع المرور الثاني من إضافة أي شيء مرتين.

هل يحتفظ easyCoexistence بنسخة من المحادثات المستوردة؟

لا. تنتقل المحادثات وجهات الاتصال من Meta مباشرة إلى endpoint لديك، ولا تُخزَّن افتراضيًا. وبالنسبة إلى رقم تكون فيه الأتمتة مفعّلة، يحتفظ easyCoexistence بنص الرسائل للمدة التي تختارها، 30 أو 90 أو 365 يومًا (90 افتراضيًا)، وتعرضه شاشة المحادثات؛ وتُحفظ عمليات التسليم المُعاد توجيهها حتى 7 أيام، وسجلات التشغيل 30 يومًا.

ما أكبر حجم للحمولات؟

قد تحمل webhook واحدة من Meta حتى 3 MB، ويرسل الرقم المزدحم مقاطع سجل كثيرة. ارفع حد الجسم في إطار العمل لديك (يبلغ الافتراضي في Express 100 kb) وأكّد الاستلام قبل الكتابة في قاعدة البيانات.

هل يحتاج الوكيل إلى الاستيراد ليعمل؟

لا. بدونه تبدأ الذاكرة من أول رسالة بعد الاتصال، وتنمو من الحركة المباشرة. يهم الاستيراد عندما ينبغي أن تشكّل المحادثات الماضية الردود من اليوم الأول، مثل آخر طلب لعميل عائد.

تابع القراءة

أسماء مستخدمي WhatsApp ومعرّفات BSUID: ما يتغيّر في خطّاف الويب (webhooks) لـ Cloud APIكيف تغيّر أسماء مستخدمي WhatsApp مضمون webhooks في Cloud API: معرّف BSUID في user_id، ومتى يختفي wa_id وfrom، والرد عبر recipient، وتغييرات Coexistence.بناء وكيل ذكاء اصطناعي لـ WhatsApp بـ Node.js وPython على رقم Coexistenceكود Node.js وPython لوكيل ذكاء اصطناعي على رقم Coexistence: التحقق من الأحداث الموقّعة، والتوقف عند رد شخص، وتجاهل التكرار، وفحص نافذة 24 ساعة.كيف تصل رسائل WhatsApp إلى خادمك: مباشرة أو مُدارة، والتحقق من التوقيعمباشرة: تنشر Meta إلى خادمك. مُدارة: ترد الأتمتة، وتصل نسخة موقّعة إلى عنوان URL للتوجيه. الحمولة، وتوقيع X-EC-Signature في Node وPython، وإعادة المحاولة.خطاف الويب (webhook) للحقل historyيُسلَّم سجل المحادثات لمرة واحدة لرقم Coexistence عبر هذا الحقل. تعرف ما يصل، ومتى يصل، ولماذا يحدث ذلك مرة واحدة فقط.خطاف الويب smb_app_state_syncتصل مزامنة جهات الاتصال من تطبيق WhatsApp Business عبر هذا الحقل، مع توضيح محتواه وسبب فصله عن سجل المحادثات.ما الذي يستطيع الذكاء الاصطناعي رؤيته وفعله على WhatsApp؟ البيانات والتخزين وقطع الاتصالما الذي يستطيع الذكاء الاصطناعي المتصل برقم WhatsApp Business قراءته وفعله، وما يصل إلى مزود الذكاء الاصطناعي، وما يتم تخزينه ومدة ذلك، وكيفية قطع الوصول.

هل أنت مستعد للبدء؟

أعد إعداد WhatsApp Coexistence خلال دقائق، وليس أشهر. يواصل التطبيق العمل على الهاتف.

ابدأ الفترة التجريبية المجانية

تم التحقق في