MasukMulai uji coba gratis
Meta Tech Provider

Beri agen AI Anda memori: enam bulan chat dan kontak WhatsApp

Pada nomor yang terhubung melalui Coexistence, Meta dapat mengirim kontak aplikasi dan hingga 180 hari chat satu-ke-satu ke server Anda, sekali saja, jika tujuan webhook langsung disimpan dalam 24 jam setelah terhubung dan bisnis menyetujuinya di aplikasi. Potongan dapat tiba tidak berurutan, dan progres 100 menandai akhir. Simpan pesan berdasarkan id, identifikasi orang dengan BSUID, dan berikan percakapan terbaru ke agen.

easyCoexistence menghubungkan nomor melalui alur Coexistence dari Meta dan, ketika Anda menyimpan endpoint sebagai tujuan webhook langsung dalam 24 jam, meminta Meta satu kali untuk kontak dan hingga 180 hari chat, yang langsung dikirim ke server Anda.

180 days

Seberapa jauh sinkronisasi riwayat menjangkau ke belakang sejak onboarding; tabel fitur Meta menyebutnya 6 bulan terakhir.

24 hours

Waktu setelah onboarding untuk meminta kontak dan riwayat; setiap permintaan hanya dapat dibuat sekali.

100

Nilai metadata.progress yang menandai sinkronisasi riwayat selesai; Meta menyatakan fase saja tidak cukup.

2593109

Kode kesalahan dalam webhook riwayat ketika bisnis mematikan berbagi riwayat di aplikasi WhatsApp Business.

3 phases

Fase 0 mencakup hari 0 hingga 1 sebelum onboarding, fase 1 hari 1 hingga 90, fase 2 hari 90 hingga 180.

3 MB

Payload webhook terbesar yang dikirim Meta, yang menentukan batas ukuran body yang dibutuhkan endpoint Anda.

Apa yang dibawa impor, dan apa yang tertinggal?

Dua aliran, keduanya dari aplikasi WhatsApp Business di ponsel. Kontak tiba sebagai webhook smb_app_state_sync, satu entri per kontak dengan action add atau remove, dan field yang sama juga terus melaporkan kontak yang kemudian ditambahkan, diubah, atau dihapus bisnis di aplikasi. Chat tiba sebagai webhook history: percakapan satu-ke-satu hingga 180 hari sebelum onboarding, dalam kedua arah, beserta status pengirimannya. Apa saja yang tidak ikut terbawa tercantum di bawah, jadi memori yang dibangun dari impor tidak boleh mengharapkannya.

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 memastikan impor sampai ke server Anda?

Pastikan endpoint sudah aktif sebelum nomor terhubung, lalu simpan sebagai tujuan webhook langsung nomor itu dalam 24 jam setelah terhubung: di halaman nomor pada bagian Route incoming messages to your own webhook, dengan set_webhook_destination dari AI Anda, atau sebagai webhook_url pada sesi koneksi Partner API. Penyimpanan inilah yang membuat easyCoexistence meminta sinkronisasi ke Meta, kontak lebih dulu lalu riwayat, satu kali per onboarding; permintaan beserta id permintaan dari Meta muncul di log event nomor sebagai history_sync_requested.

Bisnis harus menyetujui berbagi riwayat saat aplikasi menanyakannya selama proses koneksi. Nomor yang pesannya masuk lewat easyCoexistence (Through easyCoexistence pada kartu Where incoming messages go), bahkan dengan Forward URL, tidak mendapat impor, karena permintaan hanya dibuat untuk tujuan langsung. Jika nanti Anda membutuhkan automations, beralihlah setelah impor selesai.

Bagaimana potongan riwayat tiba?

Tidak berurutan, dalam fase yang berjalan dari pesan terbaru mundur ke belakang: fase 0 mencakup hari terakhir sebelum onboarding, fase 1 hingga hari ke-90, dan fase 2 hingga hari ke-180. Urutkan berdasarkan metadata.chunk_order jika urutan penting, dan anggap metadata.progress = 100 sebagai akhir, karena Meta mencatat bahwa fase tidak menandakan suatu fase sudah selesai. Id percakapan adalah nomor telepon pelanggan, dikosongkan jika tidak dapat dibagikan, dan context-nya memuat wa_id, user_id, dan username. Pesan yang dikirim bisnis memiliki from berisi nomor bisnis dan sebuah field 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 sebaiknya memori agen disimpan?

Dua tabel sudah cukup. Orang diidentifikasi dengan BSUID, yaitu user_id yang ditambahkan Meta pada kontak, percakapan, dan pesan, dengan nomor telepon disimpan di sampingnya, karena pengguna dengan username bisa datang tanpa nomor; referensi Meta sendiri menyarankan memakai user_id untuk mengidentifikasi kontak. Pesan memakai wamid sebagai kunci, sehingga impor, webhook langsung, dan pengiriman ulang pesan yang sama menyatu menjadi satu baris, dan penanda from_business mencatat siapa yang berbicara. Buat indeks berdasarkan orang dan waktu, karena agen meminta percakapan terbaru dari satu orang.

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 memuat potongan dan kontak ke dalamnya?

