Kirjaudu sisäänAloita ilmainen kokeilu
Meta Tech Provider

Anna AI-agentillesi muisti: kuusi kuukautta WhatsApp-keskusteluja ja yhteystietoja

Coexistencen kautta yhdistetyssä numerossa Meta voi lähettää sovelluksen yhteystiedot ja jopa 180 päivän yksi-yhteen-keskustelut palvelimellesi kerran, jos suora webhook-kohde on tallennettu 24 tunnin sisällä yhdistämisestä ja yritys hyväksyy asian sovelluksessa. Erät voivat saapua epäjärjestyksessä, ja edistyminen 100 merkitsee loppua. Tallenna viestit tunnisteen mukaan, henkilöt BSUID:n mukaan ja syötä tuoreet vuorot agentille.

easyCoexistence yhdistää numeron Metan Coexistence-kulun kautta, ja kun tallennat endpointisi suoraksi webhook-kohteeksi 24 tunnin sisällä, se pyytää Metalta kerran yhteystiedot ja jopa 180 päivän keskustelut, jotka kulkevat suoraan palvelimellesi.

180 days

Kuinka pitkälle historiasynkronointi ulottuu käyttöönotosta; Metan ominaisuustaulukko kutsuu sitä viimeisimmiksi 6 kuukaudeksi.

24 hours

Aika käyttöönotosta, jolloin yhteystiedot ja historia pyydetään; kukin pyyntö voidaan tehdä vain kerran.

100

metadata.progress-arvo, joka merkitsee historiasynkronoinnin valmiiksi; Meta sanoo, ettei pelkkä phase riitä.

2593109

Virhekoodi historia-webhookissa, kun yritys on sulkenut historian jakamisen WhatsApp Business -sovelluksessa.

3 phases

Vaihe 0 kattaa päivät 0–1 ennen käyttöönottoa, vaihe 1 päivät 1–90 ja vaihe 2 päivät 90–180.

3 MB

Suurin Metan lähettämä webhook-kuorma, joka määrää endpointisi tarvitseman rungon kokorajan.

Mitä tuonti tuo mukanaan ja mikä jää jälkeen?

Kaksi virtaa, molemmat WhatsApp Business -sovelluksesta puhelimelta. Yhteystiedot saapuvat smb_app_state_sync-webhookeina, yksi merkintä per yhteystieto, action-kentässä add tai remove, ja sama kenttä kertoo myös yhteystiedot, joita yritys myöhemmin lisää, muokkaa tai poistaa sovelluksessa. Keskustelut saapuvat historia-webhookeina: yksi-yhteen-keskustelut jopa 180 päivää ennen käyttöönottoa molempiin suuntiin toimitustiloineen. Mitä ei siirry, on listattu alla, joten muistin ei pidä odottaa sitä tuonnista.

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

Miten varmistat, että tuonti saapuu palvelimellesi?

Ota endpoint käyttöön ennen numeron yhdistämistä ja tallenna se numeron suoraksi webhook-kohteeksi 24 tunnin sisällä yhdistämisestä: numeron sivulla kohdassa ”Route incoming messages to your own webhook”, set_webhook_destination-kutsulla tekoälysi kautta tai webhook_url-kentässä Partner API -yhdistämisistunnossa. Tallennus saa easyCoexistencen pyytämään Metalta synkronoinnin, ensin yhteystiedot ja sitten historian, kerran per käyttöönotto. Pyyntö ja Metan pyyntötunnisteet näkyvät numeron tapahtumalokissa nimellä history_sync_requested.

Yrityksen on hyväksyttävä historian jakaminen, kun sovellus kysyy sitä yhdistämisen aikana. Numero, jonka viestit kulkevat easyCoexistencen kautta (”Through easyCoexistence” kortissa ”Where incoming messages go”), vaikka sillä olisi Forward URL, ei saa tuontia, koska pyyntö tehdään vain suoralle kohteelle. Jos tarvitset automaatioita myöhemmin, vaihda tilaa tuonnin päätyttyä.

