Crea un agente de IA para WhatsApp en Node.js y Python con un número en Coexistencia
Recibe los mensajes del número reenviados con una firma HMAC que verificas (X-EC-Signature) o directamente del webhook de Meta, con un secreto en la URL. Después omite cualquier id de mensaje ya atendido, no respondas en un chat donde un eco muestre que una persona contestó desde el teléfono y envía la respuesta de tu modelo por la Cloud API solo dentro de las 24 horas siguientes al último mensaje del cliente.
easyCoexistence conecta el número que el negocio sigue usando en la app de WhatsApp Business con la Cloud API de Meta, entrega a tu código sus credenciales mediante get_api_credentials y enruta los mensajes directamente de Meta a tu servidor o a través de un reenvío firmado con las automatizaciones activas.
Mayor diferencia aceptada entre la t de la firma y tu reloj; cada reintento se vuelve a firmar con una t nueva.
Cuánto espera un POST reenviado una respuesta 2xx antes de que easyCoexistence programe un reintento de esa entrega.
Durante cuánto tiempo reintenta Meta un webhook directo que no recibió HTTP 200, lo que puede entregar el mismo mensaje dos veces.
Ventana de atención al cliente tras el último mensaje del usuario; fuera de ella, Meta solo acepta mensajes de plantilla.
Throughput fijo de un número usado a la vez con la app de WhatsApp Business y con la Cloud API.
¿Qué ruta debe usar un agente programado?
Reenviado significa que el número sigue en el modo Automatizaciones activas: Meta entrega a easyCoexistence, las automatizaciones pueden seguir ejecutándose y una copia firmada de cada cambio de Meta llega a tu URL de reenvío. Hay una variante que no necesita reenvío: el paso Llamar a mi webhook de una automatización hace un POST con el mensaje a tu endpoint y envía el {"reply"} que devuelvas en un máximo de 20 segundos, con la deduplicación, la pausa por teléfono y el control de 24 horas ya resueltos por easyCoexistence.
Directo significa que Meta envía su propio webhook directamente a tu endpoint, configurado con set_webhook_destination, y easyCoexistence nunca ve los mensajes. Las automatizaciones quedan desactivadas para ese número, así que todas las protecciones corren por tu cuenta, igual que la importación del historial de 6 meses cuando el destino se guarda dentro de las 24 horas posteriores a la conexión. Los ejemplos de abajo cubren los tres puntos de entrada con un núcleo compartido.
| Forwarded, signed | Direct from Meta | |
|---|---|---|
| Number mode | Automations on (managed) | Direct to your server |
| Body | One Meta change: id, event, received_at, connection, value | Meta's envelope: object, entry, changes |
| Authentication | X-EC-Signature, HMAC-SHA256 with a per-number secret | A secret in the URL path |
| Acknowledge | Any 2xx within 10 seconds | HTTP 200; Meta retries other codes |
| Retries | 7 attempts over about 33 hours | Up to 7 days |
| Reply | Graph API, or {"reply"} to a Call my webhook step | Graph API |
| History import | Not requested | Requested if saved within 24 hours of connecting |
¿Qué hace el agente con un mensaje, en Node.js?
agent.mjs contiene la lógica que comparten ambas rutas. Registra la hora del último mensaje del cliente, se aparta durante 4 horas de un chat cuando un evento smb_message_echoes muestra que alguien respondió desde la app de WhatsApp Business (el comportamiento predeterminado de las automatizaciones de easyCoexistence), omite un id de mensaje que ya atendió y envía solo dentro de la ventana de 24 horas. La ventana se mide desde la marca de tiempo del propio mensaje, no desde que te llegó, porque una entrega reintentada puede llegar con horas de retraso.
Los usuarios se identifican por BSUID (from_user_id, o to_user_id en los ecos) con el número de teléfono como alternativa, y a un usuario conocido solo por BSUID se le responde con recipient en lugar de to. La llamada al modelo usa cualquier API de chat completions compatible con OpenAI; si lo prefieres, sustitúyela por el SDK de tu proveedor.
// agent.mjs: what the agent does with one Meta change, whichever route brought it.
const DAY = 24 * 3600 * 1000;
const PAUSE = 4 * 3600 * 1000; // quiet time after a person replies (automations default to 4 h)
const seen = new Set(); // handled ids: use Redis or your database in production
const lastInbound = new Map(); // user -> ms of their last message
const quietUntil = new Map(); // user -> ms until which a person has the chat
export function firstTime(id) {
if (seen.has(id)) return false;
seen.add(id);
return true;
}
export async function handleChange(field, value) {
if (field === "smb_message_echoes") {
// Someone answered from the WhatsApp Business app: step back on that chat.
for (const e of value.message_echoes ?? []) {
quietUntil.set(e.to_user_id ?? e.to, Number(e.timestamp) * 1000 + PAUSE);
}
return;
}
if (field !== "messages") return; // statuses ride in value.statuses: ignored here
for (const m of value.messages ?? []) {
if (!firstTime(m.id)) continue; // Meta delivered this message before
const user = m.from_user_id ?? m.from; // BSUID first, phone number as fallback
lastInbound.set(user, Math.max(Number(m.timestamp) * 1000, lastInbound.get(user) ?? 0));
if ((quietUntil.get(user) ?? 0) > Date.now()) continue; // a person has this chat
if (m.type !== "text") continue; // media: fetch it by id first (see the FAQ)
const reply = await askModel([{ role: "user", content: m.text.body }]);
if (!reply) continue;
if (Date.now() - lastInbound.get(user) >= DAY) continue; // window closed: template only
await sendText({ phone: m.from, bsuid: m.from_user_id }, reply);
}
}
// Any OpenAI-compatible chat completions API (OpenAI, OpenRouter...).
export async function askModel(turns) {
const res = await fetch(`${process.env.AI_BASE_URL}/chat/completions`, {
method: "POST",
headers: { Authorization: `Bearer ${process.env.AI_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
model: process.env.AI_MODEL,
messages: [{ role: "system", content: process.env.AI_INSTRUCTIONS ?? "Answer briefly." }, ...turns],
}),
});
if (!res.ok) throw new Error(`AI provider answered ${res.status}`);
const data = await res.json();
return data.choices?.[0]?.message?.content?.trim() ?? "";
}
// send_endpoint and access_token come from get_api_credentials.
async function sendText({ phone, bsuid }, text) {
const res = await fetch(process.env.SEND_ENDPOINT, {
method: "POST",
headers: { Authorization: `Bearer ${process.env.WA_TOKEN}`, "Content-Type": "application/json" },
body: JSON.stringify({
messaging_product: "whatsapp",
recipient_type: "individual",
...(phone ? { to: phone } : { recipient: bsuid }), // a BSUID-only user gets recipient
type: "text",
text: { body: text.slice(0, 4096) },
}),
});
if (!res.ok) throw new Error(`Graph API answered ${res.status}: ${await res.text()}`);
}¿Cómo se verifican y enrutan los eventos en Node.js?
server.mjs expone los tres puntos de entrada. /ec/forward recibe los reenvíos de un número gestionado: verifica X-EC-Signature sobre los bytes sin procesar con el secreto de reenvío del número, responde 200 antes de hacer cualquier trabajo y omite un id de entrega que ya aceptó, porque un reintento lleva el mismo id con una firma nueva. En el cuerpo, event es el nombre de campo de Meta y value es el cambio de Meta, sin modificar. /ec/agent responde a un paso Llamar a mi webhook, firmado con el secreto de firma propio de esa automatización, y convierte el historial en turnos de chat. /meta/:secret es la ruta directa: responde al GET de verificación de Meta con el hub.challenge sin procesar y solo acepta POST en la ruta que contiene el secreto.
La clave HMAC es el secreto completo, incluido el prefijo whsec_, como texto UTF-8. express.raw conserva los bytes intactos, y su límite de 5 MB deja margen para payloads de Meta de hasta 3 MB.
// server.mjs: Node 18+, npm i express, then node server.mjs
import crypto from "node:crypto";
import express from "express";
import { askModel, firstTime, handleChange } from "./agent.mjs";
const app = express();
// X-EC-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, keyed with the whole secret.
export function verifyEc(raw, header, secret, toleranceSec = 300) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(String(header ?? "").trim());
if (!m || !Buffer.isBuffer(raw) || !secret) return false;
if (Math.abs(Date.now() / 1000 - Number(m[1])) > toleranceSec) return false; // stale or replayed
const expected = crypto.createHmac("sha256", secret).update(`${m[1]}.`).update(raw).digest();
return crypto.timingSafeEqual(expected, Buffer.from(m[2], "hex"));
}
function sameSecret(a, b) {
const x = Buffer.from(String(a)), y = Buffer.from(String(b ?? ""));
return x.length === y.length && crypto.timingSafeEqual(x, y);
}
// Route A, forwarded: a managed number's Forward URL. One Meta change per POST.
app.post("/ec/forward", express.raw({ type: "*/*", limit: "5mb" }), (req, res) => {
if (!verifyEc(req.body, req.get("X-EC-Signature"), process.env.EC_FORWARD_SECRET)) return res.sendStatus(401);
res.sendStatus(200); // acknowledge inside 10 s, then work
const d = JSON.parse(req.body.toString("utf8"));
if (!firstTime(`delivery:${d.id}`)) return; // a retry of a delivery already taken
handleChange(d.event, d.value).catch(console.error); // d.event is the Meta field name
});
// Route A, synchronous: a "Call my webhook" step. Answer {"reply"} within 20 s.
app.post("/ec/agent", express.raw({ type: "*/*", limit: "1mb" }), async (req, res) => {
if (!verifyEc(req.body, req.get("X-EC-Signature"), process.env.EC_AUTOMATION_SECRET)) return res.sendStatus(401);
const step = JSON.parse(req.body.toString("utf8"));
const turns = step.history.map((h) => ({ role: h.direction === "in" ? "user" : "assistant", content: h.text }));
while (turns[0]?.role === "assistant") turns.shift();
if (!turns.length) turns.push({ role: "user", content: step.message?.text ?? "" }); // tests carry no history
res.json({ reply: await askModel(turns) }); // step.dry_run is true on "Test it"
});
// Route B, direct: Meta's own envelope. The secret path is the credential.
app.get("/meta/:secret", (req, res) => {
if (!sameSecret(req.params.secret, process.env.PATH_SECRET)) return res.sendStatus(404);
if (req.query["hub.mode"] === "subscribe" && req.query["hub.verify_token"] === process.env.VERIFY_TOKEN) {
return res.type("text/plain").send(String(req.query["hub.challenge"]));
}
res.sendStatus(403);
});
app.post("/meta/:secret", express.json({ limit: "5mb" }), (req, res) => {
if (!sameSecret(req.params.secret, process.env.PATH_SECRET)) return res.sendStatus(404);
res.sendStatus(200); // Meta retries anything but 200
for (const entry of req.body.entry ?? []) {
for (const change of entry.changes ?? []) handleChange(change.field, change.value).catch(console.error);
}
});
app.listen(process.env.PORT ?? 3000);¿Cómo se ve el mismo agente en Python?
Un solo archivo Flask con las mismas tres rutas y las mismas reglas. request.get_data() devuelve el cuerpo sin procesar para el HMAC, hmac.compare_digest hace la comparación en tiempo constante y el trabajo se ejecuta en un hilo en segundo plano después del 200, así que ni easyCoexistence ni Meta esperan a tu modelo. Ejecútalo con flask --app agent run durante el desarrollo y detrás de gunicorn u otro servidor WSGI en producción.
El conjunto y los diccionarios en memoria sirven para un solo proceso. Con varios workers o instancias, pásalos a Redis o a tu base de datos, con una escritura que solo grabe si la clave no existe y con expiración para los ids de mensaje; si no, dos workers responderán al mismo mensaje.
# agent.py: pip install flask requests, then flask --app agent run
import hashlib, hmac, json, os, re, threading, time
import requests
from flask import Flask, abort, request
app = Flask(__name__)
DAY, PAUSE = 24 * 3600, 4 * 3600
seen, last_inbound, quiet_until = set(), {}, {} # use Redis or a database in production
lock = threading.Lock()
def verify_ec(raw: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
m = re.fullmatch(r"t=([0-9]+),v1=([0-9a-f]{64})", (header or "").strip())
if not m or not secret or abs(time.time() - int(m[1])) > tolerance:
return False
expected = hmac.new(secret.encode(), m[1].encode() + b"." + raw, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, m[2])
def first_time(key: str) -> bool:
with lock:
if key in seen:
return False
seen.add(key)
return True
def ask_model(turns: list) -> str: # any OpenAI-compatible chat completions API
r = requests.post(f"{os.environ['AI_BASE_URL']}/chat/completions", timeout=30,
headers={"Authorization": f"Bearer {os.environ['AI_KEY']}"},
json={"model": os.environ["AI_MODEL"], "messages": [
{"role": "system", "content": os.environ.get("AI_INSTRUCTIONS", "Answer briefly.")}, *turns]})
r.raise_for_status()
return (r.json()["choices"][0]["message"]["content"] or "").strip()
def send_text(phone, bsuid, text: str) -> None: # SEND_ENDPOINT and WA_TOKEN: get_api_credentials
to = {"to": phone} if phone else {"recipient": bsuid}
r = requests.post(os.environ["SEND_ENDPOINT"], timeout=15,
headers={"Authorization": f"Bearer {os.environ['WA_TOKEN']}"},
json={"messaging_product": "whatsapp", "recipient_type": "individual", **to,
"type": "text", "text": {"body": text[:4096]}})
r.raise_for_status()
def handle_change(field: str, value: dict) -> None:
if field == "smb_message_echoes": # a person answered from the app: step back
for e in value.get("message_echoes", []):
quiet_until[e.get("to_user_id") or e.get("to")] = int(e["timestamp"]) + PAUSE
return
if field != "messages":
return
for m in value.get("messages", []):
if not first_time(m["id"]): # Meta delivered this message before
continue
user = m.get("from_user_id") or m.get("from")
last_inbound[user] = max(int(m["timestamp"]), last_inbound.get(user, 0))
if quiet_until.get(user, 0) > time.time() or m.get("type") != "text":
continue
reply = ask_model([{"role": "user", "content": m["text"]["body"]}])
if reply and time.time() - last_inbound[user] < DAY: # past 24 h: template only
send_text(m.get("from"), m.get("from_user_id"), reply)
def later(field, value):
threading.Thread(target=handle_change, args=(field, value), daemon=True).start()
@app.post("/ec/forward") # route A: a managed number's Forward URL
def forward():
raw = request.get_data()
if not verify_ec(raw, request.headers.get("X-EC-Signature", ""), os.environ["EC_FORWARD_SECRET"]):
abort(401)
d = json.loads(raw)
if first_time("delivery:" + d["id"]): # skip retries of a delivery already taken
later(d["event"], d["value"])
return "", 200
@app.post("/ec/agent") # route A: a "Call my webhook" step, answer within 20 s
def agent_step():
raw = request.get_data()
if not verify_ec(raw, request.headers.get("X-EC-Signature", ""), os.environ["EC_AUTOMATION_SECRET"]):
abort(401)
step = json.loads(raw)
turns = [{"role": "user" if h["direction"] == "in" else "assistant", "content": h["text"]}
for h in step["history"]]
while turns and turns[0]["role"] == "assistant":
turns.pop(0)
turns = turns or [{"role": "user", "content": step["message"]["text"] or ""}]
return {"reply": ask_model(turns)}
@app.get("/meta/<secret>") # route B: Meta's GET handshake
def meta_handshake(secret):
if not hmac.compare_digest(secret.encode(), os.environ["PATH_SECRET"].encode()):
abort(404)
if (request.args.get("hub.mode") == "subscribe"
and request.args.get("hub.verify_token") == os.environ["VERIFY_TOKEN"]):
return request.args.get("hub.challenge", ""), 200, {"Content-Type": "text/plain"}
abort(403)
@app.post("/meta/<secret>") # route B: Meta's envelope, straight from Meta
def meta_events(secret):
if not hmac.compare_digest(secret.encode(), os.environ["PATH_SECRET"].encode()):
abort(404)
for entry in (request.get_json(silent=True) or {}).get("entry", []):
for change in entry.get("changes", []):
later(change.get("field"), change.get("value", {}))
return "", 200¿Cómo se evitan las respuestas duplicadas?
Los duplicados tienen seis causas habituales, y los ejemplos de arriba resuelven las cinco primeras:
- Reintentos de Meta. Un webhook directo se reintenta durante hasta 7 días ante cualquier respuesta que no sea HTTP 200; guarda los ids de mensaje y omite los que ya atendiste.
- Reintentos del reenvío. easyCoexistence reintenta, con el mismo id, una entrega que no recibió un 2xx en 10 segundos; omite los ids ya aceptados y deduplica además por id de mensaje, porque un cambio que Meta vuelve a entregar se reenvía con un id nuevo.
- Confirmaciones lentas. Responde primero y trabaja después; un manejador que espera al modelo agota el tiempo de espera y el mismo evento vuelve a llegar.
- Una persona en el teléfono. Un evento
smb_message_echoessignifica que alguien respondió desde la app; no respondas en ese chat durante unas horas. - Varios workers. Los conjuntos en memoria no se comparten entre procesos; pasa los registros a Redis o a tu base de datos.
- Dos agentes respondiendo. Una automatización de respuesta con IA y tu propio agente en los mismos chats responden los dos, y tus envíos por la Graph API no son ecos, así que no pausan las automatizaciones. Deja un solo responsable de las respuestas por número.
¿De dónde salen los secretos y las credenciales?
Del panel o del conector MCP, y solo deben estar en el entorno de tu servidor. get_api_credentials devuelve graph_api_base, waba_id, phone_number_id, send_endpoint y access_token, el token propio del negocio; la página del número muestra los mismos valores en Conecta tu propio sistema. Si access_token es null, vuelve a conectar el número desde una computadora con Reconectar para emitir un token. Trata el token como una contraseña, porque cualquiera que lo tenga puede enviar mensajes en nombre del negocio.
Errores comunes
- Verificar el HMAC sobre JSON serializado de nuevo. json.dumps de Python añade por defecto espacios después de los separadores, así que un cuerpo parseado y vuelto a serializar ya no coincide; verifica los bytes sin procesar.
- Decodificar el secreto en base64 o quitarle el prefijo whsec_. La clave es la cadena completa como texto UTF-8, exactamente como se te mostró una sola vez.
- Validar X-Hub-Signature-256 en la ruta directa con el app secret de tu propia app de Meta. Meta firma con el app secret de easyCoexistence, que no se comparte, así que los eventos legítimos fallan; autentica con el secreto de la ruta.
- Calcular la ventana desde la hora de llegada. Un reenvío reintentado horas después conserva la marca de tiempo original de Meta; compara con ella, o el agente responderá pasadas las 24 horas y Meta rechazará el envío.
Cada número se monitorea 24/7, con alertas cuando se cae una conexión. De US$ 9 a US$ 0.75 por número al mes, un precio que baja a medida que agregas números, con los primeros 3 días gratis.
Preguntas frecuentes
¿Puede el agente entender notas de voz y fotos?
Sí, con tu propio código. El payload de Meta incluye el id del archivo multimedia: descárgalo con GET /<media-id> y el token del número, descarga la URL devuelta con el mismo encabezado Authorization y luego transcribe o describe el contenido con tu modelo. Las automatizaciones solo ven marcadores como [voice message].
¿Qué modelos pueden usar los ejemplos?
Cualquier modelo detrás de un endpoint de chat completions compatible con OpenAI, incluidos los de OpenAI y los disponibles a través de OpenRouter; también puedes reemplazar askModel y ask_model por el SDK de tu proveedor. easyCoexistence nunca cobra por la IA: tu proveedor te factura directamente.
¿Puede el agente iniciar una conversación?
Solo con una plantilla aprobada, enviada con type template al mismo endpoint de envío. En un número en Coexistencia, las plantillas se envían solo por la API, nunca desde la app del teléfono, y Meta las cobra por mensaje a la propia cuenta de WhatsApp Business del negocio.
¿Un solo agente puede atender varios números?
Sí. Enruta por value.metadata.phone_number_id o connection.phone_number_id y guarda un endpoint de envío, un token y un secreto de reenvío por número, ya que cada número tiene los suyos.
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