اپنے AI ایجنٹ کو میموری دیں: WhatsApp چیٹس اور رابطوں کے چھ مہینے
Coexistence کے ذریعے جڑے نمبر پر، Meta ایپ کے رابطے اور 180 دن تک کی ایک سے ایک چیٹس ایک بار آپ کے سرور کو بھیج سکتا ہے، بشرطیکہ کنکشن کے 24 گھنٹوں کے اندر براہ راست ویب ہک ڈیسٹینیشن محفوظ ہو اور کاروبار ایپ میں اجازت دے۔ چنکس بے ترتیب آ سکتے ہیں، اور progress 100 آخری حصے کا نشان ہے۔ میسجز کو id سے محفوظ کریں، لوگوں کو BSUID سے شناخت کریں، اور حالیہ جوابات ایجنٹ کو دیں۔
easyCoexistence نمبر کو Meta کے Coexistence فلو کے ذریعے جوڑتا ہے اور، جب آپ اینڈ پوائنٹ کو 24 گھنٹوں کے اندر براہ راست ویب ہک ڈیسٹینیشن کے طور پر محفوظ کرتے ہیں، تو Meta سے رابطوں اور 180 دن تک کی چیٹس کی ایک بار درخواست کرتا ہے، جو سیدھی آپ کے سرور تک جاتی ہیں۔
آن بورڈنگ سے ہسٹری سنک کتنے عرصے پیچھے تک جاتا ہے؛ Meta کے فیچر ٹیبل میں اسے حالیہ 6 مہینے کہا گیا ہے۔
رابطوں اور ہسٹری کی درخواست کرنے کا آن بورڈنگ کے بعد کا وقت؛ ہر درخواست صرف ایک بار کی جا سکتی ہے۔
وہ metadata.progress ویلیو جو ہسٹری سنک کو مکمل ظاہر کرتی ہے؛ Meta کہتا ہے کہ صرف phase کافی نہیں۔
ہسٹری ویب ہک میں وہ ایرر کوڈ جب کاروبار نے WhatsApp Business ایپ میں ہسٹری شیئرنگ بند کر دی ہو۔
Phase 0 آن بورڈنگ سے پہلے کے دن 0 سے 1 کا احاطہ کرتا ہے، phase 1 دن 1 سے 90 تک، phase 2 دن 90 سے 180 تک۔
Meta کی بھیجی گئی سب سے بڑی ویب ہک پے لوڈ، جو آپ کے اینڈ پوائنٹ کو درکار باڈی سائز کی حد طے کرتی ہے۔
امپورٹ کیا لاتا ہے، اور کیا پیچھے رہ جاتا ہے؟
دو دھارے ہیں، دونوں فون پر WhatsApp Business ایپ سے۔ رابطے smb_app_state_sync ویب ہکس کے طور پر آتے ہیں، ہر رابطے کے لیے ایک اندراج، جس میں action add یا remove ہوتا ہے، اور یہی فیلڈ ان رابطوں کی تبدیلیاں بھی بتاتی ہے جو کاروبار بعد میں ایپ میں شامل، تبدیل یا حذف کرتا ہے۔ چیٹس history ویب ہکس کے طور پر آتی ہیں: آن بورڈنگ سے پہلے 180 دن تک کی ایک سے ایک بات چیت، دونوں سمتوں میں، ان کی ڈیلیوری اسٹیٹس کے ساتھ۔ جو چیز ساتھ نہیں آتی وہ نیچے درج ہے، اس لیے امپورٹ پر بنائی گئی میموری سے اس کی توقع نہ رکھیں۔
امپورٹ آپ کے سرور تک کیسے پہنچے، اس کا یقین کیسے کریں؟
اینڈ پوائنٹ نمبر کے جڑنے سے پہلے لائیو رکھیں، پھر کنکشن کے 24 گھنٹوں کے اندر اسے نمبر کی براہ راست ویب ہک ڈیسٹینیشن کے طور پر محفوظ کریں: نمبر کے صفحے پر Route incoming messages to your own webhook کے تحت، یا set_webhook_destination کے ذریعے اپنے AI سے، یا Partner API کنیکٹ سیشن پر webhook_url کے طور پر۔ اسے محفوظ کرنا ہی easyCoexistence کو Meta سے سنک کی درخواست کرنے دیتا ہے، پہلے رابطے، پھر ہسٹری، ہر آن بورڈنگ میں ایک بار؛ درخواست اور Meta کی درخواست آئی ڈیز نمبر کے ایونٹ لاگ میں history_sync_requested کے طور پر ظاہر ہوتی ہیں۔
کنکشن کے دوران جب ایپ پوچھے تو کاروبار کو ہسٹری شیئر کرنے پر راضی ہونا ہوگا۔ وہ نمبر جس کے پیغام easyCoexistence کے ذریعے آتے ہیں (کارڈ Where incoming messages go میں Through easyCoexistence)، Forward URL کے ساتھ بھی، کوئی امپورٹ نہیں لیتا، کیونکہ درخواست صرف براہ راست ڈیسٹینیشن کے لیے کی جاتی ہے۔ اگر بعد میں آپ کو automations چاہئیں تو امپورٹ ختم ہونے کے بعد سوئچ کریں۔
ہسٹری چنکس کیسے آتے ہیں؟
بے ترتیب، ایسے مرحلوں میں جو سب سے نئے میسجز سے پیچھے کی طرف چلتے ہیں: phase 0 آن بورڈنگ سے پہلے کا آخری دن، phase 1 دن 90 تک، اور phase 2 دن 180 تک۔ ترتیب اہم ہو تو metadata.chunk_order سے ترتیب دیں، اور metadata.progress = 100 کو اختتام سمجھیں، کیونکہ Meta نوٹ کرتا ہے کہ phase یہ نہیں بتاتا کہ کوئی مرحلہ ختم ہو گیا ہے۔ کسی بات چیت کی id گاہک کا فون نمبر ہوتی ہے، جو شیئر نہ ہو سکے تو حذف کر دیا جاتا ہے، اور اس کے context میں 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 inserts کے ذریعے، تاکہ ترتیب اور دوبارہ ڈیلیوری کی کوئی اہمیت نہ رہے۔ ingestHistory ایک history تبدیلی پڑھتا ہے: 2593109 کا انکار لاگ کرتا ہے اور آگے بڑھ جاتا ہے، context.user_id یا اس کی id سے بات چیت کی شناخت کرتا ہے، جب from، metadata.display_phone_number کے برابر ہو تو میسج کو کاروبار کا نشان زد کرتا ہے، اور متن نہ ہو تو [type] پلیس ہولڈر محفوظ کرتا ہے۔ ingestContacts، user_id یا فون نمبر پر upsert کرتا ہے اور ہٹائے گئے رابطوں کو نشان زد کرتا ہے، ان کے میسجز حذف نہیں کرتا۔ انہیں براہ راست ڈیسٹینیشن پر change.value کے ساتھ، یا جب فارورڈ کا ایونٹ history یا smb_app_state_sync ہو تو body کی value کے ساتھ کال کریں۔
// 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 باتیں، پرانی سے نئی کی ترتیب میں، واپس کرتا ہے، اور پہلا میسج گاہک کا رکھتا ہے جیسا کہ زیادہ تر چیٹ APIs چاہتی ہیں؛ اگر ایجنٹ کو زیادہ چاہیے تو پرانی بات چیتوں کا محفوظ شدہ خلاصہ شامل کریں۔ ہر جواب میں چھ مہینوں کی چیٹس ڈالنا ہر جواب پر ٹوکن خرچ کرتا ہے اور پوچھے جانے والے سوال کو دبا دیتا ہے۔
موازنے کے لیے، بلٹ ان Reply with AI مرحلہ زیادہ سے زیادہ 20 پچھلے میسجز پڑھتا ہے (ڈیفالٹ 10)، اور Call my webhook مرحلہ آخری 10 بھیجتا ہے۔ دونوں اس متن پر انحصار کرتے ہیں جو مالک کی منتخب کردہ مدت تک رکھا جاتا ہے، 30، 90 یا 365 دن (ڈیفالٹ 90)، automations آن ہونے کے وقت سے، اسی لیے چھ مہینوں کی امپورٹ شدہ چیٹس آپ کے اپنے ڈیٹا بیس میں رہنی چاہئیں۔
امپورٹ کے بعد میموری کیسے تازہ رہتی ہے؟
وہی ڈیسٹینیشن لائیو ٹریفک وصول کرتی رہتی ہے: گاہکوں کے میسجز، ایپ میں ٹائپ کیے گئے جوابات کے لیے smb_message_echoes، اور جب کاروبار اپنے رابطے بدلے تو smb_app_state_sync۔ انہیں انہی ٹیبلز میں source live یا echo کے ساتھ ڈالیں۔ جب گاہک فون نمبر بدلتا ہے تو Meta user_changed_number یا user_changed_user_id ٹائپ کا سسٹم میسج بھیجتا ہے جس میں previous_user_id ہوتا ہے، جو آپ کو اشارہ دیتا ہے کہ ان کی قطاریں نئے BSUID پر منتقل کریں۔
بعد میں automations آن کرنے سے براہ راست ڈیسٹینیشن ہٹ جاتی ہے۔ وہی URL بطور Forward URL شامل کریں اور ہر دستخط شدہ POST سے event اور value پڑھیں، اور سوئچ کرنے سے پہلے 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 گھنٹوں کے اندر ہی مانگا جاتا ہے، اس لیے بعد میں محفوظ کیا گیا اینڈ پوائنٹ صرف لائیو میسجز سے شروع ہوتا ہے۔
- progress 100 سے پہلے automations آن کرنا۔ براہ راست ڈیسٹینیشن فوراً ہٹ جاتی ہے، اور بعد کے چنکس تبھی پہنچتے ہیں جب Forward URL پہلے سے سیٹ ہو۔
- phase 2 کو امپورٹ کا اختتام سمجھنا۔ صرف metadata.progress = 100 بتاتا ہے کہ سنک مکمل ہے، اور چنکس ترتیب سے نہیں پہنچتے۔
- میموری کو صرف فون نمبر پر رکھنا۔ بات چیت کی آئی ڈیز اور رابطے فون نمبر چھوڑ دیتے ہیں جب username والا صارف اسے شیئر نہ کر سکے، جبکہ user_id پھر بھی موجود ہوتا ہے۔
درخواست نمبر کے ایونٹ لاگ میں درج ہوتی ہے، اور اس کے بعد نمبر 24/7 مانیٹر ہوتا ہے۔ فی نمبر فی مہینہ US$ 9 سے US$ 0.75 تک، نمبر بڑھانے کے ساتھ کم ہوتی ہوئی، پہلے 3 دن کا فری ٹرائل۔
اکثر پوچھے جانے والے سوالات
کیا امپورٹ دوبارہ چل سکتا ہے؟
صرف ایک نئی آن بورڈنگ کے ذریعے۔ Meta ہر آن بورڈنگ پر ایک درخواست کی اجازت دیتا ہے، اس لیے نمبر کو دوبارہ ڈس کنیکٹ اور کنیکٹ کرنا ہوگا، اور چیٹس پھر آئیں گی؛ میسج id کے ذریعے انسرٹ کرنے سے دوسری بار کچھ بھی دو بار شامل نہیں ہوتا۔
کیا easyCoexistence امپورٹ شدہ چیٹس کی کاپی رکھتا ہے؟
نہیں۔ ہسٹری اور رابطے Meta سے براہ راست آپ کے اینڈ پوائنٹ پر جاتے ہیں اور ڈیفالٹ طور پر محفوظ نہیں ہوتے۔ جس نمبر پر automations آن ہوں اس کے لیے easyCoexistence میسج کا متن آپ کی منتخب کردہ مدت تک رکھتا ہے، 30، 90 یا 365 دن (ڈیفالٹ 90)، اور Conversations اسکرین اسے دکھاتی ہے؛ فارورڈ کی گئی ڈیلیوریز 7 دن تک رکھی جاتی ہیں، اور رن لاگز 30 دن۔
پے لوڈ کتنے بڑے ہو سکتے ہیں؟
ایک Meta ویب ہک 3 MB تک لے جا سکتا ہے، اور مصروف نمبر بہت سے ہسٹری چنکس بھیجتا ہے۔ اپنے فریم ورک کی باڈی حد بڑھائیں (Express ڈیفالٹ طور پر 100 kb رکھتا ہے) اور ڈیٹا بیس میں لکھنے سے پہلے رسید بھیجیں۔
کیا ایجنٹ کے کام کرنے کے لیے امپورٹ ضروری ہے؟
نہیں۔ اس کے بغیر میموری کنیکٹ کرنے کے بعد پہلے میسج سے شروع ہوتی ہے اور لائیو ٹریفک سے بڑھتی ہے۔ امپورٹ تب اہم ہے جب پچھلی بات چیت پہلے دن سے جوابات کو شکل دے، جیسے کسی واپس آنے والے گاہک کا آخری آرڈر۔
مزید پڑھیں
شروع کرنے کے لیے تیار ہیں؟
WhatsApp Coexistence چند منٹ میں سیٹ اپ کریں، مہینوں میں نہیں۔ ایپ فون پر کام کرتی رہتی ہے۔
فری ٹرائل شروع کریںتصدیق شدہ تاریخ