Miten historian erät saapuvat?

Epäjärjestyksessä, vaiheittain, uusimmista viesteistä taaksepäin: vaihe 0 kattaa viimeisen päivän ennen käyttöönottoa, vaihe 1 jopa päivään 90 ja vaihe 2 jopa päivään 180. Lajittele metadata.chunk_order-kentän mukaan, jos järjestyksellä on merkitystä, ja pidä metadata.progress = 100 loppuna, koska Meta huomauttaa, ettei vaihe kerro vaiheen olevan valmis. Keskustelun id on asiakkaan puhelinnumero, jätetty pois jos sitä ei voi jakaa, ja sen context sisältää wa_id:n, user_id:n ja username:n. Yrityksen lähettämässä viestissä from on yrityksen numero ja mukana on to-kenttä.

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

Miten agentin muisti kannattaa tallentaa?

Kaksi taulua riittää. Henkilöt tunnistetaan BSUID:n perusteella, eli user_id-kentän perusteella, jonka Meta lisää yhteystietoihin, keskusteluihin ja viesteihin, ja puhelinnumero säilytetään sen vieressä, koska käyttäjä, jolla on käyttäjätunnus, voi saapua ilman sitä. Metan oma ohje sanoo käyttää user_id:tä yhteystiedon tunnistamiseen. Viestit avataan niiden wamid-tunnuksella, jolloin tuonti, live-webhookit ja uudelleen lähetetyt samat viestit yhdistyvät yhdeksi riviksi, ja from_business-lippu kertoo, kuka puhui. Indeksoi henkilön ja ajan mukaan, koska agentti hakee yhden henkilön viimeisimmät vuorot.

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

Miten erät ja yhteystiedot ladataan muistiin?

Idempotentein lisäyksin, jolloin järjestys ja uudelleentoimitus eivät enää merkitse. ingestHistory lukee yhden historia-muutoksen: se kirjaa 2593109-hylkäyksen ja jatkaa, tunnistaa keskustelun context.user_id:n tai id:n perusteella, merkitsee viestin yrityksen viestiksi, kun from vastaa metadata.display_phone_number-arvoa, ja tallentaa [type]-paikkamerkin, jos tekstiä ei ole. ingestContacts tekee upsertin user_id:n tai puhelinnumeron perusteella ja merkitsee poistetut yhteystiedot poistamatta niiden viestejä. Kutsu niitä change.value-arvolla suoraa kohdetta käytettäessä tai rungon value-arvolla, kun välitetyn tapahtuman event on history tai 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 };
}

Miten muisti syötetään agentille?

Rajoitetusti, ei kerralla. memoryFor palauttaa henkilön nimen osoitekirjasta ja hänen viimeiset 20 vuoroaan vanhimmasta uusimpaan, alkaen asiakkaan vuorosta, kuten useimmat chat-rajapinnat odottavat. Lisää tallennettu yhteenveto vanhemmista keskusteluista, jos agentti tarvitsee enemmän. Kuuden kuukauden keskustelut jokaisessa kehotteessa maksavat tokeneita joka vastauksella ja hukuttavat kysytyn kysymyksen.

Vertailun vuoksi sisäänrakennettu ”Reply with AI” -vaihe lukee enintään 20 aiempaa viestiä (oletuksena 10), ja ”Call my webhook” -vaihe lähettää viimeiset 10. Molemmat hyödyntävät tekstiä, joka säilytetään omistajan valitsemän ajan, 30, 90 tai 365 päivää (oletuksena 90), automaatioiden käynnistämisestä lähtien, minkä vuoksi tuodut kuuden kuukauden keskustelut on pidettävä omassa tietokannassasi.

Miten muisti pysyy ajantasaisena tuonnin jälkeen?

