# Agente de IA: o laço completo

Fonte: https://lunahia.com.br/docs/agente-de-ia

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](https://lunahia.com.br/docs/referencia). Os termos em letra pequena (janela de 24 horas, template, idempotência) estão no [glossário](https://lunahia.com.br/docs/glossario).

## O laço, em oito passos

1. **Receber** o `POST` da Luna no seu endereço e **verificar a assinatura** dos bytes que chegaram. Assinatura inválida: `401` e pare. Veja [Receber eventos](https://lunahia.com.br/docs/receber-eventos#assinatura).
2. **Responder `200` na hora.** A Luna espera 10 segundos, e uma chamada a um modelo de IA passa disso com facilidade.
3. **Descartar o repetido**: a entrega é pelo menos uma vez, e o mesmo `event_id` pode chegar duas vezes.
4. **Pôr o evento numa fila** e tratá-lo fora da requisição, um a um, para manter a ordem da conversa.
5. **Marcar como lida** (`POST /v1/messages/{id}/read`) e **mostrar “digitando”** (`POST /v1/messages/{id}/typing`).
6. **Pensar**: chamar o seu modelo com o texto recebido.
7. **Responder** com `POST /v1/messages`, com uma `Idempotency-Key` que nasce da mensagem recebida: `resp-<id>`.
8. **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](https://lunahia.com.br/docs/primeiros-passos). O `secret` que o cadastro devolve é o `LUNA_WEBHOOK_SECRET`.
- Uma chave de API com o perfil `agent` (`profile: "agent"` em `POST /v1/api-keys`, ou o perfil “Agente de atendimento” no console). Ele concede `messages:write`, `messages:read`, `numbers:read` e `templates: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](https://lunahia.com.br/docs/receber-eventos#gerir)).

| 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.

```js
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));
```

```python
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()
```

```bash
export LUNA_API_KEY="hlsn_..."
export LUNA_WEBHOOK_SECRET="whsec_..."
export LUNA_NUMBER_ID="123456789012345"

python3 agente.py     # ou: node agente.mjs
```

Escreva 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](https://lunahia.com.br/docs/primeiros-passos#receber).

## 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](https://lunahia.com.br/docs/receber-eventos#garantias).

### 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](https://lunahia.com.br/docs/enviar-mensagens#lida-e-digitando).

## 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** responde `409 idempotency_key_reused`.
- A chave vale de 1 a 255 caracteres visíveis, sem espaço. O formato completo está em [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens#idempotencia).

## Quando a janela fechou

Logo depois de o contato escrever, a [janela de 24 horas](https://lunahia.com.br/docs/glossario#janela) 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](https://lunahia.com.br/docs/glossario#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](https://lunahia.com.br/docs/templates#testar).

> Sem telefone? O contato que escreve só com o [BSUID](https://lunahia.com.br/docs/glossario#bsuid) chega com `wa_id` nulo. O código responde com `recipient` igual ao `user_id` do evento, e não com `to`. Veja [Usuários sem telefone](https://lunahia.com.br/docs/usuarios-sem-telefone).

## 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](https://lunahia.com.br/docs/enviar-mensagens#midia).

```js
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'));
```

```python
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 o `200`. Em produção, grave o evento num banco antes de responder (um `INSERT` rá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](https://lunahia.com.br/docs/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](https://lunahia.com.br/docs/modo-de-teste).
- **Os erros** que o laço pode ver e o que fazer em cada um: [Erros](https://lunahia.com.br/docs/erros).
- **n8n em vez de código?** O caminho com os nós padrão está em [SDK e n8n](https://lunahia.com.br/docs/sdk-e-n8n).
