Mag-log inMagsimula ng Libreng Trial
Meta Tech Provider

Bigyan ng memory ang inyong AI agent: anim na buwan ng WhatsApp chats at contacts

Sa naka-connect na numero sa pamamagitan ng Coexistence, maaaring ipadala ng Meta sa inyong server ang contacts ng app at hanggang 180 araw ng one-to-one chats, isang beses lamang, basta may naka-save na direct webhook destination sa loob ng 24 na oras mula nang mag-connect at pumayag ang negosyo sa app. Maaaring dumating nang wala sa ayos ang chunks, at ang progress na 100 ang senyales ng katapusan. I-store ang mga mensahe ayon sa id, itala ang mga tao ayon sa BSUID, at ipasa sa agent ang pinakahuling turn.

easyCoexistence ikinokonekta ang numero sa pamamagitan ng daloy ng Coexistence ng Meta at, kapag na-save ninyo ang endpoint bilang direct webhook destination sa loob ng 24 na oras, humihingi ito sa Meta nang isang beses para sa contacts at hanggang 180 araw ng chats, na direktang ipinapadala sa inyong server.

180 days

Hanggang saan umaabot ang history sync mula sa onboarding; ayon sa feature table ng Meta, ang pinakabagong 6 na buwan.

24 hours

Oras pagkatapos ng onboarding para humiling ng contacts at history; isang beses lang maaaring gawin ang bawat request.

100

Halaga ng metadata.progress na nagmamarka sa history sync bilang kumpleto; sabi ng Meta, hindi sapat ang phase lamang.

2593109

Error code sa history webhook kapag pinatay ng negosyo ang history sharing sa WhatsApp Business app.

3 phases

Phase 0 ang araw 0 hanggang 1 bago ang onboarding, phase 1 ang araw 1 hanggang 90, at phase 2 ang araw 90 hanggang 180.

3 MB

Pinakamalaking webhook payload na ipinapadala ng Meta, na nagtatakda ng body size limit na kailangan ng inyong endpoint.

Ano ang dinadala ng import, at ano ang naiiwan?

Dalawang daloy ito, parehong mula sa WhatsApp Business app sa telepono. Dumarating ang contacts bilang smb_app_state_sync webhooks, isang entry bawat contact na may action na add o remove, at ang parehong field ay nag-uulat din ng mga contact na idinadagdag, ina-edit, o tinatanggal ng negosyo sa app pagkatapos. Dumarating ang chats bilang history webhooks: one-to-one na usapan hanggang 180 araw bago ang onboarding, sa magkabilang direksyon, kasama ang delivery status ng bawat isa. Nakalista sa ibaba ang hindi kasama sa import, kaya dapat hindi ito asahan ng memory na binuo mula sa import.

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

Paano masisigurong makararating sa server ninyo ang import?

Ihanda po muna ang endpoint bago mag-connect ang numero, saka i-save ito bilang direct webhook destination ng numero sa loob ng 24 na oras mula nang mag-connect: sa pahina ng numero, sa ilalim ng Ipadala ang mga papasok na mensahe sa sariling webhook, gamit ang set_webhook_destination mula sa inyong AI, o bilang webhook_url sa isang Partner API connect session. Ang pag-save nito ang nagpapahintulot sa easyCoexistence na humiling ng sync sa Meta, una ang contacts at saka ang history, isang beses bawat onboarding. Lalabas ang request at ang mga request id ng Meta sa event log ng numero bilang history_sync_requested.

Dapat pumayag ang negosyo na ibahagi ang history kapag itinanong ito ng app habang nagko-connect. Hindi makakakuha ng import ang numerong ang mga mensahe ay dumadaan sa easyCoexistence (Through easyCoexistence sa card na Where incoming messages go), kahit may Forward URL, dahil ginagawa lamang ang request para sa direct destination. Kung kakailanganin ninyo ang automations sa susunod, i-switch ito pagkatapos matapos ang import.

Paano dumarating ang history chunks?

Wala sa ayos, sa mga phase na nagsisimula sa pinakabagong mensahe pabalik: phase 0 ang huling araw bago ang onboarding, phase 1 hanggang araw 90, at phase 2 hanggang araw 180. I-sort gamit ang metadata.chunk_order kung mahalaga ang pagkakasunod, at ituring na katapusan ang metadata.progress = 100, dahil sabi ng Meta na hindi nasasabi ng phase kung tapos na ang isang phase. Ang id ng usapan ay numero ng telepono ng customer, na iniiwan kapag hindi ito maibabahagi, at ang context nito ay may wa_id, user_id, at username. Ang mensaheng ipinadala ng negosyo ay may from na nakatakda sa numero ng negosyo at isang field na 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" }
        }
      ]
    }]
  }]
}

Paano dapat itago ang memory ng agent?

Sapat na ang dalawang table. Naka-key ang mga tao sa BSUID, ang user_id na idinadagdag ng Meta sa contacts, usapan, at mensahe, kasama ang numero ng telepono sa tabi nito, dahil maaaring dumating ang user na may username nang walang numero; sabi mismo ng reference ng Meta, gamitin ang user_id para matukoy ang contact. Naka-key ang mga mensahe sa kanilang wamid, kaya nagiging iisang row ang import, mga live webhook, at mga retry ng iisang mensahe, at tinatala ng flag na from_business kung sino ang nagsalita. I-index ayon sa tao at oras, dahil hinihingi ng agent ang pinakahuling turn ng isang tao.

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

Paano i-load ang chunks at contacts dito?

