AnmeldenKostenlose Testphase starten
Meta Tech Provider

Gedächtnis für Ihren KI-Agenten: sechs Monate WhatsApp-Chats und Kontakte

Bei einer über Coexistence verbundenen Nummer kann Meta die Kontakte der App und bis zu 180 Tage Einzelchats einmalig an Ihren Server senden, wenn innerhalb von 24 Stunden nach der Verbindung ein direktes Webhook-Ziel gespeichert ist und das Unternehmen dies in der App zulässt. Chunks können in beliebiger Reihenfolge eintreffen, und Fortschritt 100 markiert das Ende. Speichern Sie Nachrichten nach ID, identifizieren Sie Personen über die BSUID und übergeben Sie dem Agenten die letzten Gesprächsbeiträge.

easyCoexistence verbindet die Nummer über den Coexistence-Ablauf von Meta und fragt bei Meta einmal die Kontakte und bis zu 180 Tage Chats an, wenn Sie Ihren Endpoint innerhalb von 24 Stunden als direktes Webhook-Ziel speichern; diese gelangen direkt auf Ihren Server.

180 days

Wie weit der History-Sync ab dem Onboarding zurückreicht; Metas Funktionstabelle nennt die jüngsten 6 Monate.

24 hours

Zeitraum nach dem Onboarding, in dem Kontakte und Verlauf angefordert werden können; jede Anfrage ist nur einmal möglich.

100

Wert von metadata.progress, der den History-Sync als abgeschlossen markiert; Meta sagt, die Phase allein tue das nicht.

2593109

Fehlercode in einem History-Webhook, wenn das Unternehmen die Verlaufsfreigabe in der WhatsApp Business App deaktiviert hat.

3 phases

Phase 0 umfasst Tag 0 bis 1 vor dem Onboarding, Phase 1 die Tage 1 bis 90, Phase 2 die Tage 90 bis 180.

3 MB

Größte Webhook-Payload, die Meta sendet; sie bestimmt das Body-Größenlimit, das Ihr Endpoint benötigt.

Was bringt der Import, und was bleibt zurück?

Zwei Datenströme, beide aus der WhatsApp Business App auf dem Telefon. Kontakte kommen als smb_app_state_sync-Webhooks an, ein Eintrag pro Kontakt mit action add oder remove, und dasselbe Feld meldet auch Kontakte, die das Unternehmen später in der App hinzufügt, bearbeitet oder entfernt. Chats kommen als History-Webhooks: Einzelunterhaltungen aus bis zu 180 Tagen vor dem Onboarding, in beide Richtungen, mit ihrem Zustellstatus. Was nicht übertragen wird, steht unten; ein Gedächtnis, das auf dem Import aufbaut, sollte damit nicht rechnen.

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

Wie stellen Sie sicher, dass der Import Ihren Server erreicht?

Der Endpoint muss live sein, bevor die Nummer verbunden wird. Speichern Sie ihn dann innerhalb von 24 Stunden nach der Verbindung als direktes Webhook-Ziel der Nummer: auf der Seite der Nummer unter Eingehende Nachrichten an einen eigenen Webhook weiterleiten, mit set_webhook_destination über Ihre KI oder als webhook_url in einer Connect-Sitzung der Partner API. Erst das Speichern veranlasst easyCoexistence, bei Meta den Sync anzufordern, zuerst Kontakte, dann Verlauf, einmal pro Onboarding. Die Anfrage und die Meta-Anfrage-IDs erscheinen im Ereignisprotokoll der Nummer als history_sync_requested.

Das Unternehmen muss zustimmen, den Verlauf zu teilen, wenn die App dies während der Verbindung abfragt. Eine Nummer, deren Nachrichten über easyCoexistence laufen (Über easyCoexistence in der Karte Wohin eingehende Nachrichten gehen), bekommt keinen Import, auch nicht mit einer Forward URL, denn die Anfrage wird nur für ein direktes Ziel gestellt. Falls Sie später Automatisierungen brauchen, schalten Sie erst nach Abschluss des Imports um.

