Crie um agente de IA para WhatsApp em Node.js e Python em um número com Coexistência
Receba as mensagens do número encaminhadas com uma assinatura HMAC que você verifica (X-EC-Signature) ou direto do webhook da Meta, com um segredo na URL. Depois, ignore qualquer id de mensagem já tratado, fique em silêncio na conversa em que um eco mostre que uma pessoa respondeu pelo celular e envie a resposta do seu modelo pela Cloud API somente até 24 horas após a última mensagem do cliente.
A easyCoexistence conecta o número que o negócio continua usando no app do WhatsApp Business à Cloud API da Meta, entrega ao seu código as credenciais por meio de get_api_credentials e roteia as mensagens direto da Meta para o seu servidor ou por um encaminhamento assinado com as automações ligadas.
Maior diferença aceita entre o t da assinatura e o seu relógio; cada repetição é assinada de novo com um t novo.
Tempo que um POST encaminhado espera por um 2xx antes que a easyCoexistence agende a repetição dessa entrega.
Tempo durante o qual a Meta repete um webhook direto que não recebeu HTTP 200, o que pode entregar a mesma mensagem duas vezes.
Janela de atendimento após a última mensagem do cliente; fora dela, a Meta só aceita mensagens de template.
Throughput fixo de um número usado ao mesmo tempo no app do WhatsApp Business e na Cloud API.
Qual rota um agente feito em código deve usar?
Encaminhado significa que o número continua no modo Automations on: a Meta entrega as mensagens à easyCoexistence, as automações continuam podendo rodar e uma cópia assinada de cada mudança da Meta vai para a sua URL de encaminhamento (Forward URL). Uma variante dispensa o encaminhamento: a etapa Call my webhook de uma automação faz um POST da mensagem para o seu endpoint e envia o {"reply"} que você retornar em até 20 segundos, com deduplicação, pausa pelo celular e checagem das 24 horas já feitas para você.
Direto significa que a Meta envia o próprio webhook direto para o seu endpoint, definido com set_webhook_destination, e a easyCoexistence nunca vê as mensagens. As automações ficam desligadas nesse número, então todas as proteções ficam por sua conta, assim como a importação do histórico de 6 meses quando o destino é salvo em até 24 horas após a conexão. Os exemplos abaixo tratam os três pontos de entrada com um núcleo compartilhado.
| 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 |
O que o agente faz com uma mensagem, em Node.js?
agent.mjs contém a lógica que as duas rotas compartilham. Ele registra o horário da última mensagem do cliente, fica em silêncio por 4 horas (o padrão que as automações da easyCoexistence usam) numa conversa quando um evento smb_message_echoes mostra que alguém respondeu pelo app do WhatsApp Business, ignora um id de mensagem que já tratou e só envia dentro da janela de 24 horas. A janela é medida a partir do timestamp da própria mensagem, e não do momento em que ela chegou até você, já que uma entrega repetida pode chegar horas depois.
Os usuários são identificados pelo BSUID (from_user_id, ou to_user_id nos ecos), com o número de telefone como alternativa, e um usuário conhecido apenas pelo BSUID recebe a resposta com recipient em vez de to. A chamada ao modelo usa qualquer API de chat completions compatível com a OpenAI; se preferir, use o SDK do seu provedor.
// 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()}`);
}Como verificar e rotear os eventos em Node.js?
server.mjs expõe os três pontos de entrada. /ec/forward recebe os encaminhamentos de um número gerenciado: verifica o X-EC-Signature sobre os bytes brutos com o segredo de encaminhamento do número, responde 200 antes de qualquer processamento e ignora um id de entrega que já aceitou, porque uma repetição traz o mesmo id com uma assinatura nova. O campo event do corpo é o nome do campo da Meta, e value é a mudança da Meta, sem alteração. /ec/agent responde a uma etapa Call my webhook, assinada com o Signing secret da própria automação, e transforma o histórico em turnos de conversa. /meta/:secret é a rota direta: responde ao handshake GET da Meta com o hub.challenge bruto e só aceita POSTs no caminho com o segredo.
A chave HMAC é o segredo inteiro, incluindo o prefixo whsec_, como texto UTF-8. O express.raw mantém os bytes intactos, e o limite de 5 MB dele deixa espaço para payloads da Meta de até 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);Como fica o mesmo agente em Python?
Um único arquivo Flask com as mesmas três rotas e as mesmas regras. request.get_data() retorna o corpo bruto para o HMAC, hmac.compare_digest faz a comparação em tempo constante e o processamento roda em uma thread em segundo plano depois do 200, para que nem a easyCoexistence nem a Meta fiquem esperando o seu modelo. Rode com flask --app agent run durante o desenvolvimento e atrás do gunicorn ou de outro servidor WSGI em produção.
O set e os dicionários em memória funcionam para um único processo. Com vários workers ou instâncias, mova-os para o Redis ou para o seu banco de dados, usando uma gravação set-if-absent com expiração para os ids de mensagem; caso contrário, dois workers vão responder à mesma mensagem.
# 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 "", 200Como evitar respostas duplicadas?
As duplicatas têm seis causas comuns, e os exemplos acima tratam as cinco primeiras:
- Repetições da Meta. Um webhook direto é repetido por até 7 dias após qualquer resposta diferente de HTTP 200; guarde os ids de mensagem e ignore os já tratados.
- Repetições do encaminhamento. A easyCoexistence repete, com o mesmo id, uma entrega que não recebeu 2xx em 10 segundos; ignore os ids já aceitos e depois deduplique pelo id da mensagem, pois uma mudança que a Meta reenvia é encaminhada de novo com um id novo.
- Confirmações lentas. Responda primeiro e processe depois; um handler que espera o modelo estoura o tempo limite, e o mesmo evento volta.
- Uma pessoa no celular. Um evento
smb_message_echoessignifica que alguém respondeu pelo app; fique em silêncio nessa conversa por algumas horas. - Vários workers. Conjuntos em memória não são compartilhados entre processos; mova os armazenamentos para o Redis ou para o seu banco de dados.
- Duas fontes de resposta. Uma automação de resposta com IA e o seu próprio agente nas mesmas conversas respondem os dois, e os seus envios pela Graph API não são ecos, então não pausam as automações. Escolha uma única fonte de resposta por número.
De onde vêm os segredos e as credenciais?
Do painel ou do conector MCP, e eles devem ficar somente no ambiente do seu servidor. get_api_credentials retorna graph_api_base, waba_id, phone_number_id, send_endpoint e access_token, o token do próprio negócio; a página do número mostra os mesmos valores em Plug in your own system. Se access_token vier null, reconecte o número em um computador pelo Reconnect para emitir um token. Trate o token como uma senha, porque quem o tiver pode enviar mensagens em nome do negócio.
Erros comuns
- Verificar o HMAC sobre um JSON serializado de novo. O json.dumps do Python adiciona espaços depois dos separadores por padrão, então um corpo lido e serializado novamente deixa de bater; verifique os bytes brutos.
- Decodificar o segredo em base64 ou remover o prefixo whsec_. A chave é a string inteira como texto UTF-8, exatamente como foi exibida a você, uma única vez.
- Validar o X-Hub-Signature-256 na rota direta com o app secret do seu próprio app da Meta. A Meta assina com o app secret da easyCoexistence, que não é compartilhado, então eventos legítimos falham; autentique pelo segredo do caminho.
- Calcular a janela pelo horário de chegada. Um encaminhamento repetido horas depois ainda traz o timestamp original da Meta; compare com ele, ou o agente responde depois das 24 horas e a Meta recusa o envio.
Cada número é monitorado 24/7, com alertas quando uma conexão cai. De R$ 29,90 a R$ 3,90 por número por mês, com o valor caindo conforme você adiciona números, e 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
O agente de IA consegue entender áudios e fotos?
Sim, com o seu próprio código. O payload da Meta traz o id da mídia: baixe-a com GET /<media-id> e o token do número, acesse a URL retornada com o mesmo cabeçalho Authorization e então transcreva ou descreva o conteúdo com o seu modelo. As automações só veem marcadores como [voice message].
Quais modelos de IA os exemplos podem usar?
Qualquer modelo atrás de um endpoint de chat completions compatível com a OpenAI, incluindo os da OpenAI e os acessados pelo OpenRouter, ou substitua askModel e ask_model pelo SDK do seu provedor. A easyCoexistence nunca cobra pela IA: o seu provedor cobra você diretamente.
O agente pode iniciar uma conversa com o cliente?
Somente com um template aprovado, enviado com type template para o mesmo endpoint de envio. Em um número com Coexistência, os templates saem apenas pela API, nunca pelo app do celular, e a Meta cobra cada mensagem na conta do WhatsApp Business (WABA) do próprio negócio.
Um único agente atende vários números?
Sim. Roteie por value.metadata.phone_number_id ou connection.phone_number_id e mantenha um endpoint de envio, um token e um segredo de encaminhamento por número, já que cada número tem os seus.
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