Dengan insert idempoten, sehingga urutan dan pengiriman ulang tidak lagi berpengaruh. ingestHistory membaca satu perubahan riwayat: ia mencatat penolakan 2593109 lalu melanjutkan, menentukan kunci percakapan dari context.user_id atau id-nya, menandai pesan sebagai milik bisnis ketika from sama dengan metadata.display_phone_number, dan menyimpan placeholder [type] ketika tidak ada teks. ingestContacts melakukan upsert berdasarkan user_id atau nomor telepon dan menandai kontak yang dihapus, bukan menghapus pesannya. Panggil keduanya dengan change.value pada tujuan langsung, atau dengan value dari body ketika event forward berupa 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 memori itu diberikan ke agen?

Secukupnya, jangan sekaligus. memoryFor mengembalikan nama orang dari buku alamat dan 20 pesan terakhirnya, dari yang terlama, diawali pesan pelanggan seperti yang diharapkan sebagian besar API chat; tambahkan ringkasan tersimpan dari percakapan lama jika agen membutuhkan lebih. Enam bulan chat di setiap prompt menghabiskan token pada setiap balasan dan mengaburkan pertanyaan yang sedang diajukan.

Sebagai pembanding, langkah Reply with AI bawaan membaca paling banyak 20 pesan sebelumnya (10 secara default), dan langkah Call my webhook mengirim 10 pesan terakhir. Keduanya mengambil dari teks yang disimpan selama retensi yang dipilih pemilik, 30, 90, atau 365 hari (90 secara default), sejak automations diaktifkan, itulah sebabnya enam bulan chat yang diimpor harus tersimpan di basis data Anda sendiri.

Bagaimana memori tetap mutakhir setelah impor?

Tujuan yang sama terus menerima lalu lintas langsung: pesan dari pelanggan, smb_message_echoes untuk balasan yang diketik di aplikasi, dan smb_app_state_sync ketika bisnis mengubah kontaknya. Masukkan semuanya melalui tabel yang sama dengan source live atau echo. Ketika pelanggan berganti nomor telepon, Meta mengirim pesan sistem bertipe user_changed_number atau user_changed_user_id dengan previous_user_id, sebagai tanda bagi Anda untuk memindahkan barisnya ke BSUID baru.

Menyalakan automations nanti akan menghapus tujuan langsung. Tambahkan URL yang sama sebagai Forward URL dan baca event serta value dari setiap POST yang ditandatangani, lalu tunggu progres 100 sebelum beralih, atau potongan yang tersisa hanya sampai kepada Anda melalui forward tersebut.

Cara mengonfigurasi

  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.

Kesalahan umum

  • Menyimpan tujuan pada hari kedua. Sinkronisasi hanya diminta dalam 24 jam setelah terhubung, sehingga endpoint yang disimpan lebih lambat hanya mulai dari pesan langsung.
  • Menyalakan automations sebelum progres mencapai 100. Tujuan langsung dihapus seketika, dan potongan berikutnya hanya sampai kepada Anda jika Forward URL sudah diatur.
  • Menganggap fase 2 sebagai akhir impor. Hanya metadata.progress = 100 yang menandakan sinkronisasi selesai, dan potongan tidak dikirim secara berurutan.
  • Menjadikan nomor telepon satu-satunya kunci memori. Id percakapan dan kontak kehilangan nomor telepon ketika pengguna dengan username tidak dapat membagikannya, sementara user_id tetap ada.
Melakukan ini dengan EasyCoexistence

Permintaan tercatat di log event nomor, dan nomor dipantau 24/7 setelahnya. US$ 9 turun hingga US$ 0.75 per nomor per bulan, makin turun seiring Anda menambah nomor, dengan 3 hari pertama gratis.

Pertanyaan yang sering diajukan

Apakah impor bisa dijalankan untuk kedua kalinya?

Hanya melalui onboarding baru. Meta mengizinkan satu permintaan per onboarding, sehingga nomor harus diputus lalu dihubungkan kembali, dan chat kemudian tiba lagi; melakukan insert berdasarkan id pesan mencegah putaran kedua menambahkan data yang sama dua kali.

Apakah easyCoexistence menyimpan salinan chat yang diimpor?

Tidak. Riwayat dan kontak berpindah dari Meta langsung ke endpoint Anda dan tidak disimpan secara default. Untuk nomor dengan automations yang aktif, easyCoexistence menyimpan teks pesan selama periode yang Anda pilih, 30, 90, atau 365 hari (90 secara default), dan layar Conversations menampilkannya; pengiriman yang diteruskan disimpan hingga 7 hari, dan log eksekusi 30 hari.

Seberapa besar payload bisa menjadi?

Satu webhook Meta dapat membawa hingga 3 MB, dan nomor yang sibuk mengirim banyak potongan riwayat. Naikkan batas body framework Anda (Express secara default 100 kb) dan kirim konfirmasi penerimaan sebelum menulis ke basis data.

Apakah agen membutuhkan impor agar bisa berfungsi?

Tidak. Tanpa impor, memori dimulai dari pesan pertama setelah terhubung dan tumbuh dari lalu lintas langsung. Impor berguna ketika percakapan masa lalu perlu memengaruhi jawaban sejak hari pertama, misalnya pesanan terakhir dari pelanggan yang kembali.

Lanjut membaca

Siap memulai?

Konfigurasikan WhatsApp Coexistence dalam hitungan menit, bukan bulan. Aplikasi tetap berfungsi di ponsel.

Mulai uji coba gratis

Diverifikasi pada