Giriş yapınÜcretsiz denemeyi başlatın
Meta Tech Provider

Yapay zekâ ajanınıza hafıza verin: altı aylık WhatsApp sohbetleri ve kişiler

Coexistence ile bağlanan bir numarada Meta, bağlantıdan sonraki 24 saat içinde doğrudan webhook hedefi kaydedilmişse ve işletme uygulamada onaylamışsa, uygulamanın kişilerini ve birebir sohbetlerin en fazla 180 günlüğünü tek seferde sunucunuza gönderebilir. Parçalar sırasız gelebilir; ilerleme 100 bitişi gösterir. Mesajları id'ye göre kaydedin, kişileri BSUID ile tutun ve ajana son turları iletin.

easyCoexistence, numarayı Meta'nın Coexistence akışıyla bağlar ve uç noktanızı bağlantıdan sonraki 24 saat içinde doğrudan webhook hedefi olarak kaydettiğinizde, kişiler ve en fazla 180 günlük sohbetler için Meta'dan bir kez istekte bulunur; bunlar doğrudan sunucunuza gider.

180 days

Onboarding'den geriye doğru geçmiş senkronizasyonunun kapsadığı süre; Meta'nın özellik tablosu bunu en son 6 ay olarak belirtir.

24 hours

Onboarding'den sonra kişi ve geçmiş isteğinin yapılabileceği süre; her istek yalnızca bir kez yapılabilir.

100

Geçmiş senkronizasyonunun tamamlandığını gösteren metadata.progress değeri; Meta, yalnızca phase değerinin bunu göstermediğini belirtir.

2593109

İşletme WhatsApp Business uygulamasında geçmiş paylaşımını kapattığında, geçmiş webhook'unda görünen hata kodu.

3 phases

Faz 0 onboarding öncesi 0. ile 1. günü, faz 1 1. ile 90. günü, faz 2 ise 90. ile 180. günü kapsar.

3 MB

Meta'nın gönderdiği en büyük webhook payload'ı; uç noktanızın ihtiyaç duyduğu gövde boyutu sınırını belirler.

Geçmişten ne gelir, ne geride kalır?

İki akış var; ikisi de telefondaki WhatsApp Business uygulamasından gelir. Kişiler, kişi başına bir giriş olacak şekilde action değeri add veya remove olan smb_app_state_sync webhook'ları olarak gelir; aynı alan, işletmenin sonradan uygulamada eklediği, düzenlediği veya sildiği kişileri de bildirmeye devam eder. Sohbetler geçmiş webhook'ları olarak gelir: onboarding'den önceki 180 güne kadar olan birebir konuşmalar, iki yönlü ve teslim durumlarıyla birlikte. Aşağıda listelenen şeyler aktarılmaz; bu yüzden içe aktarıma dayalı hafıza bunları beklememelidir.

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

İçe aktarımın sunucunuza ulaştığından nasıl emin olursunuz?

Uç noktanızı numara bağlanmadan önce canlıya alın, sonra bağlantıdan itibaren 24 saat içinde numaranın doğrudan webhook hedefi olarak kaydedin: numaranın sayfasında Gelen mesajları kendi webhook'unuza yönlendir altında, yapay zekânızdan set_webhook_destination ile ya da bir Partner API bağlanma oturumunda webhook_url olarak. Bunu kaydetmek, easyCoexistence'ın Meta'dan senkronizasyonu istemesini sağlar; önce kişiler, sonra geçmiş, onboarding başına bir kez. İstek ve Meta'nın istek kimlikleri, numaranın olay günlüğünde history_sync_requested olarak görünür.

İşletme, bağlantı sırasında uygulama sorduğunda geçmişi paylaşmayı kabul etmelidir. Mesajları easyCoexistence üzerinden gelen bir numara (Gelen mesajların gittiği yer kartında easyCoexistence üzerinden), Forward URL olsa bile içe aktarma almaz, çünkü istek yalnızca doğrudan hedef için yapılır. Sonradan otomasyonlara ihtiyacınız olursa, içe aktarım bittikten sonra geçiş yapın.

