Dale memoria a tu agente de IA: seis meses de chats y contactos de WhatsApp
Con un número conectado mediante Coexistencia, Meta puede enviar a tu servidor, una sola vez, los contactos de la app y hasta 180 días de chats uno a uno, siempre que guardes un destino de webhook directo en las 24 horas siguientes a la conexión y la empresa lo acepte en la app. Los bloques pueden llegar desordenados y el progreso 100 marca el final. Guarda los mensajes por id, identifica a las personas por BSUID y pasa al agente los turnos recientes.
easyCoexistence conecta el número mediante el flujo de Coexistencia de Meta y, cuando guardas tu endpoint como destino de webhook directo en las 24 horas siguientes, pide a Meta una sola vez los contactos y hasta 180 días de chats, que llegan directamente a tu servidor.
Hasta dónde llega la sincronización del historial desde la incorporación; la tabla de funciones de Meta lo describe como los 6 meses más recientes.
Plazo tras la incorporación para pedir los contactos y el historial; cada petición solo puede hacerse una vez.
Valor de metadata.progress que marca la sincronización del historial como completa; según Meta, la fase por sí sola no lo indica.
Código de error en un webhook de historial cuando la empresa desactivó el uso compartido del historial en la app de WhatsApp Business.
La fase 0 cubre del día 0 al 1 antes de la incorporación, la fase 1 los días 1 a 90 y la fase 2 los días 90 a 180.
Tamaño máximo de payload de webhook que envía Meta, que determina el límite de tamaño del cuerpo que necesita tu endpoint.
¿Qué trae la importación y qué se queda fuera?
Dos flujos, ambos desde la app de WhatsApp Business en el teléfono. Los contactos llegan como webhooks smb_app_state_sync, con una entrada por contacto y acción add o remove, y ese mismo campo sigue informando de los contactos que la empresa añade, edita o elimina después en la app. Los chats llegan como webhooks de historial: conversaciones uno a uno de hasta 180 días antes de la incorporación, en ambos sentidos, con su estado de entrega. Lo que no se transfiere se detalla más abajo, así que una memoria construida a partir de la importación no debe contar con ello.
¿Cómo te aseguras de que la importación llegue a tu servidor?
Ten el endpoint activo antes de conectar el número y guárdalo como destino de webhook directo del número en las 24 horas siguientes a la conexión: en la página del número, en Enrutar los mensajes entrantes a tu propio webhook, con set_webhook_destination desde tu IA, o como webhook_url en una sesión de conexión de la Partner API. Guardarlo es lo que hace que easyCoexistence pida la sincronización a Meta, primero los contactos y luego el historial, una vez por incorporación; la petición y los ids de petición de Meta aparecen en el registro de eventos del número como history_sync_requested.
La empresa debe aceptar compartir el historial cuando la app lo pregunte durante la conexión. Un número cuyos mensajes llegan a través de easyCoexistence («A través de easyCoexistence» en la tarjeta Adónde van los mensajes entrantes), aunque tenga una Forward URL, no recibe la importación, porque la petición solo se hace para un destino directo. Si más adelante necesitas automatizaciones, cambia cuando termine la importación.
¿Cómo llegan los bloques del historial?
Desordenados, en fases que van de los mensajes más recientes hacia atrás: la fase 0 cubre el último día antes de la incorporación, la fase 1 hasta el día 90 y la fase 2 hasta el día 180. Ordénalos por metadata.chunk_order si el orden importa, y toma metadata.progress = 100 como el final, ya que Meta advierte que la fase no indica que una fase haya terminado. El id de una conversación es el número de teléfono del cliente, que se omite cuando no puede compartirse, y su context incluye wa_id, user_id y username. Un mensaje enviado por la empresa tiene en from el número de la empresa y un 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" }
}
]
}]
}]
}¿Cómo se debe almacenar la memoria de un agente?
Bastan dos tablas. Las personas tienen como clave el BSUID, el user_id que Meta añade a contactos, conversaciones y mensajes, con el número de teléfono guardado al lado, porque un usuario con username puede llegar sin él; la propia referencia de Meta indica usar user_id para identificar a un contacto. Los mensajes tienen como clave su wamid, de modo que la importación, los webhooks en vivo y las entregas reintentadas del mismo mensaje quedan en una sola fila, y un indicador from_business registra quién habló. Crea índices por persona y fecha, ya que el agente pide los últimos turnos de una persona.
-- 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);¿Cómo se cargan los bloques y los contactos?
Con inserciones idempotentes, para que el orden y las entregas repetidas dejen de importar. ingestHistory lee un cambio de historial: registra un rechazo 2593109 y sigue, identifica una conversación por context.user_id o por su id, marca un mensaje como de la empresa cuando from coincide con metadata.display_phone_number y guarda un marcador [type] cuando no hay texto. ingestContacts hace upsert por user_id o número de teléfono y marca los contactos eliminados en lugar de borrar sus mensajes. Llámalas con change.value en un destino directo, o con el value del cuerpo cuando el event de un reenvío es history o 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 };
}¿Cómo le pasas esa memoria al agente?
Acotada, nunca toda de golpe. memoryFor devuelve el nombre de la persona según la agenda de contactos y sus últimos 20 turnos, del más antiguo al más reciente, empezando por un turno del cliente, como espera la mayoría de las APIs de chat; añade un resumen guardado de las conversaciones anteriores si el agente necesita más. Meter seis meses de chats en cada prompt cuesta tokens en cada respuesta y entierra la pregunta que se está haciendo.
Como referencia, el paso integrado Responder con IA lee como máximo 20 mensajes anteriores (10 por defecto), y el paso Llamar a mi webhook envía los últimos 10. Ambos se basan en texto que se conserva durante la retención que elige el propietario, 30, 90 o 365 días (90 por defecto), desde el momento en que se activaron las automatizaciones; por eso los seis meses de chats importados tienen que estar en tu propia base de datos.
¿Cómo se mantiene actualizada la memoria después de la importación?
El mismo destino sigue recibiendo el tráfico en vivo: mensajes de clientes, smb_message_echoes para las respuestas escritas en la app y smb_app_state_sync cuando la empresa edita sus contactos. Insértalos en las mismas tablas con source live o echo. Cuando un cliente cambia de número de teléfono, Meta envía un mensaje del sistema de tipo user_changed_number o user_changed_user_id con previous_user_id: es la señal para mover sus filas al nuevo BSUID.
Activar las automatizaciones más adelante elimina el destino directo. Añade la misma URL como Forward URL y lee event y value de cada POST firmado, y espera a que el progreso llegue a 100 antes de cambiar, o los bloques restantes solo te llegarán a través de ese reenvío.
Cómo configurarlo
- 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.
Errores comunes
- Guardar el destino el segundo día. La sincronización solo se pide en las 24 horas siguientes a la conexión, así que un endpoint guardado más tarde empieza solo con los mensajes en vivo.
- Activar las automatizaciones antes de que el progreso llegue a 100. El destino directo se elimina de inmediato, y los bloques posteriores solo te llegan si ya hay una Forward URL configurada.
- Dar por terminada la importación en la fase 2. Solo metadata.progress = 100 indica que la sincronización está completa, y los bloques no se entregan en orden.
- Usar solo el número de teléfono como clave de la memoria. Los ids de conversación y los contactos omiten el número cuando un usuario con username no puede compartirlo, mientras que user_id sigue presente.
La petición queda en el registro de eventos del número, y a partir de ahí el número se supervisa 24/7. De US$ 9 a US$ 0.75 por número al mes, un precio que baja a medida que añades números, con los primeros 3 días gratis.
Preguntas frecuentes
¿Se puede repetir la importación?
Solo con una nueva incorporación. Meta permite una petición por incorporación, así que hay que desconectar el número y volver a conectarlo, y los chats llegan de nuevo; insertar por id de mensaje evita que la segunda pasada duplique nada.
¿easyCoexistence guarda una copia de los chats importados?
No. El historial y los contactos van de Meta directamente a tu endpoint y no se almacenan por defecto. Para un número con automatizaciones activadas, easyCoexistence conserva el texto de los mensajes durante el periodo que elijas, 30, 90 o 365 días (90 por defecto), y la pantalla Conversaciones lo muestra; las entregas reenviadas se conservan hasta 7 días, y los registros de ejecución, 30 días.
¿Qué tamaño pueden tener los payloads?
Un solo webhook de Meta puede llevar hasta 3 MB, y un número con mucho movimiento envía muchos bloques de historial. Aumenta el límite de cuerpo de tu framework (Express usa 100 kb por defecto) y confirma la recepción antes de escribir en la base de datos.
¿Un agente necesita la importación para funcionar?
No. Sin ella, la memoria empieza con el primer mensaje después de la conexión y crece con el tráfico en vivo. La importación es útil cuando las conversaciones pasadas deben influir en las respuestas desde el primer día, por ejemplo el último pedido de un cliente que vuelve.
Sigue leyendo
¿Listo para empezar?
Configura WhatsApp Coexistence en minutos, no en meses. La app sigue funcionando en el teléfono.
Empezar prueba gratisVerificado el