Zaloguj sięRozpocznij bezpłatny okres próbny
Meta Tech Provider

Daj agentowi AI pamięć: sześć miesięcy czatów WhatsApp i kontaktów

Przy numerze połączonym przez Coexistence Meta może raz wysłać na Twój serwer kontakty z aplikacji oraz do 180 dni czatów jeden na jeden, pod warunkiem że adres docelowy webhooka zostanie zapisany w ciągu 24 godzin od połączenia, a firma zgodzi się w aplikacji. Fragmenty mogą przyjść w dowolnej kolejności, a postęp 100 oznacza koniec. Zapisuj wiadomości według id, osoby wiąż po BSUID i podawaj agentowi ostatnie wymiany zdań.

easyCoexistence łączy numer przez przepływ Coexistence Meta i, gdy zapiszesz Twój endpoint jako bezpośredni cel webhooka w ciągu 24 godzin, prosi Meta jednorazowo o kontakty oraz do 180 dni czatów, które trafiają prosto na Twój serwer.

180 days

Jak daleko wstecz sięga synchronizacja historii od onboardingu; tabela funkcji Meta nazywa to 6 ostatnimi miesiącami.

24 hours

Czas po onboardingu, po którym można zażądać kontaktów i historii; każde żądanie można wysłać tylko raz.

100

Wartość metadata.progress, która oznacza zakończenie synchronizacji historii; Meta podkreśla, że sama wartość phase nie wystarcza.

2593109

Kod błędu w webhooku historii, gdy firma wyłączyła udostępnianie historii w aplikacji WhatsApp Business.

3 phases

Faza 0 obejmuje dni od 0 do 1 przed onboardingiem, faza 1 od dnia 1 do 90, a faza 2 od dnia 90 do 180.

3 MB

Największy payload webhooka wysyłany przez Meta, który wyznacza limit rozmiaru treści potrzebny Twojemu endpointowi.

Co przynosi import, a co zostaje?

Dwa strumienie, oba z aplikacji WhatsApp Business na telefonie. Kontakty przychodzą jako webhooki smb_app_state_sync, po jednym wpisie na kontakt, z działaniem add lub remove; to samo pole informuje też o kontaktach, które firma później dodaje, edytuje lub usuwa w aplikacji. Czaty przychodzą jako webhooki historii: rozmowy jeden na jeden z okresu do 180 dni przed onboardingiem, w obu kierunkach, wraz ze statusem dostarczenia. To, czego nie przenosi się, wymieniono poniżej, więc pamięć zbudowana na imporcie nie powinna tego oczekiwać.

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

Jak sprawić, by import dotarł na Twój serwer?

Endpoint musi działać, zanim numer się połączy, a potem zapisz go jako bezpośredni adres docelowy webhooka numeru w ciągu 24 godzin od połączenia: na stronie numeru w polu „Kieruj przychodzące wiadomości do własnego webhooka”, poleceniem set_webhook_destination z poziomu Twojego agenta AI albo jako webhook_url w sesji połączenia Partner API. Zapisanie go sprawia, że easyCoexistence prosi Meta o synchronizację, najpierw kontaktów, potem historii, jednorazowo przy każdym onboardingu; żądanie i identyfikatory żądań Meta pojawiają się w dzienniku zdarzeń numeru jako history_sync_requested.

Firma musi zgodzić się na udostępnienie historii, gdy aplikacja zapyta o to podczas połączenia. Numer, którego wiadomości przechodzą przez easyCoexistence („Przez easyCoexistence” w karcie Dokąd trafiają przychodzące wiadomości), nawet z Forward URL, nie otrzyma importu, ponieważ żądanie wysyłane jest tylko do bezpośredniego celu. Jeśli później potrzebujesz automatyzacji, przełącz numer dopiero po zakończeniu importu.

Jak docierają fragmenty historii?

Fragmenty przychodzą w dowolnej kolejności, w fazach biegnących od najnowszych wiadomości wstecz: faza 0 obejmuje ostatni dzień przed onboardingiem, faza 1 sięga do dnia 90, a faza 2 do dnia 180. Jeśli kolejność ma znaczenie, sortuj według metadata.chunk_order, a za koniec uznawaj metadata.progress = 100, ponieważ Meta zaznacza, że sama faza nie informuje o jej zakończeniu. Identyfikatorem rozmowy jest numer telefonu klienta, pomijany, gdy nie może zostać udostępniony, a jej kontekst zawiera wa_id, user_id i username. Wiadomość wysłaną przez firmę ma pole from ustawione na numer firmy oraz pole 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" }
        }
      ]
    }]
  }]
}

Jak należy przechowywać pamięć agenta?

Wystarczą dwie tabele. Osoby wiąże się z BSUID, czyli user_id, który Meta dodaje do kontaktów, rozmów i wiadomości, a numer telefonu trzyma się obok, ponieważ użytkownik z nazwą użytkownika może przyjść bez niego; dokumentacja Meta wskazuje user_id jako sposób identyfikacji kontaktu. Wiadomości wiąże się z ich wamid, więc import, webhooki na żywo i ponowne dostarczenia tej samej wiadomości łączą się w jeden wiersz, a flaga from_business zapisuje, kto mówił. Indeksuj według osoby i czasu, bo agent pyta o ostatnie wypowiedzi jednej osoby.

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

Jak ładować fragmenty i kontakty do pamięci?

