EntrarComeçar teste grátis
Meta Tech Provider

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

Em um número conectado pela Coexistência, a Meta pode enviar ao seu servidor, uma única vez, os contatos do app e até 180 dias de conversas individuais. Para isso, um destino de webhook direto precisa ser salvo em até 24 horas após a conexão, e a empresa precisa aceitar no app. Os blocos podem chegar fora de ordem, e progress 100 marca o fim. Armazene as mensagens pelo id, use o BSUID como chave das pessoas e passe os turnos recentes ao agente.

A easyCoexistence conecta o número pelo fluxo de Coexistência da Meta e, quando você salva o seu endpoint como destino de webhook direto em até 24 horas, pede à Meta, uma única vez, os contatos e até 180 dias de conversas, que vão direto para o seu servidor.

180 days

Até onde a sincronização do histórico volta a partir do onboarding; a tabela de recursos da Meta descreve isso como os 6 meses mais recentes.

24 hours

Prazo após o onboarding para solicitar contatos e histórico; cada solicitação só pode ser feita uma vez.

100

Valor de metadata.progress que marca a sincronização do histórico como concluída; segundo a Meta, o phase sozinho não indica isso.

2593109

Código de erro em um webhook de histórico quando a empresa desativou o compartilhamento de histórico no app do WhatsApp Business.

3 phases

A fase 0 cobre do dia 0 ao dia 1 antes do onboarding, a fase 1 do dia 1 ao 90 e a fase 2 do dia 90 ao 180.

3 MB

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

O que a importação traz e o que fica de fora?

Dois fluxos, ambos vindos do app do WhatsApp Business no celular. Os contatos chegam como webhooks smb_app_state_sync, uma entrada por contato com action add ou remove, e o mesmo campo continua informando os contatos que a empresa adiciona, edita ou remove depois no app. As conversas chegam como webhooks history: conversas individuais de até 180 dias antes do onboarding, nos dois sentidos, com o status de entrega. O que não vem na importação está listado abaixo, e uma memória construída sobre ela 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 chegue ao seu servidor?

Deixe o endpoint no ar antes de conectar o número e salve-o como destino de webhook direto do número em até 24 horas após a conexão: na página do número, em Encaminhar mensagens recebidas para o seu próprio webhook, com set_webhook_destination pela sua IA, ou como webhook_url em uma sessão de conexão da Partner API. É ao salvar esse destino que a easyCoexistence pede a sincronização à Meta, primeiro os contatos e depois o histórico, uma vez por onboarding. A requisição e os ids de requisição da Meta aparecem no registro de eventos do número como history_sync_requested.

A empresa precisa aceitar compartilhar o histórico quando o app pedir, durante a conexão. Um número cujas mensagens passam pela easyCoexistence (Pela easyCoexistence, no cartão Para onde vão as mensagens recebidas), mesmo com uma Forward URL, não recebe a importação, porque a solicitação só é feita para um destino direto. Se você precisar de automações depois, mude de modo quando a importação terminar.

Como chegam os blocos do histórico?

Fora de ordem, em fases que vão das mensagens mais recentes para as mais antigas: a fase 0 cobre o último dia antes do onboarding, a fase 1 vai até o dia 90 e a fase 2 até o dia 180. Ordene por metadata.chunk_order se a ordem importar e trate metadata.progress = 100 como o fim, pois a Meta observa que o phase não indica que uma fase terminou. O id de uma conversa é o número de telefone do cliente, omitido quando não pode ser compartilhado, e o context dela traz wa_id, user_id e username. Uma mensagem enviada pela empresa tem from igual ao 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 armazenar a memória de um agente?

Duas tabelas bastam. As pessoas têm como chave o BSUID, o user_id que a Meta adiciona aos contatos, às conversas e às mensagens, com o número de telefone guardado ao lado, pois um usuário com username pode chegar sem ele; a própria referência da Meta manda usar o user_id para identificar um contato. As mensagens têm como chave o wamid, de modo que a importação, os webhooks ao vivo e as entregas repetidas da mesma mensagem viram uma única linha, e uma flag from_business registra quem falou. Crie índices por pessoa e horário, já que o agente pede os últimos turnos 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 os blocos e os contatos nessa memória?

