Iniciar sessãoIniciar teste gratuito
Meta Tech Provider

Dê memória ao seu agente de IA: seis meses de conversas e contactos do WhatsApp

Num número ligado através do Coexistence, a Meta pode enviar para o seu servidor, uma única vez, os contactos da aplicação e até 180 dias de conversas individuais, desde que um destino de webhook direto esteja guardado nas 24 horas seguintes à ligação e a empresa concordar na aplicação. Os blocos podem chegar fora de ordem, e o progresso 100 marca o fim. Guarde as mensagens pelo id, identifique as pessoas pelo BSUID e envie as últimas trocas ao agente.

A easyCoexistence liga o número pelo fluxo Coexistence da Meta e, quando guarda o seu endpoint como destino de webhook direto nas 24 horas seguintes, pede à Meta uma única vez os contactos e até 180 dias de conversas, que seguem diretamente para o seu servidor.

180 days

Até onde recua a sincronização do histórico desde a integração; a tabela de funcionalidades da Meta indica os 6 meses mais recentes.

24 hours

Tempo após a integração para pedir contactos e histórico; cada pedido só pode ser feito uma vez.

100

Valor de metadata.progress que marca a sincronização do histórico como concluída; a Meta diz que a fase, por si só, não basta.

2593109

Código de erro num webhook de histórico quando a empresa desativou a partilha do histórico na aplicação WhatsApp Business.

3 phases

A fase 0 cobre o dia 0 a 1 antes da integração, a fase 1 os dias 1 a 90 e a fase 2 os dias 90 a 180.

3 MB

Maior payload de webhook enviado pela Meta, que define o limite de tamanho do corpo que o seu endpoint precisa.

O que traz a importação e o que fica para trás?

Dois fluxos, ambos vindos da aplicação WhatsApp Business no telemóvel. Os contactos chegam como webhooks smb_app_state_sync, uma entrada por contacto com action add ou remove, e o mesmo campo continua a reportar os contactos que a empresa acrescenta, edita ou remove depois na aplicação. As conversas chegam como webhooks de histórico: conversas individuais de até 180 dias antes da integração, nos dois sentidos, com o respetivo estado de entrega. O que não chega está listado abaixo, pelo que uma memória construída sobre a importação não deve contar com isso.

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

Como garantir que a importação chega ao seu servidor?

Tenha o endpoint ativo antes de o número ligar e depois guarde-o como destino de webhook direto do número nas 24 horas seguintes à ligação: na página do número, em Encaminhar as mensagens recebidas para o seu próprio webhook, com set_webhook_destination a partir da sua IA, ou como webhook_url numa sessão de ligação da Partner API. Guardá-lo é o que leva a easyCoexistence a pedir à Meta a sincronização, primeiro os contactos e depois o histórico, uma vez por integração; o pedido e os identificadores de pedido da Meta aparecem no registo de eventos do número como history_sync_requested.

A empresa tem de aceitar partilhar o histórico quando a aplicação o pedir durante a ligação. Um número cujas mensagens passam pela easyCoexistence (Através da easyCoexistence, no cartão Para onde vão as mensagens recebidas), mesmo com URL de reencaminhamento, não recebe importação, porque o pedido só é feito para um destino direto. Se mais tarde precisar de automações, mude depois de a importação terminar.

Como chegam os blocos do histórico?

Fora de ordem, em fases que vão das mensagens mais recentes para trás: a fase 0 cobre o último dia antes da integração, a fase 1 até ao dia 90 e a fase 2 até ao dia 180. Ordene por metadata.chunk_order se a ordem importar, e trate metadata.progress = 100 como o fim, pois a Meta observa que a fase, por si só, não indica que esta terminou. O id de uma conversa é o número de telefone do cliente, omitido quando não puder ser partilhado, e o seu contexto inclui wa_id, user_id e username. Uma mensagem enviada pela empresa tem from definido como o número da empresa e um 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" }
        }
      ]
    }]
  }]
}

Como deve ser guardada a memória de um agente?

Duas tabelas bastam. As pessoas são identificadas pelo BSUID, o user_id que a Meta acrescenta aos contactos, conversas e mensagens, com o número de telefone guardado ao lado, porque um utilizador com username pode chegar sem ele; a referência da própria Meta diz para usar o user_id para identificar um contacto. As mensagens são identificadas pelo wamid, pelo que a importação, os webhooks em tempo real e as entregas repetidas da mesma mensagem se reduzem a uma linha, e um indicador from_business regista quem falou. Indexe por pessoa e hora, já que o agente pede as últimas trocas de uma pessoa.

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

Como carregar blocos e contactos na memória?

