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.
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.
Prazo após o onboarding para solicitar contatos e histórico; cada solicitação só pode ser feita uma vez.
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.
Código de erro em um webhook de histórico quando a empresa desativou o compartilhamento de histórico no app do WhatsApp Business.
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.
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.
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.
{
"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.
-- 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: 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
- 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.
- Connect the numberRun the connection from the dashboard, and accept sharing chat history when the WhatsApp Business app asks.
- 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.
- Store chunks until progress 100Insert contacts and messages as they come; the event log shows history_sync_requested once the request went to Meta.
- 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.
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átisVerificado em