Geçmiş parçaları nasıl gelir?

Sırasız, en yeni mesajdan geriye doğru ilerleyen fazlar halinde: faz 0 onboarding öncesindeki son günü, faz 1 90. güne kadarı, faz 2 ise 180. güne kadarı kapsar. Sıra önemliyse metadata.chunk_order ile sıralayın; metadata.progress = 100 değerini bitiş olarak kabul edin, çünkü Meta, fazın bittiğini faz değerinin kendisinden anlaşılamayacağını not eder. Bir sohbetin id'si müşterinin telefon numarasıdır; paylaşılamadığında boş bırakılır ve context alanı wa_id, user_id ve username taşır. İşletmenin gönderdiği bir mesajda from, işletmenin numarasına ayarlanır ve bir to alanı bulunur.

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" }
        }
      ]
    }]
  }]
}

Bir yapay zekâ ajanının hafızası nasıl saklanmalı?

İki tablo yeterlidir. Kişiler, Meta'nın kişilere, sohbetlere ve mesajlara eklediği user_id ile BSUID'ye göre anahtarlanır; telefon numarası yanlarında tutulur, çünkü username'i olan bir kullanıcı numarasız gelebilir. Meta'nın kendi referansı, bir kişiyi tanımlamak için user_id kullanılmasını söyler. Mesajlar wamid'lerine göre anahtarlanır; böylece içe aktarım, canlı webhook'lar ve yeniden denenen aynı mesajın teslimleri tek satırda birleşir ve from_business bayrağı kimin konuştuğunu kaydeder. Kişiye ve zamana göre indeksleyin, çünkü ajan bir kişinin en son turlarını ister.

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

Parçaları ve kişileri ona nasıl yüklersiniz?

Idempotent ekleme ile; böylece sıra ve yeniden teslim artık önemli olmaz. ingestHistory tek bir geçmiş değişikliğini okur: 2593109 reddini kaydeder ve geçer, bir sohbeti context.user_id ya da id ile anahtarlar, bir mesajı from, metadata.display_phone_number'a eşitse işletmenin mesajı olarak işaretler ve metin yoksa bir [type] yer tutucusu saklar. ingestContacts, user_id ya da telefon numarasına göre upsert yapar ve silinen kişileri, mesajlarını silmeden işaretler. Bunları doğrudan hedefte change.value ile, ya da yönlendirmenin olayı history veya smb_app_state_sync olduğunda gövdedeki value ile çağırın.

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

Bu hafızayı ajana nasıl beslersiniz?

Sınırlı olarak, asla hepsini birden değil. memoryFor, kişinin adres defterindeki adını ve en son 20 turunu, en eskiden en yeniye, çoğu sohbet API'sinin beklediği gibi bir müşteri turuyla başlayarak döndürür; ajanın daha fazlasına ihtiyacı varsa eski konuşmaların saklı bir özetini ekleyin. Her yanıtta altı aylık sohbetler token harcar ve sorulan soruyu gömer.

Karşılaştırma için: yerleşik Yapay zekâyla yanıtla adımı en fazla 20 önceki mesajı okur (varsayılan 10), Webhook'umu çağır adımı ise son 10'u gönderir. İkisi de, sahibin seçtiği saklama süresince tutulan metinden yararlanır: 30, 90 veya 365 gün (varsayılan 90), otomasyonlar açıldığı andan itibaren; bu yüzden içe aktarılan altı aylık sohbetlerin kendi veritabanınızda yaşaması gerekir.

İçe aktarımdan sonra hafıza nasıl güncel kalır?

