AccediInizia la prova gratuita
Meta Tech Provider

Dai memoria al tuo agente AI: sei mesi di chat e contatti WhatsApp

Su un numero collegato tramite Coexistence, Meta può inviare una sola volta al tuo server i contatti dell'app e fino a 180 giorni di chat uno a uno, a condizione che una destinazione webhook diretta sia salvata entro 24 ore dalla connessione e che l'azienda lo accetti nell'app. I blocchi possono arrivare fuori ordine e l'avanzamento 100 segna la fine. Archivia i messaggi per id, identifica le persone tramite BSUID e passa all'agente i turni recenti.

easyCoexistence collega il numero tramite il flusso Coexistence di Meta e, quando salvi il tuo endpoint come destinazione webhook diretta entro 24 ore, chiede a Meta una sola volta i contatti e fino a 180 giorni di chat, che arrivano direttamente al tuo server.

180 days

Fino a quanto indietro arriva la sincronizzazione della cronologia dall'onboarding: la tabella delle funzionalità di Meta parla degli ultimi 6 mesi.

24 hours

Tempo dopo l'onboarding entro cui richiedere contatti e cronologia; ogni richiesta può essere fatta una sola volta.

100

Valore di metadata.progress che segna la sincronizzazione della cronologia come completata; Meta dice che la sola fase non basta.

2593109

Codice di errore in un webhook di cronologia quando l'azienda ha disattivato la condivisione della cronologia nell'app WhatsApp Business.

3 phases

La fase 0 copre dal giorno 0 al giorno 1 prima dell'onboarding, la fase 1 dal giorno 1 al giorno 90, la fase 2 dal giorno 90 al giorno 180.

3 MB

Il payload webhook più grande inviato da Meta, che determina il limite di dimensione del corpo richiesto dal tuo endpoint.

Che cosa porta l'importazione e che cosa resta indietro?

Due flussi, entrambi dall'app WhatsApp Business sul telefono. I contatti arrivano come webhook smb_app_state_sync, una voce per contatto con action add o remove, e lo stesso campo segnala anche i contatti che l'azienda aggiunge, modifica o rimuove in seguito nell'app. Le chat arrivano come webhook di cronologia: conversazioni uno a uno fino a 180 giorni prima dell'onboarding, in entrambe le direzioni, con il loro stato di consegna. Ciò che non viene trasferito è elencato sotto, quindi una memoria costruita sull'importazione non deve aspettarselo.

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

Come fai in modo che l'importazione arrivi al tuo server?

Tieni l'endpoint attivo prima che il numero si connetta, poi salvalo come destinazione webhook diretta del numero entro 24 ore dalla connessione: nella pagina del numero sotto Instrada i messaggi in arrivo al tuo webhook, con set_webhook_destination dalla tua AI, oppure come webhook_url in una sessione di connessione Partner API. Salvarlo è ciò che fa chiedere a easyCoexistence la sincronizzazione a Meta, prima i contatti e poi la cronologia, una volta sola per ogni onboarding; la richiesta e gli ID di richiesta di Meta compaiono nel registro eventi del numero come history_sync_requested.

L'azienda deve accettare di condividere la cronologia quando l'app lo chiede durante la connessione. Un numero i cui messaggi passano da easyCoexistence (Tramite easyCoexistence nella scheda Dove vanno i messaggi in arrivo), anche con un Forward URL, non riceve alcuna importazione, perché la richiesta viene fatta solo per una destinazione diretta. Se ti servono le automazioni in seguito, passa a quella modalità dopo la fine dell'importazione.

Come arrivano i blocchi della cronologia?

Fuori ordine, in fasi che vanno dai messaggi più recenti indietro nel tempo: la fase 0 copre l'ultimo giorno prima dell'onboarding, la fase 1 fino al giorno 90 e la fase 2 fino al giorno 180. Ordina per metadata.chunk_order se l'ordine conta, e considera metadata.progress = 100 come la fine, perché Meta fa notare che la fase non basta a dirti che una fase è conclusa. L'id di una conversazione è il numero di telefono del cliente, omesso quando non può essere condiviso, e il suo context contiene wa_id, user_id e username. Un messaggio inviato dall'azienda ha from impostato sul numero dell'azienda e un campo 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" }
        }
      ]
    }]
  }]
}

Come deve essere archiviata la memoria di un agente?

Bastano due tabelle. Le persone sono indicizzate per BSUID, lo user_id che Meta aggiunge a contatti, conversazioni e messaggi, con accanto il numero di telefono, perché un utente con username può arrivare senza. Il riferimento di Meta dice di usare user_id per identificare un contatto. I messaggi sono indicizzati per wamid, quindi l'importazione, i webhook live e le consegne ripetute dello stesso messaggio si riducono a una sola riga, e un flag from_business registra chi ha parlato. Indicizza per persona e orario, perché l'agente chiede gli ultimi turni di una persona.

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

Come carichi i blocchi e i contatti nella memoria?