Sama kohde jatkaa live-liikenteen vastaanottamista: asiakkaiden viestit, smb_message_echoes-kutsut sovelluksessa kirjoitetuille vastauksille ja smb_app_state_sync, kun yritys muokkaa yhteystietojaan. Lisää ne samoihin tauluihin lähteellä live tai echo. Kun asiakas vaihtaa puhelinnumeroaan, Meta lähettää järjestelmäviestin tyyppiä user_changed_number tai user_changed_user_id, ja kentässä previous_user_id on vanha tunniste. Tämä on merkki siirtää hänen rivinsä uuteen BSUID:hen.

Automaatioiden myöhempi käyttöönotto poistaa suoran kohteen. Lisää sama URL Forward URL -kentäksi, lue event ja value jokaisesta allekirjoitetusta POST-pyynnöstä ja odota metadata.progress = 100 ennen vaihtoa, muuten loput erät tulevat vain välityksen kautta.

Näin otat sen käyttöön

  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.

Yleiset virheet

  • Tallennus toisena päivänä. Tuonti pyydetään vain 24 tunnin sisällä yhdistämisestä, joten myöhemmin tallennettu endpoint saa vain live-viestit.
  • Automaatioiden käynnistäminen ennen kuin edistyminen on 100. Suora kohde poistuu heti, ja myöhemmät erät tulevat perille vain, jos Forward URL on jo asetettu.
  • Vaiheen 2 pitäminen tuonnin loppuna. Vain metadata.progress = 100 kertoo synkronoinnin valmistuneen, eivätkä erät tule perille järjestyksessä.
  • Muistin avaaminen pelkän puhelinnumeron mukaan. Keskustelujen id:t ja yhteystiedot jättävät puhelinnumeron pois, kun käyttäjä, jolla on käyttäjätunnus, ei voi jakaa sitä, mutta user_id on silti mukana.
Näin teet tämän EasyCoexistencen avulla

Pyyntö kirjataan numeron tapahtumalokiin, ja numeroa valvotaan sen jälkeen ympäri vuorokauden. US$ 9:stä US$ 0,75:een numeroa kohti kuukaudessa, hinta laskee numeroita lisättäessä, ensimmäiset 3 päivää ilmaiseksi.

Usein kysytyt kysymykset

Voiko tuonnin ajaa uudelleen?

Vain uuden käyttöönoton kautta. Meta sallii yhden pyynnön käyttöönottoa kohden, joten numero on irrotettava ja yhdistettävä uudelleen, ja keskustelut saapuvat silloin uudelleen. Lisäys viestin tunnisteen mukaan estää, että toinen kierros lisää mitään kahteen kertaan.

Säilyttääkö easyCoexistence kopion tuoduista keskusteluista?

Ei. Historia ja yhteystiedot kulkevat Metalta suoraan endpointiisi, eikä niitä tallenneta oletusarvoisesti. Numerolle, jolla on automaatiot päällä, easyCoexistence säilyttää viestien tekstiä valitsemasi ajan, 30, 90 tai 365 päivää (oletuksena 90), ja Keskustelut-näkymä näyttää sen; välitetyt toimitukset säilytetään enintään 7 päivää ja ajolokit 30 päivää.

Kuinka suuria payloadit voivat olla?

Yksi Metan webhook voi kantaa jopa 3 MB, ja vilkas numero lähettää paljon historia-eriä. Nosta frameworkisi rungon rajaa (Express-oletus on 100 kb) ja vastaa ennen tietokantakirjoitusta.

Tarvitseeko agentti tuonnin toimiakseen?

Ei. Ilman sitä muisti alkaa ensimmäisestä viestistä yhdistämisen jälkeen ja kasvaa live-liikenteestä. Tuonti on tärkeä, kun aiempien keskustelujen pitäisi vaikuttaa vastauksiin ensimmäisestä päivästä lähtien, esimerkiksi palaavan asiakkaan viimeisimmän tilauksen kohdalla.

Lue lisää

Valmis aloittamaan?

Ota WhatsApp Coexistence käyttöön minuuteissa, ei kuukausissa. Sovellus toimii edelleen puhelimessa.

Aloita ilmainen kokeilu

Vahvistettu