Log masukMulakan percubaan percuma
Meta Tech Provider

Beri ejen AI anda ingatan: enam bulan sembang dan kenalan WhatsApp

Pada nombor yang disambungkan melalui Coexistence, Meta boleh menghantar kenalan aplikasi dan sehingga 180 hari sembang individu ke pelayan anda, sekali sahaja, jika destinasi webhook terus disimpan dalam masa 24 jam selepas sambungan dan perniagaan bersetuju dalam aplikasi. Ketulan boleh tiba tidak mengikut susunan dan kemajuan 100 menandakan akhir. Simpan mesej mengikut id, kenal pasti individu melalui BSUID, dan sediakan giliran terkini untuk ejen.

easyCoexistence menyambungkan nombor melalui aliran Coexistence Meta dan, apabila anda menyimpan endpoint anda sebagai destinasi webhook terus dalam masa 24 jam, meminta Meta sekali untuk kenalan dan sehingga 180 hari sembang, yang dihantar terus ke pelayan anda.

180 days

Sejauh mana sejarah penyegerakan kembali dari selepas pendaftaran; jadual ciri Meta menyebutnya enam bulan terkini.

24 hours

Masa selepas pendaftaran untuk meminta kenalan dan sejarah; setiap permintaan hanya boleh dibuat sekali.

100

Nilai metadata.progress yang menandakan penyegerakan sejarah selesai; Meta menyatakan fasa sahaja tidak mencukupi.

2593109

Kod ralat dalam webhook sejarah apabila perniagaan mematikan perkongsian sejarah dalam aplikasi WhatsApp Business.

3 phases

Fasa 0 meliputi hari 0 hingga 1 sebelum pendaftaran, fasa 1 hari 1 hingga 90, fasa 2 hari 90 hingga 180.

3 MB

Payload webhook terbesar yang dihantar Meta, yang menetapkan had saiz badan yang diperlukan oleh endpoint anda.

Apa yang dibawa import, dan apa yang tinggal?

Dua aliran, kedua-duanya dari aplikasi WhatsApp Business pada telefon. Kenalan tiba sebagai webhook smb_app_state_sync, satu entri bagi setiap kenalan dengan tindakan add atau remove, dan medan yang sama turut melaporkan kenalan yang kemudian ditambah, disunting atau dibuang oleh perniagaan dalam aplikasi. Sembang tiba sebagai webhook sejarah: perbualan individu dari sehingga 180 hari sebelum pendaftaran, dalam kedua-dua arah, bersama status penghantaran. Perkara yang tidak dibawa masuk disenaraikan di bawah, jadi ingatan yang dibina daripada import tidak sepatutnya menjangkakannya.

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

Bagaimana anda memastikan import sampai ke pelayan anda?

Pastikan endpoint sudah aktif sebelum nombor disambungkan, kemudian simpannya sebagai destinasi webhook terus bagi nombor itu dalam masa 24 jam selepas sambungan: pada halaman nombor di bawah Hala mesej masuk ke webhook anda sendiri, dengan set_webhook_destination daripada AI anda, atau sebagai webhook_url pada sesi sambungan Partner API. Menyimpannya menjadikan easyCoexistence meminta penyegerakan daripada Meta, kenalan dahulu dan kemudian sejarah, sekali bagi setiap pendaftaran; permintaan dan id permintaan Meta muncul dalam log peristiwa nombor sebagai history_sync_requested.

Perniagaan mesti bersetuju berkongsi sejarah apabila aplikasi memintanya semasa sambungan. Nombor yang mesejnya melalui easyCoexistence (Melalui easyCoexistence dalam kad Ke mana mesej masuk pergi), walaupun dengan Forward URL, tidak mendapat import, kerana permintaan hanya dibuat untuk destinasi terus. Jika anda memerlukan Automations kemudian, tukar selepas import tamat.

Bagaimana ketulan sejarah tiba?

Tidak mengikut susunan, dalam fasa yang berjalan dari mesej terbaru ke belakang: fasa 0 meliputi hari terakhir sebelum pendaftaran, fasa 1 sehingga hari 90 dan fasa 2 sehingga hari 180. Susun mengikut metadata.chunk_order jika susunan penting, dan anggap metadata.progress = 100 sebagai akhir, kerana Meta menyatakan fasa tidak memberitahu anda bahawa sesuatu fasa telah selesai. Id perbualan ialah nombor telefon pelanggan, ditinggalkan apabila ia tidak boleh dikongsi, dan kontekstnya membawa wa_id, user_id dan username. Mesej yang dihantar perniagaan mempunyai from ditetapkan kepada nombor perniagaan dan medan 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" }
        }
      ]
    }]
  }]
}

Bagaimana ingatan ejen patut disimpan?

Dua jadual sudah memadai. Individu dikenal pasti mengikut BSUID, iaitu user_id yang Meta tambah kepada kenalan, perbualan dan mesej, dengan nombor telefon disimpan di sebelahnya, kerana pengguna yang mempunyai username boleh tiba tanpa nombor; rujukan Meta sendiri menyatakan gunakan user_id untuk mengenal pasti kenalan. Mesej dikunci mengikut wamid mereka, supaya import, webhook langsung dan penghantaran semula bagi mesej yang sama bergabung menjadi satu baris, dan bendera from_business merekodkan siapa yang bercakap. Indeks mengikut orang dan masa, kerana ejen meminta giliran terkini seseorang.

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

Bagaimana ketulan dan kenalan dimuatkan ke dalamnya?