Gamit ang idempotent inserts, para hindi na mahalaga ang ayos o ang muling pagdating. Binabasa ng ingestHistory ang isang history change: nagtatala ito ng 2593109 decline at lumilipat na, itinatali ang usapan sa context.user_id o sa id nito, minamarkahan ang mensahe bilang galing sa negosyo kapag ang from ay katumbas ng metadata.display_phone_number, at nag-iimbak ng placeholder na [type] kapag walang teksto. Nag-a-upsert ang ingestContacts sa user_id o numero ng telepono, at minamarkahan ang mga tinanggal na contact sa halip na burahin ang mensahe nila. Tawagin ang mga ito gamit ang change.value sa direct destination, o ang value ng body kapag ang event ng forward ay history o 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 };
}

Paano pinapakain ang memory na ito sa agent?

May hangganan, hindi lahat nang sabay-sabay. Ibinabalik ng memoryFor ang pangalan ng tao mula sa address book at ang huling 20 turn, mula sa pinakalumang papunta sa pinakabago, na nagsisimula sa turn ng customer gaya ng inaasahan ng karamihan sa chat API; magdagdag ng nakaimbak na summary ng mas lumang usapan kung kailangan pa ng agent. Ang anim na buwang chats sa bawat prompt ay nagpapataas ng gastos sa tokens sa bawat sagot at nagtatabon sa tanong na itinatanong.

Para sa paghahambing, ang built-in na Reply with AI step ay bumabasa ng hanggang 20 naunang mensahe (10 bilang default), at ang Call my webhook step ay nagpapadala ng huling 10. Pareho silang gumagamit ng teksto na itinago sa loob ng retention na pinipili ng may-ari, 30, 90 o 365 araw (90 bilang default), mula sa sandaling naka-on ang automations, kaya kailangang nasa sarili ninyong database ang anim na buwang imported na chat.

Paano nananatiling updated ang memory pagkatapos ng import?

Patuloy na tumatanggap ang parehong destination ng live na daloy: mga mensahe mula sa customer, smb_message_echoes para sa mga sagot na tina-type sa app, at smb_app_state_sync kapag ina-edit ng negosyo ang contacts nito. Ipasok ang mga ito sa parehong table gamit ang source na live o echo. Kapag nagpalit ng numero ng telepono ang customer, nagpapadala ang Meta ng system na mensahe na may type na user_changed_number o user_changed_user_id at previous_user_id, na senyales para ilipat ninyo ang mga row nila sa bagong BSUID.

Ang pag-on ng automations sa hinaharap ay nag-aalis ng direct destination. Idagdag ang parehong URL bilang Forward URL at basahin ang event at value mula sa bawat naka-sign na POST, at hintayin ang progress 100 bago mag-switch, dahil kung hindi, ang natitirang chunks ay darating lamang sa pamamagitan ng forward na iyon.

Paano ito i-set up

  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.

Mga karaniwang pagkakamali

  • Pag-save ng destination sa ikalawang araw. Hinihiling lamang ang sync sa loob ng 24 na oras mula sa pag-connect, kaya ang endpoint na na-save nang mas huli ay live na mensahe lamang ang makukuha.
  • I-on ang automations bago umabot sa progress na 100. Agad na inaalis ang direct destination, at darating lamang ang susunod na chunks kung may Forward URL na naka-set.
  • Pagtrato sa phase 2 bilang katapusan ng import. Ang metadata.progress = 100 lamang ang nagsasabing kumpleto na ang sync, at hindi sunud-sunod ang pagdating ng chunks.
  • Pag-key ng memory sa numero ng telepono lamang. Nawawala ang numero ng telepono sa mga id ng usapan at contact kapag hindi ito maibahagi ng user na may username, samantalang nananatili ang user_id.
Ginagawa ito gamit ang EasyCoexistence

Nakatala sa event log ng numero ang request, at 24/7 na pagmo-monitor ang susunod. US$ 9 hanggang US$ 0.75 kada numero kada buwan, bumababa habang dumarami ang mga numero, na may free trial na unang 3 araw.

Mga madalas itanong

Maaari bang tumakbo ulit ang import?

Sa pamamagitan lamang ng bagong onboarding. Isang request kada onboarding ang pinapayagan ng Meta, kaya kailangang i-disconnect at i-connect muli ang numero, at darating muli ang chats. Ang pag-insert ayon sa id ng mensahe ang pumipigil na madoble ang anumang bagay sa ikalawang pagtakbo.

Nagtatago ba ang easyCoexistence ng kopya ng mga na-import na chats?

Hindi. Ang history at contacts ay dumadaan mula sa Meta diretso sa inyong endpoint at hindi itinatago bilang default. Para sa numerong may naka-on na automations, itinatago ng easyCoexistence ang teksto ng mensahe sa loob ng panahong pipiliin ninyo, 30, 90 o 365 araw (90 bilang default), at ipinapakita ito ng Conversations screen; ang mga forwarded delivery ay itinatago hanggang 7 araw, at ang run logs sa loob ng 30 araw.

Gaano kalaki ang maaaring maging payload?

Hanggang 3 MB ang kayang dalhin ng isang Meta webhook, at maraming history chunks ang ipinapadala ng abalang numero. Itaas ang body limit ng inyong framework (ang default ng Express ay 100 kb) at kumpirmahin ang pagtanggap bago magsulat sa database.

Kailangan ba ng agent ang import para gumana?

Hindi. Kung wala ito, magsisimula ang memory sa unang mensaheng dumating pagkatapos ng pag-connect at lumalaki mula sa live na daloy. Mahalaga ang import kapag dapat hubugin ng mga nakaraang usapan ang mga sagot mula sa unang araw, halimbawa ang huling order ng isang bumabalik na customer.

Magpatuloy sa pagbabasa

Handa na po ba kayong magsimula?

I-set up ang WhatsApp Coexistence sa loob ng ilang minuto, hindi buwan. Patuloy na gumagana ang app sa telepono.

Magsimula ng Libreng Trial

Na-verify noong