Aynı hedef canlı trafiği almaya devam eder: kullanıcılardan gelen mesajlar, uygulamada yazılan yanıtlar için smb_message_echoes ve işletme kişilerini düzenlediğinde smb_app_state_sync. Bunları aynı tablolara source değeri live veya echo ile ekleyin. Bir müşteri telefon numarasını değiştirdiğinde Meta, previous_user_id içeren user_changed_number veya user_changed_user_id tipinde bir sistem mesajı gönderir; bu, satırlarını yeni BSUID'ye taşımanız için bir işarettir.

Otomasyonları sonradan açmak doğrudan hedefi kaldırır. Aynı URL'yi Forward URL olarak ekleyin, her imzalı POST'tan event ve value alanlarını okuyun ve geçişten önce progress 100 değerini bekleyin; aksi halde kalan parçalar yalnızca o yönlendirme üzerinden ulaşır.

Nasıl kurulur

  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.

Yaygın hatalar

  • İkinci günde hedefi kaydetmek. Senkronizasyon yalnızca bağlantıdan sonraki 24 saat içinde istenir; bundan sonra kaydedilen uç nokta yalnızca canlı mesajlarla başlar.
  • İlerleme 100'e ulaşmadan otomasyonları açmak. Doğrudan hedef hemen kaldırılır ve sonraki parçalara yalnızca önceden bir Forward URL ayarlıysa ulaşırsınız.
  • Faz 2'yi içe aktarımın sonu sanmak. Senkronizasyonun tamamlandığını yalnızca metadata.progress = 100 söyler ve parçalar sırayla teslim edilmez.
  • Hafızayı yalnızca telefon numarasına göre anahtarlamak. Kullanıcı username'ini paylaşamadığında sohbet id'leri ve kişiler telefon numarasını düşürür, oysa user_id yine mevcuttur.
Bunu EasyCoexistence'la yapmak

İstek numaranın olay günlüğüne kaydedilir ve numara sonrasında 7/24 izlenir. Numara başına aylık US$ 9'dan US$ 0.75'e kadar düşer, numara eklendikçe azalır; ilk 3 gün ücretsizdir.

Sık sorulan sorular

Geçmiş içe aktarımı ikinci kez çalışabilir mi?

Yalnızca yeni bir onboarding ile. Meta her onboarding için bir istek kabul eder; bu yüzden numara bağlantısı kesilip yeniden bağlanmalıdır ve sohbetler yeniden gelir. Mesaj id'sine göre ekleme yapmak, ikinci geçişin hiçbir şeyi iki kez eklemesini engeller.

easyCoexistence içe aktarılan sohbetlerin bir kopyasını tutar mı?

Hayır. Geçmiş ve kişiler Meta'dan doğrudan uç noktanıza gider ve varsayılan olarak saklanmaz. Otomasyonları açık bir numara için easyCoexistence, mesaj metnini seçtiğiniz süre boyunca tutar: 30, 90 veya 365 gün (varsayılan 90); Konuşmalar ekranı da bunu gösterir. İletilen teslimatlar en fazla 7 gün, çalıştırma günlükleri ise 30 gün saklanır.

Payload'lar ne kadar büyüyebilir?

Tek bir Meta webhook'u 3 MB'a kadar taşıyabilir ve yoğun bir numara çok sayıda geçmiş parçası gönderir. Framework'ünüzün gövde sınırını yükseltin (Express varsayılanı 100 kb) ve veritabanına yazmadan önce isteğin alındığını onaylayın.

Ajanın çalışması için içe aktarım gerekir mi?

Hayır. Bu olmadan hafıza, bağlandıktan sonraki ilk mesajla başlar ve canlı trafikle büyür. İçe aktarım, geçmiş konuşmaların ilk günden cevapları şekillendirmesi gerektiğinde önem kazanır; örneğin geri dönen bir müşterinin son siparişi gibi.

Okumaya devam edin

Başlamaya hazır mısınız?

WhatsApp Coexistence'ı aylar değil, dakikalar içinde kurun. Uygulama telefonda çalışmaya devam eder.

Ücretsiz denemeyi başlatın

Doğrulama tarihi