Con inserimenti idempotenti, così l'ordine e le consegne ripetute non contano più. ingestHistory legge una modifica della cronologia: registra un rifiuto 2593109 e passa oltre, indicizza una conversazione per context.user_id o per il suo id, contrassegna un messaggio come dell'azienda quando from è uguale a metadata.display_phone_number, e salva un segnaposto [type] quando manca il testo. ingestContacts esegue un upsert su user_id o numero di telefono e contrassegna i contatti rimossi invece di cancellarne i messaggi. Chiamale con change.value su una destinazione diretta, oppure con il value del corpo quando l'evento di un inoltro è history o 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 };
}

Come passi questa memoria all'agente?

Limitata, mai tutta insieme. memoryFor restituisce il nome della persona dalla rubrica e i suoi ultimi 20 turni, dal più vecchio, aprendo con un turno del cliente come si aspettano la maggior parte delle API di chat; aggiungi un riepilogo archiviato delle conversazioni più vecchie se l'agente ne ha bisogno. Sei mesi di chat in ogni prompt costano token a ogni risposta e seppelliscono la domanda in corso.

Per confronto, il passaggio Rispondi con AI integrato legge al massimo 20 messaggi precedenti (10 per impostazione predefinita), e il passaggio Chiama il mio webhook invia gli ultimi 10. Entrambi attingono a testo conservato per la durata che sceglie il titolare, 30, 90 o 365 giorni (90 per impostazione predefinita), dal momento in cui le automazioni sono state attivate, ed è per questo che i sei mesi di chat importate devono vivere nel tuo database.

Come resta aggiornata la memoria dopo l'importazione?

La stessa destinazione continua a ricevere traffico live: i messaggi dei clienti, smb_message_echoes per le risposte scritte nell'app, e smb_app_state_sync quando l'azienda modifica i suoi contatti. Inseriscili nelle stesse tabelle con source live o echo. Quando un cliente cambia numero di telefono, Meta invia un messaggio di sistema di tipo user_changed_number o user_changed_user_id con previous_user_id, un segnale per spostare le sue righe sul nuovo BSUID.

Attivare le automazioni in seguito rimuove la destinazione diretta. Aggiungi lo stesso URL come Forward URL, leggi event e value da ogni POST firmato, e attendi progress 100 prima di passare, altrimenti i blocchi rimanenti ti arrivano solo tramite quell'inoltro.

Come configurarlo

  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.

Errori comuni

  • Salvare la destinazione il secondo giorno. La sincronizzazione viene richiesta solo entro 24 ore dalla connessione, quindi un endpoint salvato più tardi riceve solo messaggi live.
  • Attivare le automazioni prima che l'avanzamento raggiunga 100. La destinazione diretta viene rimossa subito, e i blocchi successivi ti arrivano solo se un Forward URL è già impostato.
  • Considerare la fase 2 come fine dell'importazione. Solo metadata.progress = 100 indica che la sincronizzazione è completa, e i blocchi non arrivano in sequenza.
  • Indicizzare la memoria solo sul numero di telefono. Gli id delle conversazioni e i contatti perdono il numero quando un utente con username non può condividerlo, mentre user_id resta presente.
Farlo con EasyCoexistence

La richiesta viene registrata nel registro eventi del numero, e il numero viene poi monitorato 24/7. US$ 9 fino a US$ 0,75 per numero al mese, in calo man mano che aggiungi numeri, con 3 giorni di prova gratuita.

Domande frequenti

L'importazione può essere eseguita una seconda volta?

Solo con un nuovo onboarding. Meta consente una richiesta per onboarding, quindi il numero va disconnesso e ricollegato, e le chat arrivano di nuovo; inserire per id del messaggio impedisce alla seconda passata di aggiungere qualcosa due volte.

easyCoexistence conserva una copia delle chat importate?

No. Cronologia e contatti vanno da Meta direttamente al tuo endpoint e non vengono archiviati per impostazione predefinita. Per un numero con automazioni attive, easyCoexistence conserva il testo dei messaggi per il periodo che scegli, 30, 90 o 365 giorni (90 per impostazione predefinita), e la schermata Conversazioni lo mostra; le consegne inoltrate vengono conservate fino a 7 giorni, e i log di esecuzione 30 giorni.

Quanto possono diventare grandi i payload?

Un singolo webhook di Meta può contenere fino a 3 MB, e un numero molto attivo invia molti blocchi di cronologia. Aumenta il limite del corpo del tuo framework (Express usa 100 kb per impostazione predefinita) e conferma la ricezione prima di scrivere nel database.

Un agente ha bisogno dell'importazione per funzionare?

No. Senza di essa la memoria parte dal primo messaggio dopo la connessione e cresce con il traffico live. L'importazione conta quando le conversazioni passate devono influenzare le risposte fin dal primo giorno, per esempio l'ultimo ordine di un cliente che torna.

Continua a leggere

Pronto per iniziare?

Configura WhatsApp Coexistence in pochi minuti, non in mesi. L'app continua a funzionare sul telefono.

Inizia la prova gratuita

Verificato il