Agente de IA: o laço completo
Um agente de IA que atende no WhatsApp faz sempre o mesmo laço: recebe um evento, confere que veio da Luna, responde rápido, pensa e envia a resposta. Este guia traz o laço inteiro num código que roda colando, em Python (só a biblioteca padrão) e em Node (só o fetch), e explica cada passo. A inteligência é sua: o código chama uma função answer, que você troca pelo seu modelo.
O contrato de cada rota, campo a campo, está na referência da API. Os termos em letra pequena (janela de 24 horas, template, idempotência) estão no glossário.
O laço, em oito passos#
- Receber o
POSTda Luna no seu endereço e verificar a assinatura dos bytes que chegaram. Assinatura inválida:401e pare. Veja Receber eventos. - Responder
200na hora. A Luna espera 10 segundos, e uma chamada a um modelo de IA passa disso com facilidade. - Descartar o repetido: a entrega é pelo menos uma vez, e o mesmo
event_idpode chegar duas vezes. - Pôr o evento numa fila e tratá-lo fora da requisição, um a um, para manter a ordem da conversa.
- Marcar como lida (
POST /v1/messages/{id}/read) e mostrar “digitando” (POST /v1/messages/{id}/typing). - Pensar: chamar o seu modelo com o texto recebido.
- Responder com
POST /v1/messages, com umaIdempotency-Keyque nasce da mensagem recebida:resp-<id>. - Se a janela de 24 horas estiver fechada (
409 window_closed), cair para um template aprovado.
Antes de rodar#
- Um número conectado e um endpoint de webhook cadastrado, como em Primeiros passos. O
secretque o cadastro devolve é oLUNA_WEBHOOK_SECRET. - Uma chave de API com o perfil
agent(profile: "agent"emPOST /v1/api-keys, ou o perfil “Agente de atendimento” no console). Ele concedemessages:write,messages:read,numbers:readetemplates:read: o que o laço usa, e nada de configuração. - Um endereço HTTPS público para o servidor. Em desenvolvimento, um túnel HTTPS para a sua máquina serve (veja Receber eventos).
| Variável | O que é |
|---|---|
LUNA_API_KEY | A chave de API (hlsn_...). |
LUNA_WEBHOOK_SECRET | O segredo do endpoint (whsec_...). |
LUNA_NUMBER_ID | O número de origem: o metaPhoneNumberId ou o id de GET /v1/numbers. |
LUNA_TEMPLATE | Opcional. O nome de um template aprovado, para o passo 8. |
LUNA_API_URL | Opcional. Só para apontar para outra base, como uma pilha local. |
PORT | Opcional. A porta do servidor (3000 por padrão). |
O código#
Salve como agente.py ou agente.mjs. É um arquivo só, sem pip install nem npm install. answer é a função que você troca pelo seu modelo; aqui ela devolve um texto fixo.
import crypto from 'node:crypto';
import http from 'node:http';
const API = process.env.LUNA_API_URL ?? 'https://api.lunahia.com.br'; // LUNA_API_URL é opcional: serve para apontar para uma pilha local
const KEY = process.env.LUNA_API_KEY;
const SECRET = process.env.LUNA_WEBHOOK_SECRET;
const NUMBER = process.env.LUNA_NUMBER_ID;
const TEMPLATE = process.env.LUNA_TEMPLATE; // opcional: o nome de um template aprovado, para quando a janela estiver fechada
const TOLERANCE_SECONDS = 300;
// rawBody: os bytes exatos que chegaram (um Buffer), nunca o JSON reserializado.
export function verifyLunaSignature(rawBody, header, secret, nowMs = Date.now()) {
if (typeof header !== 'string' || !secret) return false;
// 1. O cabeçalho traz o instante t e a assinatura v1.
const m = /^t=(\d{1,15}),/.exec(header);
if (!m) return false;
const t = Number(m[1]);
// 2. Recuse o que é velho demais (uma entrega gravada e repetida depois).
if (Math.abs(Math.floor(nowMs / 1000) - t) > TOLERANCE_SECONDS) return false;
// 3. Refaça a conta com o seu segredo e compare com o v1.
const expected = crypto
.createHmac('sha256', secret)
.update(`${t}.`)
.update(rawBody)
.digest();
// Na troca do segredo o cabeçalho traz dois valores v1: confira todos.
let ok = false;
for (const [, hex] of header.matchAll(/v1=([0-9a-fA-F]{64})/g)) {
if (crypto.timingSafeEqual(Buffer.from(hex, 'hex'), expected)) ok = true;
}
return ok;
}
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
// Chama a API. Devolve o status e o corpo JSON.
async function luna(method, path, body, idempotencyKey, tries = 3) {
const headers = { Authorization: 'Bearer ' + KEY };
if (body !== undefined) headers['Content-Type'] = 'application/json';
if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;
for (let attempt = 1; ; attempt++) {
const res = await fetch(API + path, {
method,
headers,
body: body === undefined ? undefined : JSON.stringify(body),
signal: AbortSignal.timeout(15000),
});
if ((res.status === 429 || res.status === 503) && attempt < tries) {
// Em 429/503 espere o que a API manda e tente de novo, com a MESMA Idempotency-Key
await sleep(Number(res.headers.get('retry-after') ?? 2 ** attempt) * 1000);
continue;
}
const text = await res.text();
return { status: res.status, body: text ? JSON.parse(text) : null };
}
}
// Troque esta função pelo seu agente (a chamada ao LLM fica aqui).
function answer(text) {
return text ? 'Recebi: ' + text + '. Já te ajudo.' : 'Recebi a sua mensagem.';
}
async function handle(event) {
if (event.event_type !== 'message.received') return;
const msg = event.message;
const destination = msg.wa_id ? { to: msg.wa_id } : { recipient: msg.user_id }; // wa_id é null quando o contato escreveu sem telefone: então responda ao user_id
await luna('POST', '/v1/messages/' + msg.id + '/read'); // marca como lida (o visto azul)
await luna('POST', '/v1/messages/' + msg.id + '/typing'); // mostra "digitando..." (também marca como lida, e some quando você responde)
const reply = answer(msg.text); // aqui só texto é tratado
let sent = await luna(
'POST',
'/v1/messages',
{ from: NUMBER, ...destination, text: { body: reply } },
'resp-' + msg.id, // a chave nasce da mensagem recebida: o mesmo evento duas vezes nunca gera duas respostas
);
console.log('reply', sent.status, sent.body);
if (sent.status === 409 && sent.body?.error === 'window_closed' && TEMPLATE) {
// a janela de 24 horas está fechada: só sai template
sent = await luna(
'POST',
'/v1/messages',
{
from: NUMBER,
...destination,
type: 'template',
template: { name: TEMPLATE, language: { code: 'pt_BR' } },
},
'resp-' + msg.id + '-template',
);
console.log('template', sent.status, sent.body);
}
}
const seen = new Set(); // em produção: um banco ou Redis, com prazo de validade
let queue = Promise.resolve(); // UM trabalhador mantém a ordem dos eventos. Para muitas conversas ao mesmo tempo, um trabalhador por wa_id.
http
.createServer((req, res) => {
const chunks = [];
req.on('data', (chunk) => chunks.push(chunk));
req.on('end', () => {
const raw = Buffer.concat(chunks);
if (!verifyLunaSignature(raw, req.headers['x-luna-signature'], SECRET)) {
res.writeHead(401).end();
return;
}
res.writeHead(200).end(); // responda 200 primeiro, trabalhe depois
const event = JSON.parse(raw.toString('utf8'));
if (seen.has(event.event_id)) return;
seen.add(event.event_id);
// o trabalho vai para uma fila: a requisição só verifica e responde
queue = queue.then(() => handle(event)).catch((err) => console.error('handler failed', err)); // a falha de um evento não pode parar o trabalhador
});
})
.listen(Number(process.env.PORT ?? 3000));import hashlib
import hmac
import json
import os
import queue
import re
import threading
import time
import urllib.error
import urllib.request
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
API = os.environ.get("LUNA_API_URL", "https://api.lunahia.com.br") # LUNA_API_URL é opcional: serve para apontar para uma pilha local
KEY = os.environ["LUNA_API_KEY"]
SECRET = os.environ["LUNA_WEBHOOK_SECRET"]
NUMBER = os.environ["LUNA_NUMBER_ID"]
TEMPLATE = os.environ.get("LUNA_TEMPLATE") # opcional: o nome de um template aprovado, para quando a janela estiver fechada
TOLERANCE_SECONDS = 300
def verify_luna_signature(raw_body, header, secret, now=None):
# raw_body: os bytes exatos que chegaram, nunca o JSON reserializado.
if not header or not secret:
return False
# 1. O cabeçalho traz o instante t e a assinatura v1.
m = re.match(r"^t=(\d{1,15}),", header)
if not m:
return False
t = int(m.group(1))
# 2. Recuse o que é velho demais (uma entrega gravada e repetida depois).
now = time.time() if now is None else now
if abs(int(now) - t) > TOLERANCE_SECONDS:
return False
# 3. Refaça a conta com o seu segredo e compare com o v1.
expected = hmac.new(
secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256
).hexdigest()
# Na troca do segredo o cabeçalho traz dois valores v1: confira todos.
ok = False
for sig in re.findall(r"v1=([0-9a-fA-F]{64})", header):
if hmac.compare_digest(sig.lower(), expected):
ok = True
return ok
def luna(method, path, body=None, idempotency_key=None, tries=3):
# Chama a API. Devolve o status e o corpo JSON.
headers = {"Authorization": f"Bearer {KEY}"}
data = None
if body is not None:
data = json.dumps(body).encode()
headers["Content-Type"] = "application/json"
if idempotency_key:
headers["Idempotency-Key"] = idempotency_key
for attempt in range(1, tries + 1):
req = urllib.request.Request(API + path, data=data, headers=headers, method=method)
try:
with urllib.request.urlopen(req, timeout=15) as res:
raw = res.read()
return res.status, (json.loads(raw) if raw else None)
except urllib.error.HTTPError as err:
raw = err.read()
payload = json.loads(raw) if raw else None
if err.code in (429, 503) and attempt < tries:
# Em 429/503 espere o que a API manda e tente de novo, com a MESMA Idempotency-Key
time.sleep(float(err.headers.get("Retry-After") or 2**attempt))
continue
return err.code, payload
def answer(text):
# Troque esta função pelo seu agente (a chamada ao LLM fica aqui).
return f"Recebi: {text}. Já te ajudo." if text else "Recebi a sua mensagem."
def handle(event):
if event["event_type"] != "message.received":
return
msg = event["message"]
destination = {"to": msg["wa_id"]} if msg["wa_id"] else {"recipient": msg["user_id"]} # wa_id é null quando o contato escreveu sem telefone: então responda ao user_id
luna("POST", f"/v1/messages/{msg['id']}/read") # marca como lida (o visto azul)
luna("POST", f"/v1/messages/{msg['id']}/typing") # mostra "digitando..." (também marca como lida, e some quando você responde)
reply = answer(msg.get("text")) # aqui só texto é tratado
status, body = luna(
"POST",
"/v1/messages",
{"from": NUMBER, **destination, "text": {"body": reply}},
idempotency_key=f"resp-{msg['id']}", # a chave nasce da mensagem recebida: o mesmo evento duas vezes nunca gera duas respostas
)
print("reply", status, body)
if status == 409 and body and body.get("error") == "window_closed" and TEMPLATE:
# a janela de 24 horas está fechada: só sai template
status, body = luna(
"POST",
"/v1/messages",
{
"from": NUMBER,
**destination,
"type": "template",
"template": {"name": TEMPLATE, "language": {"code": "pt_BR"}},
},
idempotency_key=f"resp-{msg['id']}-template",
)
print("template", status, body)
events = queue.Queue() # o trabalho vai para uma fila: a requisição só verifica e responde
seen = set() # em produção: um banco ou Redis, com prazo de validade
seen_lock = threading.Lock()
def worker():
# UM trabalhador mantém a ordem dos eventos. Para muitas conversas ao mesmo tempo, um trabalhador por wa_id.
while True:
event = events.get()
try:
handle(event)
except Exception as err: # a falha de um evento não pode parar o trabalhador
print("handler failed", repr(err))
class Handler(BaseHTTPRequestHandler):
def do_POST(self):
raw = self.rfile.read(int(self.headers.get("Content-Length", 0)))
if not verify_luna_signature(raw, self.headers.get("X-Luna-Signature"), SECRET):
self.send_response(401)
self.send_header("Content-Length", "0")
self.end_headers()
return
self.send_response(200) # responda 200 primeiro, trabalhe depois
self.send_header("Content-Length", "0")
self.end_headers()
event = json.loads(raw)
with seen_lock:
repeated = event["event_id"] in seen
seen.add(event["event_id"])
if not repeated:
events.put(event)
def log_message(self, *args):
pass
threading.Thread(target=worker, daemon=True).start()
ThreadingHTTPServer(("", int(os.environ.get("PORT", "3000"))), Handler).serve_forever()export LUNA_API_KEY="hlsn_..."
export LUNA_WEBHOOK_SECRET="whsec_..."
export LUNA_NUMBER_ID="123456789012345"
python3 agente.py # ou: node agente.mjsEscreva do seu celular para o número conectado: o agente imprime reply 202 e a resposta chega no seu celular. Se nada chegar, siga “Se nada chegou” em Primeiros passos.
Por que cada passo é assim#
Responda `200` primeiro
A Luna conta como entregue só uma resposta 2xx em até 10 segundos. Se o servidor chamasse o modelo antes de responder, uma resposta lenta viraria falha e a Luna reenviaria o evento, e o agente responderia duas vezes. Por isso a requisição só verifica, responde e põe o evento na fila; quem pensa é o trabalhador. As garantias de entrega estão em Receber eventos.
Descarte o `event_id` repetido
O event_id é estável: a mesma entrega, repetida, traz o mesmo valor. O conjunto em memória do exemplo some quando o processo reinicia; em produção guarde os já tratados num banco ou num Redis, com prazo de validade. Atenção: o reenvio que você pede com POST /v1/messages/{id}/replay também traz o mesmo event_id do original, então ele cai nesse descarte. Para recuperar uma mensagem que o agente perdeu, tire o event_id dela da lista de vistos antes de pedir o reenvio.
Um trabalhador mantém a ordem
A Luna entrega os eventos de uma conversa na ordem. Se vários trabalhadores pegassem eventos da mesma conversa, a resposta à segunda mensagem poderia sair antes da resposta à primeira. O exemplo usa um trabalhador só, o que serve até algumas conversas ao mesmo tempo; para muitas, mantenha um trabalhador (ou uma fila) por wa_id, e várias conversas andam em paralelo sem se embaralhar.
Lida e “digitando”
As duas rotas usam o identificador da mensagem recebida na Luna (o message.id do evento), e não o wamid. Chamar /typing também marca a mensagem como lida; o exemplo chama as duas para o passo ficar explícito. O indicador some sozinho quando você responde. Há um atalho: typingMs em POST /v1/messages liga o indicador e espera esse tempo antes de enviar, sem uma chamada à parte. Os dois estão em Enviar mensagens.
A chave de idempotência do agente#
Para um agente, a chave não é um UUID novo a cada tentativa: é uma chave determinística, que nasce da mensagem que ele está respondendo, como resp-<id>. O motivo: a entrega do webhook é pelo menos uma vez, e o seu tratamento pode rodar duas vezes para o mesmo evento (um reinício no meio, um reenvio, uma retentativa de 429). Com a mesma chave, as duas tentativas viram uma resposta: a segunda devolve a mensagem original, com o mesmo id, e nada é enviado de novo. Um UUID novo a cada tentativa não protege de nada.
- Uma resposta por mensagem recebida:
resp-<id>. Uma segunda resposta à mesma mensagem (o fallback de template, por exemplo) leva outro sufixo:resp-<id>-template. A mesma chave com corpo diferente responde409 idempotency_key_reused. - A chave vale de 1 a 255 caracteres visíveis, sem espaço. O formato completo está em Enviar mensagens.
Quando a janela fechou#
Logo depois de o contato escrever, a janela de 24 horas está aberta, e a resposta sai. O 409 window_closed aparece quando o agente responde um evento velho (uma fila atrasada, um reenvio de ontem) ou quando ele é quem puxa a conversa. Ele traz fechadaEm (quando a janela fechou, ou null se nunca houve) e acaoRecomendada. Mensagem livre não volta a ser aceita com o tempo: só quando o contato escrever de novo. O que sai é um template aprovado, que o código acima envia se LUNA_TEMPLATE estiver definido. Como criar e esperar a aprovação, e como testar antes de ter um, está em Templates.
Mídia recebida#
Quando o cliente manda imagem, áudio, documento ou vídeo, o evento traz message.media (com o mime_type e a url) e message.type. A url é um link da Luna que baixa o arquivo sem chave de API: faça um GET nela e siga o redirecionamento. Se a Luna ainda estiver baixando o arquivo da Meta, a resposta é 409 media_not_ready com Retry-After: espere e tente de novo. Trate o link como dado sensível e não o registre em log. GET /v1/messages/{id}/media (escopo messages:read), com chave, continua valendo. Detalhes em Enviar mensagens.
import { writeFile } from 'node:fs/promises';
const EXTENSIONS = { 'image/jpeg': '.jpg', 'image/png': '.png', 'audio/ogg': '.ogg', 'application/pdf': '.pdf' };
// Baixa o arquivo pelo media.url de um aviso message.received.
async function downloadFromLink(link, name, attempts = 6) {
for (let i = 0; i < attempts; i++) {
const res = await fetch(link); // sem cabeçalho Authorization: o token dentro do link é a credencial. Nunca registre o link em log.
if (res.status === 409) {
// 409 media_not_ready: a Luna ainda está baixando da Meta, espere o que o Retry-After diz e tente de novo
const seconds = Math.min(Number(res.headers.get('retry-after') ?? 5), 30);
await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
continue;
}
if (res.status === 404) return null; // 404: o link venceu (30 dias) ou nunca existiu. GET /v1/messages/{id}/media continua valendo, com chave.
if (!res.ok) throw new Error('media link answered ' + res.status);
const type = (res.headers.get('content-type') ?? '').split(';')[0];
const file = name + (EXTENSIONS[type] ?? '');
await writeFile(file, Buffer.from(await res.arrayBuffer()));
return file;
}
return null;
}
console.log(await downloadFromLink(process.env.LUNA_MEDIA_URL, 'arquivo'));import os
import time
import urllib.error
import urllib.request
EXTENSIONS = {"image/jpeg": ".jpg", "image/png": ".png", "audio/ogg": ".ogg", "application/pdf": ".pdf"}
def download_from_link(link, name, attempts=6):
# Baixa o arquivo pelo media.url de um aviso message.received.
for _ in range(attempts):
try:
# sem cabeçalho Authorization: o token dentro do link é a credencial. Nunca registre o link em log.
with urllib.request.urlopen(link, timeout=60) as file:
data = file.read()
extension = EXTENSIONS.get(file.headers.get_content_type(), "")
except urllib.error.HTTPError as err:
if err.code == 409:
# 409 media_not_ready: a Luna ainda está baixando da Meta, espere o que o Retry-After diz e tente de novo
time.sleep(min(int(err.headers.get("Retry-After", "5")), 30))
continue
if err.code == 404:
return None # 404: o link venceu (30 dias) ou nunca existiu. GET /v1/messages/{id}/media continua valendo, com chave.
raise
with open(name + extension, "wb") as out:
out.write(data)
return name + extension
return None
print(download_from_link(os.environ["LUNA_MEDIA_URL"], "arquivo"))Antes de ir para produção#
- Depois do
200, a falha é sua. Se o seu tratamento falhar, a Luna não retenta: ela já recebeu o200. Em produção, grave o evento num banco antes de responder (umINSERTrápido) e trate a partir dele, para um reinício não perder a mensagem. - O ritmo. Respostas em rajada não precisam de espera do seu lado: a Luna as enfileira. Veja Limites e ritmo.
- Teste sem número de verdade. A chave de teste simula o envio e os estados, sem tocar a Meta: Modo de teste.
- Os erros que o laço pode ver e o que fazer em cada um: Erros.
- n8n em vez de código? O caminho com os nós padrão está em SDK e n8n.