Dengan sisipan idempoten, supaya susunan dan penghantaran semula tidak lagi penting. ingestHistory membaca satu perubahan sejarah: ia mencatatkan penolakan 2593109 dan meneruskan, mengenal pasti perbualan melalui context.user_id atau id-nya, menandakan mesej sebagai milik perniagaan apabila from sama dengan metadata.display_phone_number, dan menyimpan pemegang tempat [type] apabila tiada teks. ingestContacts melakukan upsert mengikut user_id atau nombor telefon dan menandakan kenalan yang dibuang dan bukannya memadam mesej mereka. Panggil dengan change.value pada destinasi terus, atau dengan value badan apabila peristiwa forward ialah history atau 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 };
}

Bagaimana ingatan itu dibekalkan kepada ejen?

Terhad, jangan sekali gus. memoryFor memulangkan nama orang itu dari buku alamat dan 20 giliran terakhirnya, paling lama dahulu, bermula dengan giliran pelanggan seperti yang dijangka kebanyakan API sembang; tambah ringkasan tersimpan bagi perbualan lama jika ejen memerlukan lebih. Enam bulan sembang dalam setiap prompt menelan token pada setiap balasan dan menenggelamkan soalan yang sedang ditanya.

Sebagai perbandingan, langkah Balas dengan AI terbina dalam membaca paling banyak 20 mesej terdahulu (10 secara lalai), dan langkah Panggil webhook saya menghantar 10 terakhir. Kedua-duanya menggunakan teks yang disimpan selama tempoh simpanan yang dipilih pemilik, 30, 90 atau 365 hari (90 secara lalai), dari saat Automations dihidupkan, itulah sebabnya enam bulan sembang yang diimport mesti tinggal dalam pangkalan data anda sendiri.

Bagaimana ingatan kekal terkini selepas import?

Destinasi yang sama terus menerima trafik langsung: mesej daripada pelanggan, smb_message_echoes untuk balasan yang ditaip dalam aplikasi, dan smb_app_state_sync apabila perniagaan menyunting kenalannya. Masukkan melalui jadual yang sama dengan source live atau echo. Apabila pelanggan menukar nombor telefon, Meta menghantar mesej sistem jenis user_changed_number atau user_changed_user_id dengan previous_user_id, isyarat untuk anda memindahkan barisnya ke BSUID baharu.

Menghidupkan Automations kemudian membuang destinasi terus. Tambah URL yang sama sebagai Forward URL dan baca event serta value daripada setiap POST yang ditandatangani, dan tunggu progress 100 sebelum bertukar, atau ketulan yang tinggal hanya sampai kepada anda melalui forward itu.

Cara menetapkannya

  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.

Kesilapan biasa

  • Menyimpan destinasi pada hari kedua. Penyegerakan hanya diminta dalam masa 24 jam selepas sambungan, jadi endpoint yang disimpan lewat hanya bermula daripada mesej langsung.
  • Menghidupkan Automations sebelum progress mencapai 100. Destinasi terus dibuang serta-merta, dan ketulan kemudian hanya sampai kepada anda jika Forward URL sudah ditetapkan.
  • Menganggap fasa 2 sebagai akhir import. Hanya metadata.progress = 100 menyatakan penyegerakan selesai, dan ketulan tidak dihantar mengikut urutan.
  • Menjadikan nombor telefon sebagai satu-satunya kunci ingatan. Id perbualan dan kenalan kehilangan nombor telefon apabila pengguna yang mempunyai username tidak dapat berkongsinya, sedangkan user_id masih ada.
Menggunakan EasyCoexistence untuk ini

Permintaan direkodkan dalam log peristiwa nombor, dan nombor itu dipantau 24/7 selepas itu. Daripada US$ 9 hingga US$ 0.75 setiap nombor yang disambungkan sebulan, menurun apabila anda menambah nombor, dengan percubaan percuma 3 hari.

Soalan lazim

Bolehkah import dijalankan kali kedua?

Hanya melalui pendaftaran baharu. Meta membenarkan satu permintaan bagi setiap pendaftaran, jadi nombor itu perlu diputuskan dan disambungkan semula, dan sembang kemudian tiba semula; sisipan mengikut id mesej memastikan laluan kedua tidak menambah apa-apa dua kali.

Adakah easyCoexistence menyimpan salinan sembang yang diimport?

Tidak. Sejarah dan kenalan pergi dari Meta terus ke endpoint anda dan tidak disimpan secara lalai. Bagi nombor yang mempunyai Automations dihidupkan, easyCoexistence menyimpan teks mesej selama tempoh yang anda pilih, 30, 90 atau 365 hari (90 secara lalai), dan skrin Conversations memaparkannya; penghantaran yang dimajukan disimpan sehingga 7 hari, dan log larian selama 30 hari.

Seberapa besar muatan boleh menjadi?

Satu webhook Meta boleh membawa sehingga 3 MB, dan nombor yang sibuk menghantar banyak ketulan sejarah. Naikkan had badan rangka kerja anda (Express lalai kepada 100 kb) dan sahkan penerimaan sebelum menulis ke pangkalan data.

Adakah ejen memerlukan import untuk berfungsi?

Tidak. Tanpanya, ingatan bermula dengan mesej pertama selepas sambungan dan berkembang daripada trafik langsung. Import penting apabila perbualan lampau patut membentuk jawapan dari hari pertama, seperti tempahan terakhir pelanggan yang kembali.

Teruskan membaca

Sedia untuk bermula?

Sediakan WhatsApp Coexistence dalam beberapa minit, bukan berbulan-bulan. Aplikasi terus berfungsi pada telefon.

Mulakan Percubaan Percuma

Disahkan pada