Wie kommen die History-Chunks an?

In beliebiger Reihenfolge, in Phasen, die von den neuesten Nachrichten rückwärts laufen: Phase 0 umfasst den letzten Tag vor dem Onboarding, Phase 1 bis Tag 90 und Phase 2 bis Tag 180. Sortieren Sie nach metadata.chunk_order, wenn die Reihenfolge zählt, und behandeln Sie metadata.progress = 100 als Ende, da Meta darauf hinweist, dass die Phase allein nicht anzeigt, dass eine Phase abgeschlossen ist. Die ID einer Unterhaltung ist die Telefonnummer des Kunden, weggelassen, wenn sie nicht geteilt werden darf, und ihr context enthält wa_id, user_id und username. Eine vom Unternehmen gesendete Nachricht hat from auf die Unternehmensnummer gesetzt und ein Feld 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" }
        }
      ]
    }]
  }]
}

Wie sollte das Gedächtnis eines Agenten gespeichert werden?

Zwei Tabellen genügen. Personen werden über die BSUID identifiziert, also die user_id, die Meta zu Kontakten, Unterhaltungen und Nachrichten hinzufügt; daneben wird die Telefonnummer gespeichert, denn ein Nutzer mit Username kann ohne Telefonnummer eintreffen. Metas eigene Referenz empfiehlt, user_id zur Identifikation eines Kontakts zu verwenden. Nachrichten werden über ihre wamid als Schlüssel geführt, sodass Import, Live-Webhooks und erneute Zustellungen derselben Nachricht in einer Zeile zusammenfallen, und ein Flag from_business hält fest, wer gesprochen hat. Indizieren Sie nach Person und Zeitpunkt, denn der Agent fragt die letzten Beiträge einer Person ab.

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

Wie laden Sie Chunks und Kontakte hinein?

Mit idempotenten Inserts, damit Reihenfolge und erneute Zustellung keine Rolle mehr spielen. ingestHistory liest eine History-Änderung: Es protokolliert eine Ablehnung 2593109 und fährt fort, identifiziert eine Unterhaltung über context.user_id oder ihre id, markiert eine Nachricht als die des Unternehmens, wenn from gleich metadata.display_phone_number ist, und speichert einen [type]-Platzhalter, wenn kein Text vorhanden ist. ingestContacts führt einen Upsert über user_id oder Telefonnummer aus und kennzeichnet entfernte Kontakte, statt deren Nachrichten zu löschen. Rufen Sie die Funktionen mit change.value bei einem direkten Ziel auf oder mit dem value des Bodys, wenn das Ereignis einer Weiterleitung history oder smb_app_state_sync ist.

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

Wie fließt dieses Gedächtnis in den Agenten?

Begrenzt, nie alles auf einmal. memoryFor liefert den Namen der Person aus dem Adressbuch und ihre letzten 20 Beiträge, der älteste zuerst, beginnend mit einem Kundenbeitrag, wie es die meisten Chat-APIs erwarten. Fügen Sie eine gespeicherte Zusammenfassung älterer Unterhaltungen hinzu, wenn der Agent mehr braucht. Sechs Monate Chats in jedem Prompt kosten bei jeder Antwort Token und verdecken die gestellte Frage.

Zum Vergleich: Der eingebaute Schritt Mit KI antworten liest höchstens 20 frühere Nachrichten (standardmäßig 10), und der Schritt Webhook aufrufen sendet die letzten 10. Beide greifen auf Text zurück, der so lange gespeichert bleibt, wie der Inhaber es wählt, 30, 90 oder 365 Tage (standardmäßig 90), und zwar ab dem Zeitpunkt, zu dem Automatisierungen eingeschaltet wurden. Deshalb müssen die sechs Monate importierter Chats in Ihrer eigenen Datenbank liegen.

Wie bleibt das Gedächtnis nach dem Import aktuell?