Com inserções idempotentes, para que a ordem e as entregas repetidas deixem de ter importância. ingestHistory lê uma alteração de histórico: regista uma recusa 2593109 e segue em frente, indexa uma conversa por context.user_id ou pelo seu id, marca uma mensagem como da empresa quando from é igual a metadata.display_phone_number, e guarda um marcador [type] quando não há texto. ingestContacts faz upsert por user_id ou número de telefone e assinala os contactos removidos em vez de apagar as suas mensagens. Chame-as com change.value num destino direto, ou com o value do corpo quando o evento de um reencaminhamento for history ou 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 };
}

Como alimentar essa memória ao agente?

Com limites, nunca tudo de uma vez. memoryFor devolve o nome da pessoa na lista de contactos e as suas últimas 20 trocas, da mais antiga para a mais recente, começando sempre numa mensagem do cliente, como a maioria das APIs de chat espera; acrescente um resumo guardado das conversas mais antigas se o agente precisar de mais. Seis meses de conversas em cada prompt custam tokens em cada resposta e enterram a pergunta que está a ser feita.

Para comparar, o passo Responder com IA integrado lê no máximo 20 mensagens anteriores (10 por predefinição), e o passo Chamar o meu webhook envia as últimas 10. Ambos usam texto guardado durante a retenção que o proprietário escolhe, 30, 90 ou 365 dias (90 por predefinição), a partir do momento em que as automações foram ativadas, pelo que os seis meses de conversas importadas têm de viver na sua própria base de dados.

Como se mantém a memória atualizada depois da importação?

O mesmo destino continua a receber tráfego em tempo real: mensagens dos clientes, smb_message_echoes para as respostas escritas na aplicação, e smb_app_state_sync quando a empresa edita os seus contactos. Insira-os nas mesmas tabelas com source live ou echo. Quando um cliente muda de número de telefone, a Meta envia uma mensagem de sistema do tipo user_changed_number ou user_changed_user_id com previous_user_id, sinal para transferir as suas linhas para o novo BSUID.

Ativar as automações mais tarde remove o destino direto. Adicione o mesmo URL como URL de reencaminhamento e leia event e value de cada POST assinado, e aguarde por progress 100 antes de mudar, ou os blocos restantes só chegam por esse reencaminhamento.

Como configurar

  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.

Erros comuns

  • Guardar o destino no segundo dia. A sincronização só é pedida nas 24 horas seguintes à ligação, pelo que um endpoint guardado mais tarde recebe apenas mensagens em tempo real.
  • Ativar as automações antes de o progresso chegar a 100. O destino direto é removido de imediato, e os blocos seguintes só chegam se já houver um URL de reencaminhamento definido.
  • Tratar a fase 2 como o fim da importação. Só metadata.progress = 100 indica que a sincronização está concluída, e os blocos não chegam por ordem.
  • Identificar a memória apenas pelo número de telefone. Os ids de conversa e os contactos deixam de incluir o número quando um utilizador com username não o pode partilhar, mas o user_id continua presente.
Fazer isto com a EasyCoexistence

O pedido fica registado no registo de eventos do número, e o número é monitorizado 24/7 depois disso. De US$ 9 descendo até US$ 0.75 por número ligado por mês, à medida que acrescenta números, com os primeiros 3 dias grátis.

Perguntas frequentes

Pode a importação correr uma segunda vez?

Só através de uma nova integração. A Meta permite um pedido por integração, pelo que o número tem de ser desligado e voltar a ser ligado, e as conversas chegam então de novo; inserir pelo id da mensagem impede que a segunda passagem duplique registos.

A easyCoexistence guarda uma cópia das conversas importadas?

Não. O histórico e os contactos seguem da Meta diretamente para o seu endpoint e não ficam guardados por predefinição. Num número com automações ativas, a easyCoexistence guarda o texto das mensagens durante o período que escolher, 30, 90 ou 365 dias (90 por predefinição), e o ecrã Conversas mostra-o; as entregas reencaminhadas ficam guardadas até 7 dias, e os registos de execução 30 dias.

Quão grandes podem ser os payloads?

Um único webhook da Meta pode transportar até 3 MB, e um número movimentado envia muitos blocos de histórico. Aumente o limite do corpo da sua framework (o Express assume 100 kb por predefinição) e responda antes de escrever na base de dados.

O agente precisa da importação para funcionar?

Não. Sem ela, a memória começa na primeira mensagem após a ligação e cresce com o tráfego em tempo real. A importação faz diferença quando as conversas passadas devem moldar as respostas desde o primeiro dia, como a última encomenda de um cliente que regressa.

Continue a ler

Pronto para começar?

Configure a Coexistência do WhatsApp em minutos, não em meses. A aplicação continua a funcionar no telemóvel.

Começar período experimental gratuito

Verificado em