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.
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.
Tempo após a integração para pedir contactos e histórico; cada pedido só pode ser feito uma vez.
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.
Código de erro num webhook de histórico quando a empresa desativou a partilha do histórico na aplicação WhatsApp Business.
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.
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.
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.
{
"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.
-- 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: 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
- 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
- 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.
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 gratuitoVerificado em