Dasselbe Ziel erhält weiterhin Live-Daten: Nachrichten von Kunden, smb_message_echoes für Antworten, die in der App getippt werden, und smb_app_state_sync, wenn das Unternehmen seine Kontakte bearbeitet. Fügen Sie sie über dieselben Tabellen mit source live oder echo ein. Wenn ein Kunde seine Telefonnummer wechselt, sendet Meta eine Systemnachricht vom Typ user_changed_number oder user_changed_user_id mit previous_user_id. Das ist das Signal, die Zeilen dieses Kunden auf die neue BSUID umzuziehen.

Wenn Sie Automatisierungen später einschalten, wird das direkte Ziel entfernt. Tragen Sie dieselbe URL als Forward URL ein, lesen Sie event und value aus jedem signierten POST und warten Sie vor dem Umschalten auf progress 100. Sonst erreichen Sie die restlichen Chunks nur noch über die Weiterleitung.

So richten Sie es ein

  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.

Häufige Fehler

  • Das Ziel erst am zweiten Tag speichern. Der Sync wird nur innerhalb von 24 Stunden nach der Verbindung angefordert, ein später gespeicherter Endpoint erhält daher nur Live-Nachrichten.
  • Automatisierungen einschalten, bevor progress 100 erreicht ist. Das direkte Ziel wird sofort entfernt, und spätere Chunks erreichen Sie nur, wenn bereits eine Forward URL gesetzt ist.
  • Phase 2 als Ende des Imports behandeln. Nur metadata.progress = 100 zeigt an, dass der Sync abgeschlossen ist, und Chunks werden nicht in Reihenfolge zugestellt.
  • Das Gedächtnis allein über die Telefonnummer schlüsseln. Unterhaltungs-IDs und Kontakte lassen die Telefonnummer weg, wenn ein Nutzer mit Username sie nicht teilen kann, während user_id weiterhin vorhanden ist.
Mit EasyCoexistence

Die Anfrage wird im Ereignisprotokoll der Nummer festgehalten, danach wird die Nummer rund um die Uhr überwacht. US$ 9 bis hinunter zu US$ 0.75 pro Nummer und Monat, sinkend mit jeder weiteren Nummer, die ersten 3 Tage kostenlos.

Häufig gestellte Fragen

Kann der Import ein zweites Mal laufen?

Nur über ein neues Onboarding. Meta erlaubt eine Anfrage pro Onboarding, die Nummer muss also getrennt und neu verbunden werden, dann kommen die Chats erneut an. Das Einfügen über die Nachrichten-ID verhindert, dass beim zweiten Durchlauf etwas doppelt hinzukommt.

Speichert easyCoexistence eine Kopie der importierten Chats?

Nein. Verlauf und Kontakte gehen direkt von Meta an Ihren Endpoint und werden standardmäßig nicht gespeichert. Für eine Nummer mit eingeschalteten Automatisierungen bewahrt easyCoexistence den Nachrichtentext für den von Ihnen gewählten Zeitraum auf, 30, 90 oder 365 Tage (standardmäßig 90), und der Bildschirm Conversations zeigt ihn; weitergeleitete Zustellungen bleiben bis zu 7 Tage gespeichert, Laufprotokolle 30 Tage.

Wie groß können die Payloads werden?

Ein einzelner Meta-Webhook kann bis zu 3 MB enthalten, und eine stark genutzte Nummer sendet viele History-Chunks. Erhöhen Sie das Body-Limit Ihres Frameworks (Express steht standardmäßig auf 100 kb) und bestätigen Sie den Empfang, bevor Sie in die Datenbank schreiben.

Braucht ein Agent den Import, um zu funktionieren?

Nein. Ohne ihn beginnt das Gedächtnis mit der ersten Nachricht nach der Verbindung und wächst aus dem Live-Verkehr. Der Import ist wichtig, wenn frühere Unterhaltungen die Antworten von Tag eins an prägen sollen, etwa die letzte Bestellung eines wiederkehrenden Kunden.

Weiterlesen

Bereit für den Start?

Richten Sie WhatsApp Coexistence in wenigen Minuten statt Monaten ein. Die App funktioniert weiterhin auf dem Telefon.

Kostenlose Testphase starten

Verifiziert am