Com inserções idempotentes, para que a ordem e as reentregas deixem de importar. ingestHistory lê uma mudança de histórico: registra uma recusa 2593109 e segue adiante, usa context.user_id ou o id como chave da conversa, marca a mensagem como da empresa quando from é igual a metadata.display_phone_number e grava um marcador [type] quando não há texto. ingestContacts faz upsert por user_id ou número de telefone e sinaliza os contatos removidos em vez de apagar as mensagens deles. Chame as duas com change.value em um destino direto, ou com o value do corpo quando o event de um forward 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 passar essa memória ao agente?

Com limite, nunca tudo de uma vez. memoryFor devolve o nome da pessoa na agenda e os últimos 20 turnos dela, do mais antigo ao mais recente, começando por um turno do cliente, como a maioria das APIs de chat espera. Acrescente um resumo salvo das conversas mais antigas se o agente precisar de mais. Seis meses de conversas em cada prompt custam tokens a cada resposta e enterram a pergunta que está sendo feita.

Para comparação, a etapa nativa Reply with AI lê no máximo 20 mensagens anteriores (10 por padrão), e a etapa Call my webhook envia as últimas 10. As duas usam texto guardado pela retenção que o dono escolhe, 30, 90 ou 365 dias (90 por padrão), a partir do momento em que as automações foram ativadas, e por isso os seis meses de conversas importadas precisam ficar no seu próprio banco de dados.

Como a memória se mantém atualizada após a importação?

O mesmo destino continua recebendo o tráfego ao vivo: mensagens dos clientes, smb_message_echoes para respostas digitadas no app e smb_app_state_sync quando a empresa edita os contatos. Insira tudo 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, o sinal para mover as linhas dele para o novo BSUID.

Ativar as automações depois remove o destino direto. Adicione a mesma URL como Forward URL e leia event e value de cada POST assinado. Espere progress chegar a 100 antes de mudar de modo, senão os blocos restantes só chegam por esse forward.

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

  • Salvar o destino no segundo dia. A sincronização só é solicitada em até 24 horas após a conexão, então um endpoint salvo depois começa apenas com as mensagens ao vivo.
  • Ativar as automações antes de progress chegar a 100. O destino direto é removido na hora, e os blocos seguintes só chegam se uma Forward URL já estiver definida.
  • Tratar a fase 2 como o fim da importação. Só metadata.progress = 100 indica que a sincronização terminou, e os blocos não são entregues em sequência.
  • Usar só o número de telefone como chave da memória. Os ids de conversa e os contatos vêm sem o número quando um usuário com username não pode compartilhá-lo, mas o user_id continua presente.
Fazendo isso com o EasyCoexistence

A solicitação fica no registro de eventos do número, e o número passa a ser monitorado 24/7. De R$ 29,90 até R$ 3,90 por número por mês, caindo conforme você adiciona números, com os primeiros 3 dias grátis.

O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.

Perguntas frequentes

Dá para fazer a importação uma segunda vez?

Só com um novo onboarding. A Meta permite uma solicitação por onboarding, então o número precisa ser desconectado e conectado de novo, e as conversas chegam outra vez. Inserir pelo id da mensagem impede que a segunda passagem duplique qualquer registro.

A easyCoexistence guarda uma cópia das conversas importadas?

Não. O histórico e os contatos vão da Meta direto para o seu endpoint e não são armazenados por padrão. Em um número com automações ativas, a easyCoexistence guarda o texto das mensagens pelo período que você escolher, 30, 90 ou 365 dias (90 por padrão), e a tela Conversas o mostra; as entregas encaminhadas ficam guardadas por até 7 dias, e os logs de execução por 30 dias.

Qual é o tamanho máximo dos payloads?

Um único webhook da Meta pode ter até 3 MB, e um número movimentado envia muitos blocos de histórico. Aumente o limite de corpo do seu framework (o padrão do Express é 100 kb) e confirme o recebimento antes de gravar no banco de dados.

Um agente precisa da importação para funcionar?

Não. Sem ela, a memória começa na primeira mensagem após a conexão e cresce com o tráfego ao vivo. A importação faz diferença quando conversas passadas devem orientar as respostas desde o primeiro dia, como o último pedido de um cliente que volta.

Continue lendo

Pronto para começar?

Configure o WhatsApp Coexistence em minutos, não em meses. O aplicativo continua funcionando no celular.

Começar teste grátis

Verificado em