Operacjami wstawiania idempotentnymi, dzięki czemu kolejność i ponowne dostarczenie przestają mieć znaczenie. ingestHistory odczytuje jedną zmianę historii: zapisuje odmowę 2593109 i idzie dalej, wiąże rozmowę z context.user_id lub jej id, oznacza wiadomość jako firmową, gdy from równa się metadata.display_phone_number, i zapisuje symbol zastępczy [type], gdy brak tekstu. ingestContacts działa jako upsert po user_id lub numerze telefonu i oznacza usunięte kontakty zamiast kasować ich wiadomości. Wywołuj je z change.value przy bezpośrednim celu albo z wartością z treści, gdy zdarzeniem przekazanym przez forward jest history lub 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 };
}

Jak podawać tę pamięć agentowi?

Z ograniczeniem, nigdy wszystkiego naraz. memoryFor zwraca imię osoby z książki adresowej oraz jej ostatnie 20 wypowiedzi, od najstarszej, zaczynając od wypowiedzi klienta, tak jak oczekuje większość API do czatów; dodaj zapisane podsumowanie starszych rozmów, jeśli agent potrzebuje więcej. Sześć miesięcy czatów w każdym prompcie kosztuje tokeny przy każdej odpowiedzi i zagrzebuje pytanie, na które trzeba odpowiedzieć.

Dla porównania wbudowany krok „Odpowiedz z AI” czyta najwyżej 20 wcześniejszych wiadomości (domyślnie 10), a krok „Wywołaj mój webhook” wysyła ostatnie 10. Oba korzystają z tekstu przechowywanego przez okres wybrany przez właściciela, 30, 90 lub 365 dni (domyślnie 90), od chwili włączenia automatyzacji, dlatego sześć miesięcy zaimportowanych czatów musi żyć we własnej bazie danych.

Jak pamięć pozostaje aktualna po imporcie?

Ten sam cel dalej otrzymuje ruch na żywo: wiadomości od klientów, smb_message_echoes dla odpowiedzi wpisanych w aplikacji oraz smb_app_state_sync, gdy firma edytuje swoje kontakty. Wstawiaj je tymi samymi tabelami z source live lub echo. Gdy klient zmienia numer telefonu, Meta wysyła wiadomość systemową typu user_changed_number lub user_changed_user_id z previous_user_id, co jest sygnałem, by przenieść jego wiersze na nowy BSUID.

Włączenie automatyzacji później usuwa bezpośredni cel. Dodaj ten sam URL jako Forward URL, odczytuj event i value z każdego podpisanego żądania POST i zaczekaj na progress 100 przed przełączeniem, bo inaczej pozostałe fragmenty dotrą do Ciebie tylko tym przekierowaniem.

Jak to skonfigurować

  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.

Typowe błędy

  • Zapisanie adresu drugiego dnia. Synchronizacja jest żądana tylko w ciągu 24 godzin od połączenia, więc endpoint zapisany później otrzymuje wyłącznie wiadomości na żywo.
  • Włączenie automatyzacji przed osiągnięciem progress 100. Bezpośredni cel zostaje usunięty od razu, a kolejne fragmenty dotrą tylko wtedy, gdy Forward URL jest już ustawiony.
  • Traktowanie fazy 2 jako końca importu. Tylko metadata.progress = 100 oznacza zakończenie synchronizacji, a fragmenty nie docierają po kolei.
  • Wiązanie pamięci wyłącznie z numerem telefonu. Identyfikatory rozmów i kontakty tracą numer telefonu, gdy użytkownik z nazwą użytkownika nie może go udostępnić, a user_id jest nadal obecny.
Z EasyCoexistence zrobisz to

Żądanie zapisywane jest w dzienniku zdarzeń numeru, a numer jest potem monitorowany całą dobę. Od US$ 9 do US$ 0.75 za numer miesięcznie, a cena spada wraz z dodawaniem numerów. Pierwsze 3 dni w bezpłatnym okresie próbnym.

Najczęściej zadawane pytania

Czy import może uruchomić się ponownie?

Tylko przez nowy onboarding. Meta dopuszcza jedno żądanie na onboarding, więc numer trzeba odłączyć i połączyć ponownie, a czaty wtedy przychodzą od nowa; wstawianie według id wiadomości nie dopuści do podwójnego dodania czegokolwiek w drugim przebiegu.

Czy easyCoexistence przechowuje kopię zaimportowanych czatów?

Nie. Historia i kontakty trafiają z Meta prosto do Twojego endpointu i domyślnie nie są przechowywane. Dla numeru z włączonymi automatyzacjami easyCoexistence zachowuje treść wiadomości przez wybrany przez Ciebie okres, 30, 90 lub 365 dni (domyślnie 90), a ekran Rozmowy ją pokazuje; przekazane dostawy są przechowywane do 7 dni, a dzienniki uruchomień 30 dni.

Jak duże mogą być payloady?

Pojedynczy webhook Meta może zawierać do 3 MB, a aktywny numer wysyła wiele fragmentów historii. Podnieś limit treści w swoim frameworku (Express domyślnie ma 100 kb) i potwierdź odbiór przed zapisem do bazy danych.

Czy agent potrzebuje importu, żeby działać?

Nie. Bez niego pamięć zaczyna się od pierwszej wiadomości po połączeniu i rośnie z ruchu na żywo. Import ma znaczenie, gdy wcześniejsze rozmowy mają kształtować odpowiedzi od pierwszego dnia, na przykład ostatnie zamówienie powracającego klienta.

Czytaj dalej

Gotowy, aby zacząć?

Skonfiguruj WhatsApp Coexistence w kilka minut, nie miesięcy. Aplikacja nadal działa na telefonie.

Rozpocznij bezpłatny okres próbny

Zweryfikowano w