# Luna: documentação completa A Luna é uma API de mensageria para WhatsApp, construída sobre a WhatsApp Cloud API oficial da Meta. Este arquivo reúne os guias de integração e a referência da API, gerados do mesmo conteúdo do site (https://lunahia.com.br/docs). --- # Documentação da Luna Fonte: https://lunahia.com.br/docs A Luna é uma API de mensageria para WhatsApp, construída sobre a WhatsApp Cloud API oficial da Meta. A Helsen opera como Tech Provider aprovado, e nenhuma biblioteca não oficial participa do caminho. A Luna entrega a infraestrutura de mensageria, e o que acontece dentro da conversa é do seu produto. ## O caminho, do zero à primeira mensagem 1. **Crie a conta** no [console](https://app.lunahia.com.br/cadastro). Você confirma o e-mail e entra. A conta nasce no teste grátis: 14 dias, com capacidade para 1 número. Para conectar mais números (um por cliente, no caminho de SaaS), contrate um plano pelo e-mail contato@lunahia.com.br. Os planos estão em [Preços](https://lunahia.com.br/precos). 2. **Conecte um número.** O dono do número autoriza na janela da Meta. [Conectar um número](https://lunahia.com.br/docs/conectar-numero) 3. **Crie uma chave de API** no console, com só os escopos de que você precisa. [Primeiros passos](https://lunahia.com.br/docs/primeiros-passos#chave) 4. **Cadastre um webhook** e verifique a assinatura. [Receber eventos](https://lunahia.com.br/docs/receber-eventos) 5. **Envie uma mensagem.** [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens) Se você prefere seguir de uma vez, [Primeiros passos](https://lunahia.com.br/docs/primeiros-passos) percorre os cinco passos com exemplos que rodam. ## Os guias - [Primeiros passos](https://lunahia.com.br/docs/primeiros-passos): de uma conta nova a uma mensagem enviada e a um evento recebido. - [Conta e chaves](https://lunahia.com.br/docs/conta-e-chaves): cadastrar, entrar, criar e revogar chaves de API, os escopos, e ler a conta, o plano e o estado da plataforma, tudo com curl. - [Conectar um número](https://lunahia.com.br/docs/conectar-numero): número novo, número que continua no aplicativo WhatsApp Business do celular (coexistência) e número que vem de outro provedor. - [SaaS com N clientes](https://lunahia.com.br/docs/saas-com-n-clientes): o caminho completo de um produto que contrata um plano de números e dá WhatsApp aos clientes dele, com um externalId por cliente, eventos de todos num endpoint, chave e webhook por cliente. Comece por aqui se você vende para muitos negócios. - [Plano e números](https://lunahia.com.br/docs/plano-e-numeros): o teste grátis, a capacidade de números, o erro 409 de capacidade, como desconectar e reconectar um número e o que acontece quando o teste termina. - [Receber eventos](https://lunahia.com.br/docs/receber-eventos): o endpoint, cada tipo de evento, as garantias de entrega, retentativas, reenvio e a verificação da assinatura. - [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens): cada tipo de mensagem, a janela de 24 horas, idempotência e o acompanhamento da entrega. - [Agente de IA](https://lunahia.com.br/docs/agente-de-ia): o laço completo de um agente que atende no WhatsApp, em código que roda colando (Python e Node): verificar, deduplicar, marcar como lida, mostrar digitando, responder com idempotência e cair para template. - [Usuários sem telefone (BSUID)](https://lunahia.com.br/docs/usuarios-sem-telefone): o que muda quando o usuário escreve sem que o telefone apareça, o wa_id que pode ser nulo, como responder com recipient e a troca de telefone ou de BSUID. - [O que o número faz na Meta](https://lunahia.com.br/docs/numero-na-meta): o perfil do negócio, os usuários bloqueados, o QR code com link curto e o aviso de que um contato pediu para parar de receber marketing. - [Modo de teste](https://lunahia.com.br/docs/modo-de-teste): uma chave de teste que envia sem ir à Meta e entrega ao seu webhook os estados simulados, assinados e com test true. - [SDK e n8n](https://lunahia.com.br/docs/sdk-e-n8n): o fluxo do n8n que funciona hoje com os nós padrão (Webhook, Code e HTTP Request), com um fluxo para importar, e o que há do SDK e do nó próprio. - [Templates](https://lunahia.com.br/docs/templates): criar, acompanhar o estado, cabeçalho de mídia e o que muda entre aprovado e liberado. - [Erros](https://lunahia.com.br/docs/erros): o formato do erro, os códigos principais, o que fazer em cada um e os cabeçalhos de limite. - [Limites e ritmo](https://lunahia.com.br/docs/limites-e-ritmo): o limite de requisições, a rajada de cada conversa, o ritmo por número, a fila de envio e o limite diário de conversas, com os números e o que acontece quando você passa. - [Saúde da conta](https://lunahia.com.br/docs/saude-da-conta): os avisos da Meta sobre restrição, violação, desativação, desconexão, limite e qualidade, o que cada evento significa e o que fazer em cada caso. - [Custos da Meta](https://lunahia.com.br/docs/custos-da-meta): quem cobra o quê, as regras de cobrança da Meta em vigor desde 1º de outubro de 2026 e onde conferir o que foi cobrado. - [Glossário](https://lunahia.com.br/docs/glossario): janela de 24 horas, template, idempotência, BSUID, webhook, assinatura, wamid, externalId, event_id e corpo bruto, em linguagem simples. ## Vindo de outra plataforma - [Vindo da Z-API ou da Evolution API](https://lunahia.com.br/docs/migrar-de-api-nao-oficial): o de-para de autenticação, envio, eventos e estados, e o que não existe na API oficial. A diferença de modelo está em [Z-API e Evolution: o modelo](https://lunahia.com.br/migrar-da-evolution-api). - [Vindo da Twilio](https://lunahia.com.br/docs/migrar-da-twilio): envio, template, estados, assinatura do webhook e códigos de erro. - [Vindo de outro parceiro oficial](https://lunahia.com.br/docs/migrar-de-outro-parceiro): para quem opera clientes pela 360dialog ou pela Gupshup, inclusive como mover um número com o PIN. ## A referência da API Os guias explicam o caminho. O contrato de cada rota, campo a campo, está na [referência da API](https://lunahia.com.br/docs/referencia), gerada da mesma definição que valida as requisições. A especificação OpenAPI 3.1 está em [openapi.json](https://api.lunahia.com.br/openapi.json). Se um guia divergir da referência, vale a referência. Toda chamada leva uma chave de API no cabeçalho `Authorization`, no formato `Bearer hlsn_...`. A base é `https://api.lunahia.com.br`, e todas as rotas ficam sob `/v1`. ## O que a Luna cobra, e o que a Meta cobra A Luna cobra pela capacidade de números ativos do plano, e por nada além disso. O uso da plataforma WhatsApp é cobrado pela Meta, diretamente do negócio final, no método de pagamento que ele cadastra na conta dele. A Helsen não intermedeia esse pagamento. Os planos estão em [Preços](https://lunahia.com.br/precos). As regras da Meta estão em [Custos da Meta](https://lunahia.com.br/docs/custos-da-meta). --- # Primeiros passos Fonte: https://lunahia.com.br/docs/primeiros-passos Este guia leva você de uma conta nova a uma mensagem enviada e a um evento recebido. Os passos do console estão descritos em palavras, e os da API trazem exemplos em curl, Node e Python. ## Antes de começar - Um e-mail e uma senha de pelo menos 12 caracteres para a conta. - Um número de WhatsApp com código de país do Brasil (+55). A Luna atende só esses números. - Uma conta de WhatsApp Business do dono do número, e um método de pagamento dele na Meta. O número e a conta são do negócio final, e a Meta cobra dele o uso da plataforma WhatsApp. - Um endereço HTTPS público para receber [webhooks](https://lunahia.com.br/docs/glossario#webhook). Em desenvolvimento, um túnel HTTPS para a sua máquina serve. - Node 20 ou mais novo, ou Python 3 com `requests`, para rodar os exemplos. O curl também serve, e é tudo de que você precisa para os passos 1 a 3 e 5. (O guia [Agente de IA](https://lunahia.com.br/docs/agente-de-ia) usa só a biblioteca padrão do Python, sem `requests`.) ## As variáveis dos exemplos Os exemplos não trazem valores de mentira para você trocar: eles leem variáveis de ambiente. Defina cada uma quando o passo que a produz terminar (o terminal em que você rodar os exemplos precisa tê-las): | Variável | De onde vem | | --- | --- | | `LUNA_API_KEY` | A chave que você cria no passo 3. Começa com `hlsn_` e aparece uma vez. | | `LUNA_NUMBER_ID` | O número de origem: o `metaPhoneNumberId` (ou o `id`) que `GET /v1/numbers` devolve, no fim do passo 3. | | `LUNA_TO` | O seu celular, só dígitos, com 55 e DDD, sem o `+` (por exemplo `5511999990000`). É para quem você vai responder no passo 5. | | `LUNA_WEBHOOK_SECRET` | O `secret` que o cadastro do endpoint devolve no passo 4. Começa com `whsec_`. | | `LUNA_MESSAGE_ID` | O `id` que o `202` do passo 5 devolve, para consultar a mensagem. | ```bash export LUNA_API_KEY="hlsn_..." export LUNA_NUMBER_ID="123456789012345" export LUNA_TO="5511999990000" ``` ## 1. Crie a conta 1. Abra o [cadastro no console](https://app.lunahia.com.br/cadastro). 2. Preencha o nome da empresa, o e-mail e a senha (duas vezes), e toque em **Criar conta**. 3. Abra o e-mail que chega e clique no link de confirmação. Ele vale por sete dias e só funciona uma vez. 4. [Entre no console](https://app.lunahia.com.br/login) com o mesmo e-mail e a mesma senha. A sessão dura oito horas. > Confirmar o e-mail é o que libera a conexão de número. Antes disso a conta já pode criar chaves e integrar contra a API, mas não consegue abrir a conexão. ## 2. Conecte um número 1. No menu **Números**, abra **Conectar número** e toque em **Conectar WhatsApp**. 2. A janela da Meta abre. O dono do número escolhe a conta de WhatsApp e o número, e autoriza o acesso. Não feche a aba até a janela terminar. 3. Quando a Luna terminar o registro, o número aparece em **Números**. Pela API, ele fica com `state` igual a `REGISTERED`. O número já está no aplicativo WhatsApp Business do celular, ou vem de outro provedor? Os dois casos têm passos próprios em [Conectar um número](https://lunahia.com.br/docs/conectar-numero). ## 3. Crie uma chave de API 1. No menu **Integração**, abra **Chaves de API** e toque em **Criar chave**. 2. Confirme a sua senha. O console pede de novo, mesmo com a sessão aberta, e não volta a pedir pelas próximas duas horas. 3. Dê um rótulo e marque só os escopos deste guia: `numbers:read`, `webhooks:write`, `messages:write` e `messages:read`. Se você vende para muitos negócios e vai seguir para [SaaS com N clientes](https://lunahia.com.br/docs/saas-com-n-clientes), marque também `onboarding:write` (o link de conexão por cliente) e `webhooks:read`; para criar template, `templates:write`. Escopo que falta responde `403` na primeira chamada. 4. Copie o segredo, que começa com `hlsn_`. **Ele aparece uma única vez.** Não há rota que o devolva depois: se você o perder, revogue a chave e crie outra. Guarde a chave numa variável de ambiente, e nunca no código: ```bash export LUNA_API_KEY="hlsn_YOUR_KEY_HERE" ``` Agora leia os seus números. A resposta traz o `metaPhoneNumberId`, que é o valor que o envio pede em `from`: ```bash curl -X GET "https://api.lunahia.com.br/v1/numbers" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/numbers', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/numbers", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` Resposta (resumida) ```json { "data": [ { "id": "ed404df1-b420-4ed6-8743-ba1609892e0a", "metaPhoneNumberId": "123456789012345", "displayNumber": "+55 11 99999-0000", "state": "REGISTERED", "orientacao": "Número conectado e operando. Mensagens já entram e saem por ele." } ] } ``` O campo `id` é o identificador do número na Luna. O `metaPhoneNumberId` é o da Meta. Todas as rotas que recebem um número aceitam os dois, então use o que o seu sistema já guarda. ```bash export LUNA_NUMBER_ID="123456789012345" ``` ## 4. Cadastre o webhook Primeiro suba um servidor que recebe o evento. Os dois arquivos abaixo verificam a assinatura de cada entrega e imprimem o que chega. Salve o primeiro como `verify.mjs` (ou `verify.py`) e o segundo como `server.mjs` (ou `server.py`), e rode com `LUNA_WEBHOOK_SECRET` definida depois do cadastro. **Em palavras simples.** Você e a Luna compartilham um segredo: o `secret` que a resposta do cadastro devolve, e que começa com `whsec_`. Antes de mandar cada evento, a Luna mistura o segredo com o conteúdo do evento e escreve o resultado no cabeçalho `X-Luna-Signature`, como um carimbo. Quem não sabe o segredo não consegue fazer um carimbo igual. Ao receber, você refaz a mesma mistura e vê se o carimbo bate: se bater, o evento veio da Luna e ninguém o mudou no caminho. **Por que importa.** O endereço do seu webhook é público. Sem conferir o carimbo, qualquer pessoa pode mandar um evento falso (um “pedido pago”, por exemplo) e o seu sistema agiria como se fosse verdadeiro. 1. Do cabeçalho, pegue o número depois de `t=` (o instante em que a Luna assinou) e os valores depois de `v1=` (os carimbos). 2. Junte o `t`, um ponto e o **corpo exatamente como chegou** (os mesmos bytes, sem abrir o JSON e montar de novo), e faça a mistura com o seu segredo: é o HMAC-SHA256, que qualquer linguagem tem pronto. 3. Compare o resultado com cada `v1`. Igual a algum: pode confiar. Diferente de todos: responda `401` e ignore o evento. ```js import crypto from 'node:crypto'; 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; } ``` ```python import hashlib import hmac import re import time 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 ``` ```js import http from 'node:http'; import { verifyLunaSignature } from './verify.mjs'; const SECRET = process.env.LUNA_WEBHOOK_SECRET; // whsec_... const seen = new Set(); // em produção: um banco ou Redis, com prazo de validade async function handle(event) { switch (event.event_type) { case 'message.received': // wa_id pode ser null (usuário sem telefone): então a chave é o user_id console.log('received', event.message.wa_id ?? event.message.user_id, event.message.text); break; case 'message.status': console.log('status', event.message.wamid, event.message.status); break; default: console.log('ignored', event.event_type); // tipos novos podem aparecer } } 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 primeiro, trabalhe depois const event = JSON.parse(raw.toString('utf8')); if (seen.has(event.event_id)) return; // pelo menos uma vez: descarte as repetições seen.add(event.event_id); handle(event).catch((err) => console.error('handler failed', err)); // o tratamento nunca roda na thread da requisição: o trabalho vai para uma fila }); }) .listen(Number(process.env.PORT ?? 3000)); ``` ```python import json import os import queue import threading from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer from verify import verify_luna_signature SECRET = os.environ["LUNA_WEBHOOK_SECRET"] # whsec_... seen = set() # em produção: um banco ou Redis, com prazo de validade seen_lock = threading.Lock() events = queue.Queue() # o tratamento nunca roda na thread da requisição: o trabalho vai para uma fila def handle(event): kind = event["event_type"] if kind == "message.received": # wa_id pode ser null (usuário sem telefone): então a chave é o user_id print("received", event["message"]["wa_id"] or event["message"]["user_id"], event["message"]["text"]) elif kind == "message.status": print("status", event["message"]["wamid"], event["message"]["status"]) else: print("ignored", kind) # tipos novos podem aparecer def worker(): # um trabalhador pega os eventos um a um (chame o LLM aqui, e não na requisição) 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))) header = self.headers.get("X-Luna-Signature") if not verify_luna_signature(raw, header, SECRET): self.send_response(401) self.send_header("Content-Length", "0") self.end_headers() return self.send_response(200) # responda 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 # pelo menos uma vez: descarte as repetições seen.add(event["event_id"]) if not repeated: events.put(event) threading.Thread(target=worker, daemon=True).start() ThreadingHTTPServer(("", int(os.environ.get("PORT", "3000"))), Handler).serve_forever() ``` O servidor responde `200` na hora e entrega o evento a uma fila (a thread de trabalho do Python, a promessa solta do Node): se ele fizesse o trabalho antes de responder, uma chamada lenta a outro sistema passaria dos 10 segundos que a Luna espera e a entrega seria contada como falha. Conferir a assinatura com o `openssl`, passo a passo, está em [Receber eventos](https://lunahia.com.br/docs/receber-eventos#assinatura). Agora cadastre a URL pública do servidor. Pelo console, use **Integração**, **Webhooks**, **Cadastrar endpoint**. Pela API: ```bash curl -X POST "https://api.lunahia.com.br/v1/webhooks/endpoints" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks/luna" }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "url": "https://example.com/webhooks/luna" }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/webhooks/endpoints", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "url": "https://example.com/webhooks/luna", }, timeout=10, ) print(res.status_code, res.json()) ``` Resposta `201` ```json { "id": "5c0e9a52-3a0e-4c3f-9f3e-0b3f6f1a2c77", "url": "https://example.com/webhooks/luna", "createdAt": "2026-10-06T14:00:00.000Z", "updatedAt": "2026-10-06T14:00:00.000Z", "previousSecretExpiresAt": null, "secret": "whsec_EXAMPLE_NOT_A_REAL_SECRET" } ``` > O campo `secret` aparece nesta resposta e em mais nenhuma. Guarde-o agora, em `LUNA_WEBHOOK_SECRET`. A URL precisa ser `https` e apontar para um endereço público, e a Luna não segue redirecionamento. ## 5. Envie a primeira mensagem Texto livre só sai para quem falou com o seu número nas últimas 24 horas (a [janela de 24 horas](https://lunahia.com.br/docs/glossario#janela)). Então, antes de enviar, **escreva do seu celular para o número conectado**. Isso abre a janela, e é também o seu primeiro evento recebido (veja o passo 6). Depois responda por `POST /v1/messages`. O `from` é o número de origem, o `metaPhoneNumberId` do passo 3 (`LUNA_NUMBER_ID`). O `to` é o telefone do destinatário, só dígitos, com o código do país e sem o sinal de mais (`LUNA_TO`, o seu celular): ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d @- < `Idempotency-Key` é um cabeçalho **opcional** e fica fora do exemplo acima. Ele serve para uma coisa: se você repetir a chamada (por um tempo esgotado, por exemplo), a Luna devolve a mesma mensagem em vez de enviar uma segunda. Mande um valor único para cada mensagem, como um UUID. Em agente de IA ele é quase obrigatório: veja [Agente de IA](https://lunahia.com.br/docs/agente-de-ia#idempotencia). ```bash curl -X GET "https://api.lunahia.com.br/v1/messages/$LUNA_MESSAGE_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch(`https://api.lunahia.com.br/v1/messages/${process.env.LUNA_MESSAGE_ID}`, { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( f"https://api.lunahia.com.br/v1/messages/{os.environ['LUNA_MESSAGE_ID']}", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` ## 6. Veja o primeiro evento O servidor do passo 4 deve ter impresso o `message.received` da mensagem que você escreveu do celular, e depois um `message.status` para cada mudança de estado da resposta que você enviou. Estes são os corpos: `message.received` ```json { "version": "2026-11-10", "event_id": "a2f4909b0fd2db8ab8b1bfe4e16487f49b86113e27bf8c3c9d10a2d0fefebc72", "event_type": "message.received", "occurred_at": "2026-10-06T14:02:11.482Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "message": { "id": "b6d84033-a8e8-4db9-aab6-565ce203cc51", "wamid": "wamid.EXAMPLE_NOT_A_REAL_ID", "wa_id": "5511900000000", "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": null, "type": "text", "text": "Oi! Queria saber o status do meu pedido.", "profile_name": "Maria Souza", "media": null, "interactive": null, "button": null, "location": null, "contacts": null, "reaction": null, "context": null, "referral": null, "unsupported": null, "edit": null, "revoke": null, "order": null } } ``` `message.status` ```json { "version": "2026-11-10", "event_id": "464e089a80690f1792db6249678ddeced5ad5be0d46d95e2daa263779f7d92e5", "event_type": "message.status", "occurred_at": "2026-10-06T14:02:14.090Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "message": { "id": "ae60f288-7565-4315-a440-3663e9c231e1", "wamid": "wamid.EXAMPLE_NOT_A_REAL_ID", "wa_id": "5511900000000", "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": null, "status": "sent", "error_code": null, "error": null, "pricing": { "billable": false, "pricing_model": "PMP", "type": "free_customer_service", "category": "service" }, "callback_data": "atendimento-8841" } } ``` ### Ler a mensagem recebida sem webhook Não precisa de servidor para ver o que o seu celular mandou: a Luna guarda as mensagens, e `GET /v1/messages` as lista, da mais nova para a mais antiga. Com `direction=inbound` vêm só as recebidas. O escopo é `messages:read`: ```bash curl -X GET "https://api.lunahia.com.br/v1/messages?direction=inbound&limit=5" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages?direction=inbound&limit=5', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/messages?direction=inbound&limit=5", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` Resposta `200` (resumida) ```json { "data": [ { "id": "b6d84033-a8e8-4db9-aab6-565ce203cc51", "direction": "inbound", "type": "text", "bodyText": "oi", "waId": "5511999990000", "createdAt": "2026-10-06T14:00:00.000Z" } ], "nextCursor": null } ``` O `waId` é o telefone de quem escreveu: é o valor do `to` para responder. Para ver só uma conversa, acrescente `&waId=5511999990000`. ### Se nada chegou - Leia o número com `GET /v1/numbers/{id}` e olhe `subscriptionConfirmedAt`. Se ele for nulo, a inscrição do aplicativo na conta ainda não foi confirmada, e nenhum evento chega. - Confira se o servidor responde `2xx` em até 10 segundos. Qualquer outra resposta conta como falha e a entrega é retentada. - Peça de novo o evento de uma mensagem com `POST /v1/messages/{id}/replay`. Detalhes em [Receber eventos](https://lunahia.com.br/docs/receber-eventos#retentativas). - O estado do envio e o motivo de uma falha estão em `GET /v1/messages/{id}`, no campo `erros`. Veja [Erros](https://lunahia.com.br/docs/erros). ## Próximos passos - Conecte um número que continua no aplicativo do celular, ou que vem de outro provedor: [Conectar um número](https://lunahia.com.br/docs/conectar-numero). - Vai ligar um agente de IA? O laço completo, com código que roda: [Agente de IA](https://lunahia.com.br/docs/agente-de-ia). - Conheça os eventos e as garantias de entrega: [Receber eventos](https://lunahia.com.br/docs/receber-eventos). - Mande imagem, documento, botões e mais: [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens). - Inicie conversa fora da janela de 24 horas: [Templates](https://lunahia.com.br/docs/templates). - O contrato de cada rota está na [referência da API](https://lunahia.com.br/docs/referencia). --- # Conta e chaves Fonte: https://lunahia.com.br/docs/conta-e-chaves Tudo que o console faz com a sua conta também se faz pela API, porque o console é cliente dela. Este guia mostra o caminho completo: cadastrar, entrar, criar uma chave, usar os escopos, revogar, e ler a conta, o plano e o estado da plataforma. ## Como a API autentica Toda rota de integração pede uma chave no cabeçalho `Authorization`, no formato `Bearer hlsn_...`. A chave carrega escopos: cada rota exige o seu, e uma chave sem o escopo recebe `403`. Sem chave, ou com uma chave inválida ou revogada, a resposta é `401`. Há dois tipos de credencial. A **chave de integração** é a do seu servidor: vale até ser revogada. A **sessão** é a do console: vale oito horas, nasce do login, e não cria nem revoga chaves sozinha. Para criar uma chave, a sessão confirma a senha antes (passo 3 abaixo). ## 1. Cadastrar a conta `POST /v1/operators/signup` cria a conta e o primeiro operador numa chamada só, sem credencial. A senha tem no mínimo 12 caracteres, e quem monta a tela lê esse mínimo em `GET /v1/public/password-policy` (`{ "minLength": 12 }`, sem credencial), em vez de copiar o número. A resposta é `201` e não traz sessão: o próximo passo é entrar. ```bash curl -X POST "https://api.lunahia.com.br/v1/operators/signup" \ -H "Content-Type: application/json" \ -d '{ "email": "ana@suaempresa.com.br", "password": "uma frase longa que so voce sabe", "tenantName": "Sua Empresa" }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/operators/signup', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ "email": "ana@suaempresa.com.br", "password": "uma frase longa que so voce sabe", "tenantName": "Sua Empresa" }), }); console.log(res.status, await res.json()); ``` ```python import requests res = requests.post( "https://api.lunahia.com.br/v1/operators/signup", json={ "email": "ana@suaempresa.com.br", "password": "uma frase longa que so voce sabe", "tenantName": "Sua Empresa", }, timeout=10, ) print(res.status_code, res.json()) ``` ```json { "nextStep": "login" } ``` A Luna manda um e-mail com um link de confirmação. Ele vale por sete dias e é aceito uma vez. A conta já lê a documentação e cria chaves antes de confirmar, mas só a conta confirmada abre sessão de conexão de número. Se o e-mail não chegou, `POST /v1/operators/confirmation/resend` envia de novo (só com a sessão do console, e há um teto de poucos reenvios por hora). ## 2. Entrar `POST /v1/operators/login` troca e-mail e senha por uma credencial de sessão de oito horas. O campo `token` é o `Bearer` das próximas chamadas deste guia que usam a sessão. A recusa é sempre a mesma, seja senha errada ou conta inexistente. ```bash curl -X POST "https://api.lunahia.com.br/v1/operators/login" \ -H "Content-Type: application/json" \ -d '{ "email": "ana@suaempresa.com.br", "password": "uma frase longa que so voce sabe" }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/operators/login', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ "email": "ana@suaempresa.com.br", "password": "uma frase longa que so voce sabe" }), }); console.log(res.status, await res.json()); ``` ```python import requests res = requests.post( "https://api.lunahia.com.br/v1/operators/login", json={ "email": "ana@suaempresa.com.br", "password": "uma frase longa que so voce sabe", }, timeout=10, ) print(res.status_code, res.json()) ``` ```json { "tenantId": "0b5e3c1a-7d42-4f6a-9c18-2e7a1d5b8f90", "operatorId": "6a2d9f40-1b73-4e85-a0c6-3d8e5f7b9a12", "token": "hlsn_...", "expiresAt": "2026-10-28T20:00:00.000Z", "scopes": [ "onboarding:write", "numbers:read", "numbers:write", "messages:read", "messages:write", "templates:read", "templates:write", "webhooks:read", "webhooks:write", "keys:read", "session:end", "session:elevate" ] } ``` Guarde o token da sessão ```bash export LUNA_SESSION="hlsn_..." ``` Para trocar a senha sabendo a de hoje, sem passar pelo "Esqueci minha senha", use `POST /v1/operators/password/change` com a sessão e o corpo `{ "currentPassword": "...", "newPassword": "..." }`. A resposta é `204`. A senha nova segue a mesma regra do cadastro, as outras sessões do operador são encerradas e a que pediu a troca continua valendo. Senha atual errada responde `401`, e há um teto de tentativas por sessão. ## 3. Confirmar a senha Criar e revogar chave é uma ação sensível. `POST /v1/operators/step-up` confirma a senha do operador da sessão e abre uma janela de duas horas em que essa mesma sessão pode criar e revogar chaves. A resposta traz `elevatedUntil`, o fim da janela, e em `scopes` o que a janela empresta à sessão (`keys:write`). Passadas as duas horas, a senha é pedida de novo. Com a sessão do passo 2 ```bash curl -X POST "https://api.lunahia.com.br/v1/operators/step-up" \ -H "Authorization: Bearer $LUNA_SESSION" \ -H "Content-Type: application/json" \ -d '{ "password": "uma frase longa que so voce sabe" }' ``` ```json { "elevatedUntil": "2026-10-28T14:00:00.000Z", "scopes": ["keys:write"] } ``` Para saber se a janela ainda está aberta sem pedir a senha à toa, leia `GET /v1/operators/session` com a sessão: `expiresAt` é o fim da sessão, `elevatedUntil` é o fim da janela (nulo sem janela ou com ela fechada) e `scopes` são os escopos que a sessão tem agora. Pede o escopo `session:end`, que a sessão do console já tem. ## 4. Criar uma chave `POST /v1/api-keys` cria a chave. Peça só os escopos de que ela precisa: uma chave que só envia mensagem não deveria poder conectar número nem criar outras chaves. Com `externalId`, a chave é de UM cliente seu e só enxerga o que é dele. Com `mode: "test"`, a chave é de teste: ela envia sem ir à Meta, e só usa duas rotas (veja [Modo de teste](https://lunahia.com.br/docs/modo-de-teste)). A resposta traz o campo `secret` **uma única vez**: não há rota que o devolva depois, e quem o perde revoga a chave e cria outra. Com a sessão, dentro da janela do passo 3 ```bash curl -X POST "https://api.lunahia.com.br/v1/api-keys" \ -H "Authorization: Bearer $LUNA_SESSION" \ -H "Content-Type: application/json" \ -d '{ "label": "Integração de produção", "scopes": [ "messages:write", "messages:read", "numbers:read" ] }' ``` ```json { "id": "7d1f4c02-9a3b-4e51-8c7d-2f0b6a91e334", "label": "Integração de produção", "kind": "integration", "scopes": ["messages:write", "messages:read", "numbers:read"], "mode": "live", "externalId": null, "createdAt": "2026-10-28T12:10:44.201Z", "expiresAt": null, "revokedAt": null, "lastUsedAt": null, "secret": "hlsn_..." } ``` Guarde o segredo, que é a chave do seu servidor ```bash export LUNA_API_KEY="hlsn_..." ``` ## Os escopos A lista é fechada e igual para todas as contas. Estes são os escopos que uma chave de integração pode ter. Os escopos `session:end` e `session:elevate` existem só nas sessões do console. | Escopo | O que deixa fazer | | --- | --- | | `keys:read` | Listar e consultar as chaves da conta. | | `keys:write` | Criar e revogar chaves. | | `numbers:read` | Ler números, a saúde deles, as contas de negócio, os links de conexão, a conta e o plano. | | `numbers:write` | Editar o rótulo de um número, reconectar e desconectar. | | `messages:read` | Ler mensagens e conversas, e baixar a mídia que chegou. | | `messages:write` | Enviar mensagens, enviar arquivos de mídia, marcar como lida e mostrar “digitando”. | | `templates:read` | Listar e consultar templates. | | `templates:write` | Criar, editar e remover templates, e enviar os arquivos de exemplo. | | `onboarding:write` | Conectar números: abrir e concluir sessões, reconectar, informar o PIN, e criar e apagar links de conexão. | | `webhooks:read` | Ler os endpoints de webhook, os tipos de evento e os eventos que a Luna desistiu de entregar. | | `webhooks:write` | Cadastrar, editar, testar e remover endpoints, trocar o segredo, reenfileirar eventos e pedir que o evento de uma mensagem seja entregue de novo. | `GET /v1/api-keys/scopes` devolve esta mesma lista pela API: cada escopo com o nome em português (`label`), o que ele permite (`summary`) e `sensitive`, que é `true` nas permissões que dão um poder que exige cuidado (criar chaves e redirecionar o webhook). `GET /v1/api-keys/profiles` devolve os perfis prontos, `agent` (atendimento), `full` (integração completa) e `read_only` (somente leitura), cada um com os escopos que concede. Ao criar a chave, mande `profile` no lugar de `scopes`, um dos dois e nunca os dois: a chave nasce com os escopos que o perfil concede naquele momento, e guarda os escopos, e o perfil fica só como rótulo, em `profile` (nulo quando você escolheu os escopos um a um). Cada chave da lista traz também `status` (`active`, `revoked` ou `expired`, decidido pela API) e `allowedActions` (`revoke` enquanto a chave de integração vale), para você mostrar o botão sem comparar datas. As duas rotas pedem `keys:read`. > O escopo de cada rota está na [referência da API](https://lunahia.com.br/docs/referencia), no topo de cada operação. Escopo faltando é `403`, e a resposta não diz qual faltou além do que a rota pede. ## Listar e revogar chaves `GET /v1/api-keys` lista as chaves, com escopos, criação, último uso e revogação. O segredo nunca aparece. Use `kind=integration` para ver só as chaves de integração e esconder as sessões do console. O escopo é `keys:read`. ```bash curl -X GET "https://api.lunahia.com.br/v1/api-keys?kind=integration" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/api-keys?kind=integration', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/api-keys?kind=integration", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` `POST /v1/api-keys/{id}/revoke` invalida a chave na hora. Repetir a chamada devolve o mesmo resultado, sem erro, e a data da revogação fica registrada. Pede `keys:write` e, para a sessão do console, a janela do passo 3. ```bash curl -X POST "https://api.lunahia.com.br/v1/api-keys/YOUR_KEY_ID/revoke" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/api-keys/YOUR_KEY_ID/revoke', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/api-keys/YOUR_KEY_ID/revoke", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` ## Ler a conta e o plano `GET /v1/account` devolve a conta da credencial: identificador, nome, se o e-mail já foi confirmado e quando a conta foi criada. Não tem escopo próprio: pede `numbers:read`, o mais leve dos escopos de leitura. O campo `operatorEmail` só vem preenchido quando a credencial é uma sessão do console. ```bash curl -X GET "https://api.lunahia.com.br/v1/account" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/account', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/account", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` ```json { "id": "0b5e3c1a-7d42-4f6a-9c18-2e7a1d5b8f90", "name": "Sua Empresa", "emailConfirmed": true, "createdAt": "2026-10-28T11:58:02.114Z", "operatorEmail": null } ``` `PATCH /v1/account` troca o nome da conta. O corpo é `{ "name": "..." }`, de 1 a 120 caracteres, e a resposta é a conta já com o nome novo, no mesmo formato do `GET`. Só a sessão do console faz isto (escopo `session:end`), e a suspensão do plano não bloqueia. `GET /v1/subscription` devolve o plano, a capacidade de números e quantos estão em uso. Ele tem um guia próprio: [Plano e números](https://lunahia.com.br/docs/plano-e-numeros). ```bash curl -X GET "https://api.lunahia.com.br/v1/subscription" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/subscription', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/subscription", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` `GET /v1/account/overview` devolve o resumo que uma tela inicial precisa, já decidido pela API: `attention`, a lista do que a conta precisa olhar (cada item com `code`, `severity`, `title`, `message`, `solution`, o `resource` a que se refere, a `action` que resolve e `since`), na ordem em que deve aparecer, com o que está parado primeiro; `checklist`, os quatro primeiros passos (`connect_number`, `create_key`, `add_webhook_endpoint` e `send_message`), cada um com `done` e `doneAt`; e `numbers`, os números por estado de conexão. Pede `numbers:read`, e uma chave restrita a um cliente seu é recusada, porque o resumo é da conta inteira. ## Ver se a plataforma está de pé `GET /status` não pede chave e não revela dado de nenhuma conta. Ele responde o estado da plataforma, medido a cada poucos minutos por uma mensagem sintética que entra pela mesma porta que a Meta usa e precisa chegar a um destino por HTTPS. O `status` é `ok`, `degraded`, `down` ou `unknown`; sem verificação recente, é `unknown`, e nunca `ok`. `components` separa a entrada (`ingestion`), a entrega (`delivery`) e o horizonte de partições do banco (`partitions`). ```bash curl -X GET "https://api.lunahia.com.br/status" ``` ```js const res = await fetch('https://api.lunahia.com.br/status', { method: 'GET', }); console.log(res.status, await res.json()); ``` ```python import requests res = requests.get( "https://api.lunahia.com.br/status", timeout=10, ) print(res.status_code, res.json()) ``` ```json { "status": "ok", "checkedAt": "2026-10-28T12:05:00.000Z", "components": { "ingestion": "ok", "delivery": "ok", "partitions": "ok" }, "since": "2026-10-27T09:30:00.000Z" } ``` `GET /healthz` é a sonda mais simples: responde `200` quando o processo está de pé, e não diz nada sobre o envio de mensagens. A página de status do site mostra o mesmo estado, para quem prefere ler a chamar. ## Próximos passos Com a chave na mão, conecte um número em [Conectar um número](https://lunahia.com.br/docs/conectar-numero) e envie a primeira mensagem em [Primeiros passos](https://lunahia.com.br/docs/primeiros-passos). O contrato de cada rota está na [referência da API](https://lunahia.com.br/docs/referencia). ## Detalhes das rotas deste guia A [referência da API](https://lunahia.com.br/docs/referencia) diz como chamar cada rota, em poucas linhas. O que explica o motivo de cada decisão, os casos de borda e os avisos está aqui, na ordem da referência. ### GET /v1/api-keys O segredo nunca volta aqui, nem em rota nenhuma. A Luna guarda apenas um resumo criptográfico dele. Se você perdeu a chave, revogue e crie outra. Use kind=integration para ver só as chaves de integração e esconder as sessões do console. ### POST /v1/api-keys Dê a ela só os escopos de que ela precisa. Uma chave que só envia mensagem não deveria poder conectar número nem cunhar outras chaves. externalId, opcional, faz a chave ser de UM cliente seu: ela só lê e envia pelos números com aquele externalId (inclusive os que forem conectados depois com o mesmo rótulo), só cria link de conexão com ele, só vê templates e contas de negócio das WABAs desses números, e não lista nem cria endpoints de webhook nem chaves. Número de outro cliente seu responde 404, como um que não existe, e rota fora desse conjunto responde 403. Use para dar acesso direto ao cliente do seu cliente, ou para reduzir o estrago de uma chave vazada. O externalId não muda depois da criação. ### POST /v1/api-keys/{id}/revoke Revogação não apaga a linha. A data fica registrada, para que uma auditoria consiga responder quando o acesso terminou. ### GET /v1/subscription capacity é quantos números a conta pode manter ativos ao mesmo tempo, e activeNumbers é quantos estão ativos agora. Quando activeNumbers chega a capacity, abrir uma sessão de conexão ou criar um link de conexão responde 409 number_capacity_reached; reconectar um número que já conta não é recusado. Capacidade menor que o uso nunca desconecta ninguém: só recusa o próximo número. status diz em que pé a conta está. No teste grátis (14 dias, 1 número), trialEndsAt traz o fim e trialDaysLeft traz os dias que faltam, calculados aqui. Com o teste terminado e a conta sem contratação, ou com a conta bloqueada pela Helsen, status é suspended e suspendedReason diz o motivo: o envio e as escritas são recusados, a leitura e o recebimento de mensagens continuam, e o número segue conectado na Meta. A única grandeza faturável é a quantidade de números que este cliente manteve ativos no período. Nenhum evento da plataforma altera este valor: mensagem, conversa, template, mídia e sessão não entram nesta conta, por caminho nenhum. O uso da plataforma WhatsApp é cobrado pela Meta, diretamente do negócio final, no método de pagamento que ele cadastra na conta dele. A Helsen não intermedeia esse pagamento, não o adianta e não o repassa. Ativo significa capacidade configurada, e não apto a enviar agora. Um número aguardando o pagamento do cliente na Meta continua sendo capacidade configurada e continua contando. Um número ativo por três dias conta igual a um ativo o mês inteiro: não há fração de período. O período é meio-aberto: o início entra, o fim não. inicio e fim vêm juntos ou nenhum dos dois: sem eles, vale o mês corrente em UTC, calculado pela API. Mande os dois quando precisar de uma resposta que não dependa do relógio. A lista de identificadores traz os números que contaram no período, para que a contagem seja conferível. ### POST /v1/operators/signup A resposta não traz sessão. Depois do 201, autentique em POST /v1/operators/login com o mesmo e-mail e a mesma senha. A senha tem no mínimo 12 caracteres, sem exigência de composição. Comprimento protege mais que a mistura obrigatória de símbolos, que só produz senha previsível. Uma senha mais curta responde 400 com o campo password e o mínimo. Essa recusa pode ser dita: a regra é igual para todos e não revela nada de conta nenhuma. A conta nova entra, lê a documentação, cria e revoga chave de API e integra contra esta API. O que ela ainda não pode é abrir sessão de conexão de número: isso espera a confirmação do e-mail, e nada além dela. Um e-mail que já tem conta responde o mesmo 201, e o dono do endereço recebe um e-mail dizendo que a conta já existe e como entrar. Responder diferente entregaria de graça a lista de quem tem conta. ### GET /v1/operators/confirm O link vale por sete dias e é aceito uma única vez. Abrir de novo não desfaz a confirmação, e a conta continua confirmada. Toda recusa leva ao mesmo endereço, com erro=1. A resposta não diz se o token não existe, se expirou ou se já foi usado, porque distinguir os três entregaria informação sobre uma conta alheia. Confirmar o e-mail é o que libera a conexão de número: a conta confirmada já pode abrir sessão de conexão. ### POST /v1/operators/password/forgot A resposta é sempre 202, com o mesmo corpo, exista ou não uma conta com esse e-mail. Dizer qual dos dois entregaria de graça a lista de quem tem conta. O envio acontece depois da resposta, então o tempo também não distingue. Quando a conta existe, o link vale por uma hora e pode ser aberto uma única vez, e um pedido novo invalida o anterior. Pedidos repetidos para a mesma conta deixam de gerar e-mail depois de alguns por hora, e a resposta continua igual. O link aponta para a tela de redefinição do console. Quem integra pela API pura conclui com POST /v1/operators/password/reset, levando o token que vem no endereço. ### POST /v1/operators/password/reset A senha segue a mesma regra do cadastro: no mínimo 12 caracteres, sem exigência de composição. Uma senha fora da regra responde 400 com o campo password e o mínimo, antes de olhar o token. O token é aceito uma única vez e vale por uma hora. Token desconhecido, malformado, vencido ou já usado responde o mesmo 400, com o mesmo corpo, porque distinguir entregaria informação sobre uma conta alheia. Trocar a senha encerra todas as sessões do console desse operador. As chaves de API de integração não são sessões e continuam valendo. ### GET /v1/account Funciona com a sessão do console e com chave de API de integração. Não há escopo próprio para esta leitura: ela pede numbers:read, o mais leve dos escopos de leitura, e uma chave sem nenhum escopo de leitura recebe 403. operatorEmail é o e-mail do operador, e só existe quando a credencial é uma sessão do console. Uma chave de integração não tem pessoa atrás, e para ela o campo vem null. ### POST /v1/operators/confirmation/resend Só para a sessão do console: uma chave de API de integração não tem e-mail para receber o link e recebe 403. Responde 202 nos dois casos. Se a conta já estava confirmada nada é enviado e emailConfirmed vem true; caso contrário vem false e o e-mail saiu. Se o envio falha, responde 503 e vale tentar de novo. Há um teto de poucos reenvios por hora, por conta, e passado ele a resposta é 429. ### POST /v1/operators/login A recusa é sempre a mesma, byte a byte. A API não distingue senha errada de conta inexistente, porque distinguir entregaria de graça a lista de quem tem conta. A sessão não pode criar nem revogar chaves de API. Para isso existe a reautenticação. Depois de 10 tentativas erradas para o mesmo e-mail em 15 minutos, o login desse e-mail responde 429 com Retry-After até a janela vencer, inclusive com a senha certa. Se esqueceu a senha, use POST /v1/operators/password/forgot. ### POST /v1/operators/step-up Nenhuma credencial elevada é emitida. Não há segredo novo nesta resposta, nem linha nova no banco: o que muda é um instante gravado na própria sessão, e elevatedUntil é esse instante. Passadas as duas horas a senha volta a ser pedida, e reabrir a janela exige confirmá-la de novo. Encerrar a sessão encerra a janela junto, sem passo próprio. Não recebe email: a identidade vem da própria sessão. Assim a senha de um operador nunca eleva a sessão de outro. --- # Conectar um número Fonte: https://lunahia.com.br/docs/conectar-numero Há três situações: um número novo para a Cloud API, um número que continua funcionando no aplicativo WhatsApp Business do celular, e um número que já está na Cloud API de outro provedor. Em todas, o número e a conta de WhatsApp Business continuam sendo do negócio final. E há uma pergunta à parte: quem conecta. Se for o cliente do seu produto, você manda um link de conexão. ## Como a conexão funciona A conexão acontece no fluxo que a Meta chama de Embedded Signup. O dono do número escolhe, na janela da Meta, a conta de WhatsApp e o número dele, e autoriza o acesso na tela de consentimento. A Luna troca o código dessa autorização por acesso permanente, inscreve o aplicativo na conta e registra o número. - Não há QR Code. Cada negócio final precisa da própria conta de WhatsApp Business na Meta, com o método de pagamento dele. Veja [a diferença de modelo](https://lunahia.com.br/migrar-da-evolution-api) se você vem de uma biblioteca não oficial. - A Luna atende só números com código de país do Brasil (+55). Na conclusão, o número cujo telefone exibido não começa por 55 **não é registrado nem inscrito**, e a autorização do cliente não é guardada: a sessão termina em `COUNTRY_NOT_SUPPORTED`, com `motivo: "pais-nao-atendido"`, e a `orientacao` explica ao cliente. O link continua aberto, para o cliente tentar com um número +55. - A conta nova precisa ter o e-mail confirmado para abrir a conexão. Sem isso a API responde `403` com `error: "connection_not_released"`, e o campo `faltando` diz o que falta. - A janela da Meta só abre em um domínio autorizado no aplicativo da Luna, e esse domínio é o do console. Ela abre de dois jeitos: dentro do console, no menu **Números**, em **Conectar número**, com o operador da sua conta; ou na página de um link de conexão, que você manda ao seu cliente. A API não leva a janela para dentro do seu produto. Veja [como conectar o número de um cliente seu](#link-de-conexao). ## Conectar o número de um cliente seu Se o seu produto atende outras empresas, quem conecta o número é o negócio do seu cliente, e não você. A janela da Meta só abre no domínio do console da Luna, então você não a coloca dentro do seu produto. Você cria um **link de conexão** e manda ao seu cliente: é uma página da Luna que mostra o nome da sua conta e abre a janela da Meta para ele. Quem entra com o Facebook e aceita os termos da Meta é o negócio dele, e não você em nome dele. 1. Crie o link com `POST /v1/onboarding/links`, mandando o identificador do seu cliente em `externalId`. É um texto livre, de 1 a 128 caracteres, que a Luna não interpreta. 2. Envie a `url` da resposta ao seu cliente, pelo canal que você já tem com ele. 3. Quem avisa que o cliente terminou é o evento `number.connected`, entregue no seu endpoint de webhook com o `externalId` do cliente (veja [Receber eventos](https://lunahia.com.br/docs/receber-eventos)). A consulta continua valendo como reserva, para o caso de o seu endpoint ter estado fora do ar: leia o link em `GET /v1/onboarding/links/{id}` até o `status` virar `used`, ou liste os números do cliente por `externalId`. ```bash curl -X POST "https://api.lunahia.com.br/v1/onboarding/links" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "externalId": "cliente-8841" }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/onboarding/links', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "externalId": "cliente-8841" }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/onboarding/links", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "externalId": "cliente-8841", }, timeout=10, ) print(res.status_code, res.json()) ``` Resposta ```json { "id": "5b8a0e0e-9a1f-4d1c-8d27-2f0c5f3a7d10", "url": "https://app.lunahia.com.br/conectar/0f2c8e6a-1d3b-4a5c-9e7f-2b4d6a8c0e12.SEGREDO_DO_LINK", "expiresAt": "2026-10-10T14:00:00.000Z", "externalId": "cliente-8841" } ``` > **A `url` sai uma vez.** Nenhuma rota devolve o token de novo, nem a listagem. Quem tem a `url` pode conectar um número à sua conta, então trate-a como um segredo e mande só ao cliente certo. A conta precisa ter o e-mail confirmado, como para abrir qualquer conexão. ### Acompanhar o link Não é preciso consultar de tempos em tempos: quando o número termina de ser conectado, a Luna entrega o evento `number.connected` no seu webhook. Use a leitura abaixo como reserva, por exemplo para reconciliar depois de uma indisponibilidade do seu endpoint, e não como laço de espera. ```bash curl -X GET "https://api.lunahia.com.br/v1/onboarding/links/YOUR_LINK_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/onboarding/links/YOUR_LINK_ID', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/onboarding/links/YOUR_LINK_ID", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` Resposta, depois que o cliente conectou ```json { "id": "5b8a0e0e-9a1f-4d1c-8d27-2f0c5f3a7d10", "externalId": "cliente-8841", "status": "used", "expiresAt": "2026-10-10T14:00:00.000Z", "usedAt": "2026-10-08T15:30:12.000Z", "numberId": "ed404df1-b420-4ed6-8743-ba1609892e0a" } ``` | `status` | O que significa | | --- | --- | | `open` | O cliente ainda pode abrir o link e conectar. | | `used` | Uma conexão feita por este link concluiu. `usedAt` traz o instante. | | `expired` | Passou do prazo sem ser usado. | O `numberId` é o mesmo `id` de `GET /v1/numbers`. Ele aparece alguns instantes depois do `used`, porque a Luna registra o número em seguida, e fica nulo se a conta foi conectada sem número. Para achar os números de um cliente seu, filtre `GET /v1/numbers` com `?externalId=`, usando o mesmo rótulo. A comparação é exata, e um rótulo sem número devolve lista vazia: ```bash curl -X GET "https://api.lunahia.com.br/v1/numbers?externalId=cliente-8841" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/numbers?externalId=cliente-8841', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/numbers?externalId=cliente-8841", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` Todo número traz `externalId`, nulo quando foi conectado sem link. `GET /v1/onboarding/links` lista os links, do mais recente para o mais antigo, e nunca traz a `url`. Filtros: `?externalId=` (igualdade exata), `?q=` (o **começo** do `externalId`, sem diferenciar maiúscula, para quem lembra só do começo do nome do cliente) e `?status=`. ### O que o seu cliente vê - Uma página da Luna, sem login, que diz “o nome da sua conta pediu para conectar o WhatsApp do seu negócio”, lista o que ele precisa ter à mão e oferece as duas escolhas: número novo, ou número que ele já usa no WhatsApp Business. - A janela da Meta abre a partir dessa página. Ao terminar, a página diz “Número conectado. Você já pode fechar esta página.” - Se ele fechar a janela no meio, pode tentar de novo pela mesma página enquanto o link estiver aberto. - Da sua conta, a página mostra só o nome. Não há menu, nem caminho para o console. ### Prazo e revogação - O link vale **72 horas** para ser aberto. Passado o prazo, a página diz ao cliente que o link venceu e que ele deve pedir um novo a você. - Quando uma conexão feita pelo link conclui, ele passa a `used` e não abre outra sessão. Para conectar outro número do mesmo cliente, crie outro link. - Para cancelar, revogue o link com `DELETE /v1/onboarding/links/{id}`. A `url` passa a responder `404`, como se nunca tivesse existido, e uma conexão que o cliente já tinha começado não pode mais ser concluída por ela. O link continua na sua lista, com `status: "revoked"` e `revokedAt`, e `GET /v1/onboarding/links` aceita `?status=` para filtrar. Cada link traz também `purpose` (`new` ou `reconnect`), `lastFailure` (a última tentativa que não deu certo) e `allowedActions`. ```bash curl -X DELETE "https://api.lunahia.com.br/v1/onboarding/links/YOUR_LINK_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/onboarding/links/YOUR_LINK_ID', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status); ``` ```python import os import requests res = requests.delete( "https://api.lunahia.com.br/v1/onboarding/links/YOUR_LINK_ID", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code) ``` ### Vários links de uma vez, e a url perdida `POST /v1/onboarding/links/batch` cria até 100 links numa chamada: `{ "links": [{ "externalId": "cliente-1" }, { "externalId": "cliente-2", "redirectUrl": "https://..." }] }`, cada item com os mesmos campos do link individual (`externalId`, `redirectUrl` e `numberId`, todos opcionais). Cada item passa pelas mesmas regras da criação individual, inclusive a capacidade do plano, e a resposta é `200` com `results`, um por item na mesma ordem: `index`, `status` (`201` ou o status do erro daquele item), `link` (com a `url`, que aparece só aqui) ou `error`. Um item que falha não derruba os outros. A `url` aparece só na criação. Se o seu cliente perdeu o e-mail com ela, `POST /v1/onboarding/links/{id}/reissue` gera outra para o **mesmo** link, com o mesmo `externalId`, o mesmo `redirectUrl` e o mesmo prazo: a `url` antiga passa a responder `404` e a nova aparece só nessa resposta. Só vale para um link aberto (`allowedActions` traz `reissue`); usado, vencido ou revogado responde `409` com `link_not_open` e o estado em `status`. ## Número novo 1. No console, abra **Números**, **Conectar número**, e toque em **Conectar WhatsApp**. 2. Na janela da Meta, o dono do número escolhe a conta de WhatsApp e o número, e autoriza. 3. Acompanhe pelo console ou pela API. O código da conexão vale **30 segundos**, e o console o troca no mesmo instante em que ele chega. ```bash curl -X GET "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` Resposta (resumida) ```json { "id": "ed404df1-b420-4ed6-8743-ba1609892e0a", "metaPhoneNumberId": "123456789012345", "displayNumber": "+55 11 99999-0000", "state": "REGISTERED", "podeRetentar": false, "qualityRating": "GREEN", "orientacao": "Número conectado e operando. Mensagens já entram e saem por ele.", "tetoDeVazaoPorSegundo": null, "sincronizacaoDoHistorico": null, "subscriptionConfirmedAt": "2026-10-06T11:27:47.141Z", "credentialStatus": "active", "podeReconectar": false, "coexistence": false, "ready": true, "connection": { "status": "connected", "canSend": true, "reasons": [] } } ``` `ready` é verdadeiro quando o número está registrado e a inscrição do aplicativo foi confirmada, ou seja, quando o envio está liberado: use-o em vez de combinar `state` e `subscriptionConfirmedAt`. `coexistence` é verdadeiro quando a Luna já observou tráfego de coexistência no número, e pode passar de `false` para `true` depois da conexão. ### O estado resumido: connection Para mostrar ao seu cliente se o número dele está bem, leia `connection`, calculado pela API: `status` (`connected`, `connecting`, `action_required` ou `disconnected`), `canSend` (se enviar vai funcionar agora) e `reasons`, a lista de motivos com `code`, `message` e `solution`, em português, prontos para repassar. `GET /v1/numbers` traz o mesmo bloco em cada número e aceita `?state=`, `?wabaId=` (o id da conta de negócio na Meta, `waba.id`), `?qualityRating=` (`GREEN`, `YELLOW`, `RED`, `NA` ou `UNKNOWN`), `?connectionStatus=` (um dos quatro valores de `connection.status`), `?q=` (busca por prefixo, sem diferenciar maiúscula, em `externalId`, `label` e `displayNumber`; só dígitos também acham o número sem espaços e hífen), `?ready=`, `?canSend=` (true ou false), `?externalId=` (igualdade exata), `?limit=` (de 1 a 100) e `?cursor=` (o `nextCursor` da página anterior). Parâmetro que a rota não conhece volta `400` com o nome dele. Os eventos `number.action_required` e `number.action_resolved` avisam quando a lista de motivos passa de vazia para não vazia, e de volta; veja [Receber eventos](https://lunahia.com.br/docs/receber-eventos). Cada motivo em `reasons` traz também o que fazer com ele, para a sua tela não precisar decidir: `action` (`send_pin`, `reconnect`, `reconnect_link`, `meta_manager`, `wait` ou `contact_helsen`, e nulo quando não há ação), `actionUrl` (o endereço da conta no WhatsApp Manager da Meta, só com `meta_manager`), `docsUrl` (o guia que explica o motivo) e `since` (desde quando o motivo vale). Em `GET /v1/numbers/{id}`, `connection.steps` lista os quatro passos da conexão (`authorized`, `receiving`, `registered` e `ready`), cada um `done`, `current` ou `pending`, com o terceiro chamado de "Número vinculado" em coexistência. O campo `allowedActions`, em cada número da lista e no detalhe, é o que a sua conta pode fazer com ele agora: `disconnect`, `reconnect`, `reconnect_link`, `send_pin` e `edit_label`. A decisão considera o estado do número, a autorização do cliente, o e-mail confirmado, a suspensão e a capacidade do plano (reconectar um número que já conta não pede vaga nova). Mostre o botão quando o verbo está na lista, e não por `state`. Quando uma ação faria sentido e a conta a impede, `blockedActions` traz o verbo e a razão, em português, para você mostrar. Os escopos da chave que perguntou não entram na lista. ### Os estados de um número | `state` | O que significa | | --- | --- | | `PENDING`, `REGISTER_SENT` | O registro está em curso, e a plataforma o conduz sozinha. Não abra outra conexão: isso duplicaria trabalho que já está na fila. | | `REGISTERED` | O número está registrado na Cloud API. | | `PIN_REQUIRED` | O número exige o PIN da verificação em duas etapas, e a plataforma não o conhece. Veja [o PIN](#outro-provedor). | | `BLOCKED` | O número esgotou as tentativas de registro que a Meta concede numa janela de 72 horas. Só resta esperar a janela correr. | O campo `orientacao` traz, em português, o que está acontecendo e o que fazer. Ele é escrito para você repassar ao seu cliente sem reescrever. O campo `podeRetentar` diz se o estado admite uma nova tentativa de conexão: a decisão é da plataforma, porque cada tentativa de registro consome uma cota que a Meta conta por número. > **Olhe `subscriptionConfirmedAt`.** Ele registra quando a inscrição do aplicativo na conta foi confirmada. Enquanto for nulo, nenhum evento chega, e a falha é silenciosa: o número parece perfeito e não recebe nada. Se a Meta recusar o envio por falta de método de pagamento do negócio final, o número fica registrado e sem enviar. Não é erro da plataforma. A `orientacao` diz o que falta e onde resolver. ## Número que continua no aplicativo do celular (coexistência) A Meta chama de coexistência o caso de um número que hoje só existe no aplicativo WhatsApp Business do celular. Ele nunca passou por API nenhuma. Conectado assim, o número **continua funcionando no aplicativo**, e a Luna passa a operá-lo também. ### O que você precisa - O aplicativo **WhatsApp Business** (e não o WhatsApp comum) na versão **2.24.17 ou mais nova**. - A conta do negócio final habilitada para isso do lado da Meta. A opção só aparece na janela quando ela está. - Uso real prévio do aplicativo. A Meta recusa, com aviso de atividade insuficiente, um número recém-instalado ou que acabou de sair do WhatsApp comum. A tela de conexão do console recomenda usar o aplicativo por alguns dias, cerca de uma semana, e tentar de novo. ### Como conectar 1. No console, abra **Números**, **Conectar número**, e toque em **Conectar número que já uso no WhatsApp Business**. 2. Na janela da Meta, escolha a opção de conectar o aplicativo que você já usa, e não a de cadastrar número novo. 3. O código de confirmação chega como uma **mensagem no próprio WhatsApp**, no aplicativo do celular. ### O que muda depois de conectado - As **conversas anteriores do aparelho são importadas** para a plataforma, e aparecem em `GET /v1/messages` junto das novas. - O que o dono do negócio responde pelo aplicativo do celular **também chega**, na conversa do destinatário. - O envio tem **teto fixo de 20 mensagens por segundo** por número, e ele não sobe com o tempo. Um número fora da coexistência segue uma progressão que a Meta sobe sozinha conforme a qualidade. O campo `tetoDeVazaoPorSegundo` diz qual caso é o seu: com valor, é o teto fixo; nulo, vale `throughputLevel`. ### O que o número perde e o que pode desconectá-lo - Ao conectar, **todos os aparelhos conectados** (WhatsApp Web, computador) são desvinculados. O negócio pode conectá-los de novo depois, menos o WhatsApp para Windows e para WearOS, que não funcionam em coexistência. - Deixam de funcionar no número: **grupos**, chamadas de voz e vídeo, mensagens temporárias, visualização única, localização em tempo real, canais e as ferramentas de negócio do aplicativo. As **listas de transmissão** ficam só para leitura. - A Meta **desconecta** o número se o celular principal ficar cerca de **14 dias sem uso** (ou um aparelho conectado, cerca de 30 dias). O negócio precisa abrir o WhatsApp Business no celular de vez em quando. - O histórico importado cobre as conversas dos **últimos 180 dias** antes da conexão. - O que o negócio manda pelo aplicativo do celular **não abre nem estende a janela de 24 horas** e não entra na cobrança da Cloud API. O que sai pela Luna segue o preço da Cloud API normalmente. Fonte: documentação da Meta sobre coexistência, `https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users`. ### A importação do histórico tem prazo Passado o prazo sem concluir, a plataforma da Meta **desconecta o negócio final**, e ele precisa refazer a conexão no aparelho. Quem diz onde a importação está é `GET /v1/numbers/{id}`, nos campos `sincronizacaoDoHistorico` e `sincronizacaoPrazo`: | `sincronizacaoDoHistorico` | O que significa | | --- | --- | | nulo | Não há importação para este número. | | `em_curso` | Está acontecendo. `sincronizacaoPrazo` diz até quando. | | `concluida` | Terminou, e as conversas antigas já aparecem em `GET /v1/messages`. | | `recusada` | O dono do negócio recusou compartilhar no aparelho. Não vai concluir, e pedir de novo não muda isso. | - Não leia o percentual sozinho. `sincronizacaoProgresso` é um rótulo que a Meta atribui, e 100% **não** significa sucesso. Quem diz o desfecho é `sincronizacaoDoHistorico`, e só ele. - Nulo em `sincronizacaoProgresso` quer dizer que não há importação. Zero é uma importação que começou e ainda não andou. - `sincronizacaoPrazo` é a estimativa da plataforma: 24 horas contadas de quando ela viu a importação começar. O relógio da Meta começa um pouco antes, então trate o instante como limite e aja com folga. Se a importação ainda estiver em curso quando o prazo se aproxima, a Luna manda ao seu webhook o evento `history_sync.deadline_approaching`. O aviso sai antes do prazo, nunca depois, e é um só por número. Ele pode se repetir, sempre com o mesmo `event_id`. O estado corrente está em `GET /v1/numbers/{id}/health`. ```json { "version": "2026-11-10", "event_id": "d42ca56e44ef023d52b0a0739dcf3afb0d5054a8b84321c41e432ed6707b043f", "event_type": "history_sync.deadline_approaching", "occurred_at": "2026-10-07T03:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "history_sync": { "prazo": "2026-10-07T09:00:00.000Z" } } ``` ```bash curl -X GET "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/health" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/health', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/health", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` ## Número que vem de outro provedor Migrar um número que já está na Cloud API de outro provedor é um caminho suportado. Não exige número novo e não faz você perder o número atual. Se você vem de uma biblioteca não oficial, leia antes [o guia de migração da Evolution API](https://lunahia.com.br/migrar-da-evolution-api), que explica o que muda no modelo, e o de-para em [Vindo da Z-API ou da Evolution API](https://lunahia.com.br/docs/migrar-de-api-nao-oficial). Se você opera clientes por outro parceiro oficial, veja [Vindo de outro parceiro oficial](https://lunahia.com.br/docs/migrar-de-outro-parceiro). ### Os pré-requisitos são do lado do negócio final - Ser o dono da conta de WhatsApp Business. - Ter o número liberado no provedor anterior. - Conhecer o PIN da verificação em duas etapas, ou desligar essa verificação no WhatsApp Manager dele. ### O PIN Um número já registrado na Cloud API de outro provedor quase sempre tem verificação em duas etapas configurada lá, e a Meta exige o PIN existente para registrá-lo de novo. **Não há endpoint para ler nem para desligar esse PIN**, então ele precisa vir do negócio final. Quando o número fica em `PIN_REQUIRED`, informe o PIN: > A Meta está mudando o PIN. No novo modelo de contas ela já não usa o PIN enviado para validar o registro, mas manda continuar enviando um PIN de seis dígitos válido, e anuncia que o PIN da verificação em duas etapas está sendo retirado dos números elegíveis da Cloud API. Registrar de novo um número que já está registrado passa em silêncio, e a resposta da Meta pode trazer um campo dizendo que o PIN não foi redefinido: a Luna aceita essa resposta sem tratá-la como erro e confirma o registro lendo o número de volta. Se o seu número nunca chegar a `PIN_REQUIRED`, é porque a Meta não está exigindo PIN dele. ```bash curl -X POST "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/pin" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "pin": "123456" }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/pin', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "pin": "123456" }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/pin", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "pin": "123456", }, timeout=10, ) print(res.status_code, res.json()) ``` - O `pin` tem exatamente seis dígitos, e o `id` na URL é o da Luna, não o da Meta. - O PIN é guardado cifrado e nunca volta por rota nenhuma. - Um PIN errado é recusado pela Meta e consome uma das dez tentativas de registro que ela concede por número numa janela de 72 horas. Esgotar essas tentativas trava o número até a janela correr. - Por isso a plataforma guarda as últimas. Perto do fim, a rota responde `409` com `error: "register_budget_reserved"`, e os campos `tentativasRestantes` e `janelaVira` dizem quantas sobram e quando a janela vira. Confirme o PIN com o negócio final antes de tentar de novo. - Um número que não está aguardando o PIN responde `409` com `error: "pin_not_applicable"` e o `state` corrente. ## Quando a autorização expira `credentialStatus` diz se a autorização do cliente continua válida, e `waba.credentialExpiresAt` diz até quando (nulo quando ela não vence ou quando a Luna ainda não leu; `waba.credentialNeverExpires` distingue os dois). A Luna avisa **14 dias antes** do vencimento, no evento `number.credential_expiring` (veja [Saúde da conta](https://lunahia.com.br/docs/saude-da-conta#credencial)), e a API passa a dizer `podeReconectar` verdadeiro nessa janela. Quando a autorização morre de vez, `credentialStatus` vira `reauth_required`, e o número precisa ser reconectado. Há dois caminhos, e os dois substituem a autorização daquela conta em vez de criar uma segunda, sem contar um número novo. **Quem faz a janela da Meta é o seu cliente**, então o caminho normal é o link: crie um link de reconexão informando o `numberId`, e mande a `url` ao cliente. A página dele abre direto a renovação, e o link herda o `externalId` do número. ```bash curl -X POST "https://api.lunahia.com.br/v1/onboarding/links" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "numberId": "00000000-0000-4000-8000-000000000000" }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/onboarding/links', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "numberId": "00000000-0000-4000-8000-000000000000" }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/onboarding/links", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "numberId": "00000000-0000-4000-8000-000000000000", }, timeout=10, ) print(res.status_code, res.json()) ``` O outro caminho é a sessão de reconexão, para quando a janela da Meta é aberta no console da sua conta. Se `credentialStatus` for `reauth_required`, ou `podeReconectar` for verdadeiro, abra a sessão: ```bash curl -X POST "https://api.lunahia.com.br/v1/onboarding/reconnect" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "numberId": "00000000-0000-4000-8000-000000000000" }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/onboarding/reconnect', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "numberId": "00000000-0000-4000-8000-000000000000" }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/onboarding/reconnect", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "numberId": "00000000-0000-4000-8000-000000000000", }, timeout=10, ) print(res.status_code, res.json()) ``` A sessão devolvida é usada exatamente como a de uma conexão nova, e a conclusão substitui a autorização daquela conta em vez de criar uma segunda. Um número cuja autorização é válida e está a mais de 14 dias de vencer responde `409` com `error: "reconnect_not_applicable"` e o `credentialStatus` corrente, nas duas rotas. Autorização revogada em definitivo também responde `409`, e o caminho é uma conexão nova. Número que não é seu responde `404`, igual a número que não existe. ## As rotas de onboarding O console é cliente desta mesma API, sem rota privilegiada. Se você precisa entender o que ele faz, o ciclo de uma conexão é este: 1. `POST /v1/onboarding/sessions` abre a sessão e devolve `sessionId`, `configId`, `sdkVersion` (a versão da Graph API para o `FB.init` da janela da Meta, que a Luna atualiza: não a copie para o seu código), `csrfState` e `expiresAt`. A reconexão (`POST /v1/onboarding/reconnect`) e a página pública do link (`GET /v1/public/onboarding-links/{token}`) devolvem o mesmo `sdkVersion`. Enquanto a sessão não é concluída, nenhuma conta existe do lado da Luna. 2. O dono do número autoriza na janela da Meta, que devolve um código. 3. `POST /v1/onboarding/sessions/{id}/complete` troca o código por acesso permanente. O `csrfState` volta na conclusão e é comparado em tempo constante. 4. `GET /v1/onboarding/sessions/{id}` mostra o estado e a `orientacao`. `POST /v1/onboarding/sessions/{id}/abandon` registra, como telemetria, em que tela o fluxo parou. ```bash curl -X POST "https://api.lunahia.com.br/v1/onboarding/sessions" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/onboarding/sessions', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/onboarding/sessions", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` ```bash curl -X POST "https://api.lunahia.com.br/v1/onboarding/sessions/YOUR_SESSION_ID/complete" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "code": "YOUR_CODE_FROM_META", "csrfState": "YOUR_CSRF_STATE" }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/onboarding/sessions/YOUR_SESSION_ID/complete', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "code": "YOUR_CODE_FROM_META", "csrfState": "YOUR_CSRF_STATE" }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/onboarding/sessions/YOUR_SESSION_ID/complete", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "code": "YOUR_CODE_FROM_META", "csrfState": "YOUR_CSRF_STATE", }, timeout=10, ) print(res.status_code, res.json()) ``` - O código vale **30 segundos**. Chame a conclusão no mesmo instante em que ele chega, sem fila, sem trabalho intermediário e sem partida a frio no caminho. - `wabaId`, `phoneNumberId` e `businessId` são opcionais. Quando o navegador não os entrega, a Luna os descobre na Graph API a partir do próprio token. O que o navegador entrega é conferido com o que a Meta concedeu a esse token: se o `wabaId` não estiver entre as contas concedidas, ou o `phoneNumberId` não estiver na lista de números da conta, a sessão termina em `FAILED` com `motivo: "identificadores-divergentes"` e nada é guardado. Abra uma nova conexão. - A conclusão responde `200` mesmo quando um passo falha. O corpo traz o estado real (`state`, `terminal`, `motivo`, `podeRetentar`, `proximoPasso`), porque conexão que para no meio é estado de negócio, e não erro de requisição. - As rotas de onboarding pedem o escopo `onboarding:write`. > Para ver cada campo, abra a seção Onboarding na [referência da API](https://lunahia.com.br/docs/referencia). ## Detalhes das rotas deste guia A [referência da API](https://lunahia.com.br/docs/referencia) diz como chamar cada rota, em poucas linhas. O que explica o motivo de cada decisão, os casos de borda e os avisos está aqui, na ordem da referência. ### POST /v1/onboarding/sessions A janela da Meta que usa esta sessão só abre em um domínio cadastrado no aplicativo da Luna: o do console. Ela abre dentro do console, com o operador da sua conta, ou na página do link de conexão (POST /v1/onboarding/links), quando quem conecta é o cliente do seu produto. Esta rota não leva a janela para dentro do seu produto. O csrfState é o valor de amarração. Ele volta na conclusão e é comparado em tempo constante. Sem ele, quem descobrisse um sessionId poderia concluir a conexão de outra pessoa. A sessão tem prazo. Enquanto ela não é concluída, nenhuma conta existe do lado da Luna. ### GET /v1/onboarding/sessions/{id} Use para acompanhar o progresso depois da conclusão, ou para descobrir por que uma conexão parou. Estados terminais não avançam mais, e a orientação diz o que fazer em cada um. ### POST /v1/onboarding/sessions/{id}/abandon Não muda o estado da sessão e não é obrigatório. Existe para que a causa de um abandono seja descobrível depois, em vez de virar silêncio. ### POST /v1/onboarding/sessions/{id}/complete O código vale trinta segundos. Chame esta rota no mesmo instante em que ele chega, sem fila, sem trabalho intermediário e sem partida a frio no caminho. wabaId e phoneNumberId são opcionais de propósito. Quando o navegador não os entrega, o que acontece na prática, a Luna descobre os dois na Graph API a partir do próprio token. Mande o que você tiver. A v1 atende só números +55. Se o telefone do número que o cliente escolheu não é do Brasil, a conexão termina em COUNTRY_NOT_SUPPORTED, com motivo pais-nao-atendido: o aplicativo não é inscrito, o número não é registrado e a autorização do cliente não é guardada. A orientacao explica ao cliente, e podeRetentar é true, porque um número +55 conecta em seguida. Responde 200 mesmo quando um passo falha. O corpo carrega o estado real da sessão e o motivo, porque conexão que para no meio não é erro de requisição: é estado de negócio. ### POST /v1/numbers/{id}/pin O id na URL é o número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. Use quando state for PIN_REQUIRED. A Meta exige o PIN que já está configurado no número, e não um novo: não existe endpoint para ler nem para desligar o PIN de um número que já tem verificação em duas etapas, então apenas o negócio final o conhece. Se o número nunca teve verificação em duas etapas, o valor que você enviar passa a ser o PIN dele. O PIN é guardado cifrado e nunca volta por rota nenhuma. Ele não aparece na resposta, no registro de acesso nem em log. Depois da submissão o número volta ao ponto de onde a conexão prossegue, e a tentativa seguinte usa o PIN informado. PIN errado é recusado pela Meta e consome uma das dez tentativas de registro que ela concede a cada número numa janela de 72 horas. Esgotar essas tentativas trava o número até a janela correr, e por isso a plataforma guarda as últimas: quando o orçamento chega perto do fim, esta rota responde 409 dizendo quantas restam e quando a janela vira, em vez de gastar as que sobraram. Confirme o PIN com o negócio final antes de tentar de novo. Número que não está aguardando o PIN responde 409 com o estado corrente. Sobrescrever o PIN de um número que já conectou o deixaria sem caminho de volta. Número que não é seu responde 404, igual a número que não existe. ### POST /v1/onboarding/reconnect Use quando credentialStatus de GET /v1/numbers/{id} for reauth_required. O mesmo endpoint diz, em podeReconectar, se este caminho está disponível: a decisão é da plataforma, e não sua. A sessão devolvida é usada exatamente como a de uma conexão nova: leve o csrfState ao fluxo da Meta e conclua em POST /v1/onboarding/sessions/{id}/complete. A diferença está do nosso lado: a sessão já nasce amarrada à conta existente, então concluí-la substitui a autorização daquela conta em vez de criar uma segunda. A reconexão também é admitida antes de a autorização morrer, quando ela vence em até 14 dias (o mesmo aviso do evento number.credential_expiring). Número cuja autorização está válida e longe de vencer responde 409, e a resposta diz o estado corrente. Autorização revogada em definitivo também responde 409: esse estado não volta, e o caminho é uma conexão nova. Número que não é seu responde 404, igual a número que não existe. ### GET /v1/business-accounts numbers traz os números de cada conta na forma legível, para que uma tela de escolha possa mostrar o número em vez do identificador. Uma conta pode ter vários, e lista vazia é resposta válida e quer dizer conta conectada cujo número ainda não completou o registro. wabaId é o identificador da conta na Meta, e é o valor que a criação de template recebe. Essa é a razão de esta rota existir: sem ela, o único lugar em que o identificador aparecia era a resposta de conclusão do onboarding, que é um evento passado. status traz o último estado de saúde que a Meta avisou sobre a conta: restricted, restrictions (com tipo, prazo e orientação como a Meta mandou), disabled e violationType. A Meta não oferece consulta desse estado: a Luna lê de volta o aviso que recebeu, o mesmo que sai nos eventos account.restricted, account.violation, account.disabled e account.reinstated. Conta sobre a qual a Meta nunca avisou nada vem com tudo em ordem. credentialExpiresAt e credentialNeverExpires dizem até quando vale a autorização que o cliente deu à Luna: a Luna lê a validade na conexão e confere de hora em hora. Quando faltam 14 dias, o evento number.credential_expiring avisa uma vez por número. Para renovar, abra um link com POST /v1/onboarding/links informando numberId. paymentMethodOnMeta e currency vêm da conta do cliente na Meta: sem forma de pagamento, a Meta para de entregar mensagens de serviço depois da franquia de 1.000 por número por mês. O pagamento é do cliente com a Meta e a Luna não o intermedeia. Nulo quer dizer que a Luna ainda não leu. A rota não devolve a credencial em si. O estado da autorização do cliente sai em credentialStatus, na leitura de um número. name é o nome da conta de WhatsApp Business como a Meta o informa, nulo enquanto a Luna ainda não o leu. managerUrl é o endereço da conta no WhatsApp Manager, onde o dono da conta resolve pagamento, verificação e restrições. phoneNumbers traz os números da conta, cada um com id (o mesmo de GET /v1/numbers), displayNumber, externalId e label, na ordem em que foram conectados; numbers continua como estava. --- # SaaS com N clientes Fonte: https://lunahia.com.br/docs/saas-com-n-clientes Você tem um produto, os seus clientes têm negócios, e cada negócio precisa do próprio WhatsApp dentro do seu produto. Na Luna, cada negócio conecta o número dele (a “instância” é o número), e o fio que amarra tudo é o [`externalId`](https://lunahia.com.br/docs/glossario#externalid): o rótulo que você dá ao cliente. Ele volta no link, no número, na chave, no webhook e em todo evento de número e de link. Este guia segue o caminho de um SaaS que contrata 20 números. O contrato de cada rota, campo a campo, está na [referência da API](https://lunahia.com.br/docs/referencia). Este guia segue a ordem em que um produto com muitos clientes usa as rotas. ## O fio: um externalId por cliente O `externalId` é texto livre de 1 a 128 caracteres que a Luna nunca interpreta. Use o identificador do cliente no seu sistema. Ele nasce no link de conexão, vai para o número quando o cliente conecta, e a partir daí amarra o resto: | Onde | O que o externalId faz | | --- | --- | | `POST /v1/onboarding/links` | Marca o link e o número que resultar dele. | | Todo evento de número e de link | Vem em `number.external_id` (e em `link.external_id` nos eventos do link). Separa os clientes num endpoint só. Os eventos de template e o de teste não têm cliente: veja a tabela da seção 3. | | As listas de números, mensagens, conversas e links | O filtro `?externalId=` devolve só o que é do cliente, sem você guardar o mapa de números. | | `POST /v1/api-keys` | A chave de UM cliente: só enxerga e usa os números dele. | | `POST /v1/webhooks/endpoints` | O endpoint de UM cliente (`externalIds`), se você prefere uma URL por cliente. | > Um número conectado pelo console, sem link, nasce sem `externalId`. Dê um com `PATCH /v1/numbers/{id}`; o mesmo vale para reaproveitar um número para outro cliente seu. ## 1. A capacidade do plano O plano define uma coisa só: quantos números a conta mantém ativos ao mesmo tempo. Com 20 números contratados, você conecta 20 clientes. `GET /v1/subscription` diz a capacidade e quantos estão em uso, e o 21º link responde `409` com `error: "number_capacity_reached"`. Para contratar ou ampliar, escreva para contato@lunahia.com.br. Detalhes em [Plano e números](https://lunahia.com.br/docs/plano-e-numeros). ```bash curl -X GET "https://api.lunahia.com.br/v1/subscription" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/subscription', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/subscription", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` ## 2. Um link por cliente Crie um link com o `externalId` do cliente e mande a `url` a ele. A `url` sai **uma vez**: guarde ou envie na hora. O cliente abre a página da Luna, aceita os termos da Meta e conecta o número dele. Com `redirectUrl` (https), a página o devolve ao seu produto quando a conexão termina. > **Testando no teste grátis.** O teste tem capacidade para 1 número. Se esse número já está conectado, `POST /v1/onboarding/links` responde `409` com `error: "number_capacity_reached"`, mesmo com o corpo certo: a capacidade é conferida antes de tudo. Para ver o fluxo do link de ponta a ponta, desconecte o número (`DELETE /v1/numbers/{id}`, veja a seção 8) e crie o link para o cliente de teste, ou peça a ampliação da capacidade em contato@lunahia.com.br. ```bash curl -X POST "https://api.lunahia.com.br/v1/onboarding/links" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "externalId": "cliente-42", "redirectUrl": "https://app.example.com/whatsapp/conectado" }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/onboarding/links', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "externalId": "cliente-42", "redirectUrl": "https://app.example.com/whatsapp/conectado" }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/onboarding/links", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "externalId": "cliente-42", "redirectUrl": "https://app.example.com/whatsapp/conectado", }, timeout=10, ) print(res.status_code, res.json()) ``` Para os 20 clientes de uma vez, um laço sobre a sua lista. O script abaixo lê `customers.json`, cria um link por cliente e imprime as URLs; um `409` de capacidade aparece no terminal e o laço segue. create-links.mjs (Node 18 ou mais novo) ```js // create-links.mjs: one connect link per customer of yours. import { readFile } from 'node:fs/promises'; const API = 'https://api.lunahia.com.br'; const customers = JSON.parse(await readFile('./customers.json', 'utf8')); // customers.json: [{ "externalId": "cliente-1" }, { "externalId": "cliente-2" }] for (const customer of customers) { const res = await fetch(`${API}/v1/onboarding/links`, { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ externalId: customer.externalId, // where the link page sends your customer back to when the connection ends redirectUrl: `https://app.example.com/whatsapp/done?customer=${customer.externalId}`, }), }); if (!res.ok) { // 409 number_capacity_reached: the plan is full. Disconnect a number or ask for more capacity. console.error(customer.externalId, res.status, await res.json()); continue; } const link = await res.json(); // The url is returned ONCE. Send it to the customer now. console.log(customer.externalId, link.url); } ``` Quando a conexão termina, a página leva o cliente à sua `redirectUrl` e acrescenta na query `status` (o estado final da conexão), `externalId` (o rótulo do link), `numberId` (o número, quando a Luna já o registrou; logo depois de concluir ele costuma vir vazio e some da query) e `signature`: ```text https://app.example.com/whatsapp/conectado?status=APP_SUBSCRIBED&externalId=cliente-8841&signature=t%3D1793800000%2Cv1%3D9f2c... ``` ### Confira que o retorno veio da Luna Qualquer pessoa pode abrir a sua `redirectUrl` com um `status` inventado. A `signature` prova que a Luna montou aqueles valores: é a **mesma assinatura dos webhooks** (`t=,v1=`), feita com o segredo do endpoint de webhook mais antigo da sua conta (o mesmo `whsec_` que você já usa para validar eventos), sobre o texto `status=&numberId=&externalId=`, com os valores como estão na query (vazios quando ausentes). O instante vale 5 minutos: confira ao receber o cliente, e não depois. Sem endpoint de webhook cadastrado, a `signature` não vai, e nesse caso trate o retorno como não confiável e leia o estado em `GET /v1/numbers`. ```js import { verifyLunaSignature } from './verify.mjs'; // a mesma conferência de um webhook, sobre o texto que a página do link assinou (os valores como estão na query) export function verifyConnectionReturn(returnUrl, secret, nowMs = Date.now()) { const q = new URL(returnUrl).searchParams; const text = `status=${q.get('status') ?? ''}&numberId=${q.get('numberId') ?? ''}&externalId=${q.get('externalId') ?? ''}`; return verifyLunaSignature(Buffer.from(text), q.get('signature'), secret, nowMs); } ``` ```python from urllib.parse import parse_qs, urlparse from verify import verify_luna_signature def verify_connection_return(return_url, secret, now=None): # a mesma conferência de um webhook, sobre o texto que a página do link assinou (os valores como estão na query) q = {k: v[0] for k, v in parse_qs(urlparse(return_url).query).items()} text = f"status={q.get('status', '')}&numberId={q.get('numberId', '')}&externalId={q.get('externalId', '')}" return verify_luna_signature(text.encode(), q.get("signature"), secret, now) ``` O cliente também pode ser reconhecido na página: mande `displayName` (de 1 a 120 caracteres) em `POST /v1/onboarding/links` e ela mostra "Conexão do WhatsApp de ..." acima do título. **O nome que a janela da Meta mostra não dá para mudar:** a janela é da Meta e mostra o nome da Luna e do negócio, e não o do seu cliente. Para achar o link de um cliente, filtre pelo rótulo: ```bash curl -X GET "https://api.lunahia.com.br/v1/onboarding/links?externalId=cliente-42" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/onboarding/links?externalId=cliente-42', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/onboarding/links?externalId=cliente-42", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` O link vale 72 horas, abre uma vez e se revoga com `DELETE /v1/onboarding/links/{id}`. Mais sobre o fluxo do cliente e a coexistência em [Conectar um número](https://lunahia.com.br/docs/conectar-numero). ## 3. Todos os eventos num endpoint só O caminho recomendado é **um endpoint** para todos os clientes. Cadastre-o como em [Receber eventos](https://lunahia.com.br/docs/receber-eventos), verifique a assinatura, e separe os clientes por `number.external_id`. Quatro eventos contam a conexão de um cliente, e todos trazem o `externalId`: | Evento | O que diz | | --- | --- | | `onboarding.link.completed` | O cliente concluiu a conexão por um link. | | `onboarding.link.failed` | Uma tentativa não deu certo, com `reason` (abandonou, erro da Meta, número fora do +55, registro bloqueado) e `step`, a tela em que ele parou. | | `onboarding.link.expired` | O link venceu sem uso. Gere outro. | | `number.connected` | O número ficou pronto: já pode enviar e receber. | number.connected ```json { "version": "2026-11-10", "event_id": "458470a340db14358f03ac02fde7e3839cb6887f3071c06c57a3d9d456621996", "event_type": "number.connected", "occurred_at": "2026-10-07T13:45:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "waba_id": "102290129340398", "coexistence": false } } ``` O roteador abaixo é a parte do seu servidor que decide a quem o evento pertence. Chame-o depois de verificar a assinatura; ele descarta repetições pelo `event_id` e ignora o rótulo que você não conhece (responda `2xx` em qualquer caso). router.mjs ```js // router.mjs: one webhook endpoint for all your customers. // Call route(event) AFTER verifying the signature (see the Receive events guide). /** externalId -> { onEvent(event) } for each customer of yours. */ export function createRouter(handlers) { const seen = new Set(); return function route(event) { // The same delivery can arrive more than once: drop repeats by event_id. if (seen.has(event.event_id)) return 'duplicate'; seen.add(event.event_id); // number.external_id is on every event that goes through a number; // link events carry it in link.external_id. const customer = event.number?.external_id ?? event.link?.external_id ?? null; if (customer === null) return 'no-customer'; const handler = handlers.get(customer); // A label you do not know, or an event type you do not handle: answer 2xx anyway. if (handler === undefined) return 'unknown-customer'; handler.onEvent(event); return 'handled'; }; } ``` ### Onde está o externalId em cada evento | Evento | Onde vem o externalId | | --- | --- | | Mensagens e contatos: `message.received`, `message.status`, `message.echo`, `contact.*`, `backlog.dropped`, `history_sync.deadline_approaching` | `number.external_id` | | `number.*` (conectou, desconectou, qualidade, pagamento, ação, credencial, nome) e `account.*` | `number.external_id` | | `onboarding.link.completed` | `link.external_id`, e `number.external_id` do número que acabou de conectar | | Os outros do link: `onboarding.link.opened`, `onboarding.link.failed`, `onboarding.link.expired` | `link.external_id` (ainda não há número) | | Templates e o teste: `template.status`, `template.category`, `template.quality`, `webhook.test` | Em lugar nenhum: são da conta de negócio ou do teste, e não de um cliente. O roteador devolve `no-customer`, e só um endpoint sem filtro os recebe. | O `number.external_id` é `null` num número que nunca recebeu rótulo. Esse caso, e os eventos da última linha, são o `no-customer` do roteador: trate-os à parte, ou ignore. > **Um endpoint único é um ponto único de falha.** Se ele cair ou ficar lento, as entregas de **todos** os clientes esperam juntas: cinco falhas seguidas abrem o disjuntor desse endpoint, e quando ele volta o acumulado de todos chega de uma vez (veja [Receber eventos](https://lunahia.com.br/docs/receber-eventos#retentativas)). Com poucos clientes e um servidor que só grava e responde `200`, isso raramente pesa. Se o código de um cliente costuma falhar ou demorar, ou se um cliente não pode ser atrasado pelo outro, use **um endpoint por cliente** (seção 7): a falha de um não atrasa os demais. ### Um servidor completo em TypeScript O arquivo abaixo junta tudo: verifica a assinatura, responde `200`, descarta a repetição e entrega cada evento ao código do cliente certo, por um `Map`. Os tipos mostram que `external_id` pode ser `null`. Rode com `node server.ts` (Node 24 ou mais novo, que apaga os tipos sozinho) e `LUNA_WEBHOOK_SECRET` definida. server.ts ```ts // server.ts: run with Node 24 or newer: node server.ts import crypto from 'node:crypto'; import http from 'node:http'; // Os campos do evento que este arquivo lê (há mais: veja Receber eventos). interface LunaEvent { event_id: string; event_type: string; number?: { id: string; phone_number_id: string; external_id: string | null } | null; // external_id: null num número que nunca recebeu rótulo link?: { id: string; external_id: string | null } | null; } // 1. Verifique a assinatura (a explicação está no guia Receber eventos). const SECRET = process.env.LUNA_WEBHOOK_SECRET ?? ''; const TOLERANCE_SECONDS = 300; function verify(raw: Buffer, header: string | undefined): boolean { // raw: os bytes exatos que chegaram, nunca o JSON reserializado const m = /^t=(\d{1,15}),/.exec(header ?? ''); if (!m || !SECRET) return false; const t = Number(m[1]); if (Math.abs(Math.floor(Date.now() / 1000) - t) > TOLERANCE_SECONDS) return false; const expected = crypto.createHmac('sha256', SECRET).update(`${t}.`).update(raw).digest(); let ok = false; // na troca do segredo o cabeçalho traz dois valores v1: confira todos for (const [, hex] of (header ?? '').matchAll(/v1=([0-9a-fA-F]{64})/g)) { if (crypto.timingSafeEqual(Buffer.from(hex as string, 'hex'), expected)) ok = true; } return ok; } // 2. Os clientes: externalId -> o código que trata aquele cliente. type CustomerHandler = (event: LunaEvent) => void | Promise; const customers = new Map([ ['cliente-1', (event) => console.log('cliente-1', event.event_type)], ['cliente-2', (event) => console.log('cliente-2', event.event_type)], ]); const seen = new Set(); // em produção: um banco ou Redis, com prazo de validade function route(event: LunaEvent): 'duplicate' | 'no-customer' | 'unknown-customer' | 'handled' { if (seen.has(event.event_id)) return 'duplicate'; seen.add(event.event_id); // number.external_id nos eventos de um número; link.external_id nos eventos de um link const customer = event.number?.external_id ?? event.link?.external_id ?? null; if (customer === null) return 'no-customer'; const handler = customers.get(customer); if (handler === undefined) return 'unknown-customer'; // um rótulo que você não conhece: responda 2xx do mesmo jeito void Promise.resolve(handler(event)).catch((err) => console.error(customer, 'handler failed', err)); return 'handled'; } // 3. O servidor: verifique, responda e só então roteie. http .createServer((req, res) => { const chunks: Buffer[] = []; req.on('data', (chunk: Buffer) => chunks.push(chunk)); req.on('end', () => { const raw = Buffer.concat(chunks); const header = req.headers['x-luna-signature']; if (!verify(raw, typeof header === 'string' ? header : undefined)) { res.writeHead(401).end(); return; } res.writeHead(200).end(); // responda primeiro, trabalhe depois console.log(route(JSON.parse(raw.toString('utf8')) as LunaEvent)); }); }) .listen(Number(process.env.PORT ?? 3000)); ``` ## 4. Enviar por número Ache os números do cliente pelo rótulo e envie por um deles. `from` aceita o UUID da Luna ou o id da Meta. `?canSend=true` devolve só os números por onde enviar funciona agora. ```bash curl -X GET "https://api.lunahia.com.br/v1/numbers?externalId=cliente-42&canSend=true" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/numbers?externalId=cliente-42&canSend=true', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/numbers?externalId=cliente-42&canSend=true", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "from": "YOUR_NUMBER_ID", "to": "5511900000000", "type": "text", "text": { "body": "Seu pedido saiu para entrega." } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID(), }, body: JSON.stringify({ "from": "YOUR_NUMBER_ID", "to": "5511900000000", "type": "text", "text": { "body": "Seu pedido saiu para entrega." } }), }); console.log(res.status, await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "from": "YOUR_NUMBER_ID", "to": "5511900000000", "type": "text", "text": { "body": "Seu pedido saiu para entrega.", }, }, timeout=10, ) print(res.status_code, res.json()) ``` O histórico e as conversas também filtram pelo cliente, e o envio fora da janela de 24 horas é só por template. Veja [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens) e [Templates](https://lunahia.com.br/docs/templates). Com uma conta de negócio por cliente, `GET /v1/templates?wabaId=` ou `?phoneNumberId=` mostra os templates de cada um. ```bash curl -X GET "https://api.lunahia.com.br/v1/messages?externalId=cliente-42&limit=20" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages?externalId=cliente-42&limit=20', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/messages?externalId=cliente-42&limit=20", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` ## 5. O estado de cada número Para mostrar ao cliente se o número dele está bem, leia `connection` (a mesma conta que decide os eventos): `status` (`connected`, `connecting`, `action_required` ou `disconnected`), `canSend` e `reasons`, cada motivo com `code`, `message` e `solution` em português, prontos para repassar. ```bash curl -X GET "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` Resposta (resumida) ```json { "id": "ed404df1-b420-4ed6-8743-ba1609892e0a", "metaPhoneNumberId": "123456789012345", "externalId": "cliente-42", "state": "REGISTERED", "ready": true, "connection": { "status": "connected", "canSend": true, "reasons": [] } } ``` Você não precisa consultar os 20 números: `number.action_required` avisa quando um passa a precisar de ação (autorização vencendo, método de pagamento ausente na Meta, conta restrita), e `number.action_resolved` avisa quando deixa de precisar. A lista de números aceita `?state=`, `?ready=`, `?canSend=`, `?limit=` e `?cursor=` para montar o painel de todos de uma vez. number.action_required ```json { "version": "2026-11-10", "event_id": "8832cdd12544436fce3b39d709158baa046091d010b5ed144a289c81b807c710", "event_type": "number.action_required", "occurred_at": "2026-10-28T15:02:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "status": "action_required", "can_send": false, "reasons": [ { "code": "payment_required", "message": "A Meta recusou um envio deste número por falta de método de pagamento na conta de WhatsApp Business do negócio.", "solution": "O dono da conta cadastra o método de pagamento no WhatsApp Manager da Meta. A Luna não intermedeia esse pagamento. Quando um envio voltar a ser aceito, o aviso sai do ar." } ] } } ``` Autorização perto de vencer é o caso que se repete: abra um link de reconexão com `POST /v1/onboarding/links` informando `numberId`, e o cliente renova sem contar um número novo. Os casos estão em [Saúde da conta](https://lunahia.com.br/docs/saude-da-conta) e [Pagamento na Meta](https://lunahia.com.br/docs/pagamento-na-meta). ## 6. Uma chave por cliente Se o cliente do seu cliente acessa a API diretamente, ou se você quer reduzir o estrago de uma chave vazada, crie uma chave com `externalId`. Ela só lê e envia pelos números com aquele rótulo (inclusive os conectados depois), só cria link com ele, só vê os templates e as contas de negócio desses números, e **não** lista nem cria endpoints de webhook nem chaves, nem lê o plano. O número de outro cliente responde `404`, igual a um que não existe, mesmo que o id dele seja passado de propósito; uma rota fora do conjunto responde `403`. O `externalId` de uma chave não muda: para mudar, crie outra. **Quem cria a chave precisa do escopo `keys:write`.** A chave que você usa para chamar `POST /v1/api-keys` tem de tê-lo (no console, a sessão ganha esse poder por duas horas depois de você confirmar a senha). Sem o escopo, a resposta é `403`, e o corpo diz qual falta: `requiredScope: "keys:write"`. Os escopos da chave nova são escolhidos por você, dentro do que a chave de um cliente pode usar (mensagens, números, templates e o link de conexão). ```bash curl -X POST "https://api.lunahia.com.br/v1/api-keys" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "label": "Clínica Exemplo", "scopes": [ "messages:read", "messages:write", "numbers:read" ], "externalId": "cliente-42" }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/api-keys', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "label": "Clínica Exemplo", "scopes": [ "messages:read", "messages:write", "numbers:read" ], "externalId": "cliente-42" }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/api-keys", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "label": "Clínica Exemplo", "scopes": [ "messages:read", "messages:write", "numbers:read", ], "externalId": "cliente-42", }, timeout=10, ) print(res.status_code, res.json()) ``` A resposta `201` traz o `secret` da chave (`hlsn_...`) **uma única vez**: guarde-o agora, no seu banco, na linha daquele cliente, junto do `externalId`. Não há rota que o devolva depois; se você o perder, revogue a chave (`POST /v1/api-keys/{id}/revoke`) e crie outra. ## 7. Um webhook por cliente (opcional) Se o seu produto prefere uma URL por cliente, o endpoint aceita `externalIds` (e `phoneNumberIds`): ele só recebe os eventos de números com aquele rótulo, inclusive os conectados depois, e os eventos de link dele. Ausentes, ele recebe de todos. O `external_id` continua em todo evento, nos dois jeitos. A assinatura, a ordem, o reenvio e a fila de rejeitados são os de qualquer endpoint. ```bash curl -X POST "https://api.lunahia.com.br/v1/webhooks/endpoints" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://saas.example.com/luna/cliente-42", "externalIds": [ "cliente-42" ] }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "url": "https://saas.example.com/luna/cliente-42", "externalIds": [ "cliente-42" ] }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/webhooks/endpoints", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "url": "https://saas.example.com/luna/cliente-42", "externalIds": [ "cliente-42", ], }, timeout=10, ) print(res.status_code, res.json()) ``` ```bash curl -X PATCH "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "externalIds": [ "cliente-42", "cliente-43" ] }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID', { method: 'PATCH', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "externalIds": [ "cliente-42", "cliente-43" ] }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.patch( "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "externalIds": [ "cliente-42", "cliente-43", ], }, timeout=10, ) print(res.status_code, res.json()) ``` > Cada conta pode ter até **25 endpoints**, o mesmo limite para todos, de infraestrutura: um por cliente de um plano de 20 números, com folga. O endpoint com filtro de um cliente não recebe os eventos de outro; um evento que não diz sobre quem fala só chega a endpoint sem filtro. ## 8. Desconectar e trocar o cliente O cliente 21 entra no lugar do 3? Desconecte o número do 3 com `DELETE /v1/numbers/{id}`: ele sai da Luna, para de contar na capacidade e o evento `number.disconnected` avisa (`reason: "requested_by_tenant"`). A Luna não chama `deregister` na Meta, para não derrubar o número do cliente em outro provedor ou no aplicativo. O histórico fica. Para reaproveitar um número para outro cliente seu, troque o rótulo com `PATCH /v1/numbers/{id}`. ```bash curl -X DELETE "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status); ``` ```python import os import requests res = requests.delete( "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code) ``` ```bash curl -X PATCH "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "externalId": "cliente-43" }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID', { method: 'PATCH', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "externalId": "cliente-43" }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.patch( "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "externalId": "cliente-43", }, timeout=10, ) print(res.status_code, res.json()) ``` ## Em uma tabela | O que o seu produto faz | Como na Luna | | --- | --- | | Entrar um cliente | `POST /v1/onboarding/links` com `externalId` e `redirectUrl` | | Saber que ele conectou | `onboarding.link.completed` e `number.connected` | | Saber que ele desistiu | `onboarding.link.failed` e `onboarding.link.expired` | | Enviar | `POST /v1/messages` com `from` (UUID da Luna ou id da Meta) | | Receber de todos | Um endpoint e o `number.external_id` de cada evento | | Mostrar o estado | `connection` e `number.action_required` / `number.action_resolved` | | Dar acesso direto ao cliente | `POST /v1/api-keys` com `externalId` | | Uma URL por cliente | `externalIds` no endpoint de webhook | | Sair um cliente | `DELETE /v1/numbers/{id}` | | Ver a capacidade | `GET /v1/subscription` | > Vindo da Z-API ou da Evolution API? A página [Vindo da Z-API ou da Evolution](https://lunahia.com.br/migrar-da-evolution-api) traduz cada verbo da instância para esta lista. ## Detalhes das rotas deste guia A [referência da API](https://lunahia.com.br/docs/referencia) diz como chamar cada rota, em poucas linhas. O que explica o motivo de cada decisão, os casos de borda e os avisos está aqui, na ordem da referência. ### GET /v1/onboarding/links Cada um traz o status (open, used, expired ou revoked), o externalId que você deu e, depois que o cliente conecta, o numberId do número que resultou. Traz também createdAt, purpose (new para um número novo, reconnect para renovar a autorização de um número que já existe), revokedAt, lastFailure (a última tentativa que não deu certo, com step, reason e at, os mesmos do evento onboarding.link.failed, ou nulo) e allowedActions (revoke, só num link aberto). Nenhum traz o token nem a url: ela só saiu na criação. Use ?externalId= para achar os links de um cliente seu: a comparação é exata, e um rótulo sem link devolve lista vazia. Use ?status= (open, used, expired ou revoked) para filtrar pelo estado. Os links revogados continuam na lista. Para paginar, mande de volta o nextCursor da resposta anterior em cursor. Nulo significa fim. ### POST /v1/onboarding/links A janela de conexão da Meta só abre em domínio cadastrado no aplicativo da Luna. Por isso o link aponta para uma página do console da Luna, que mostra o nome da sua conta, explica o que será pedido e abre a janela da Meta para o seu cliente. Quem entra com o Facebook e aceita os termos da Meta é o negócio dele, e não você em nome dele. externalId é o seu identificador para este cliente, em texto livre de 1 a 128 caracteres. Ele fica no link e no número que resultar da conexão, e volta em GET /v1/numbers. redirectUrl, opcional, é para onde a página do link leva o seu cliente quando a conexão termina (https). A página acrescenta na query status (o estado final da conexão), externalId (o rótulo do link), numberId (o número, quando a Luna já o registrou; logo depois de concluir ele costuma vir vazio e então não vai, e o evento number.connected avisa quando fica pronto) e signature, a assinatura de webhook sobre status, numberId e externalId com o segredo do seu endpoint de webhook mais antigo, para você conferir que o retorno veio da Luna (código em SaaS com N clientes). Sem redirectUrl, o cliente fica na página da Luna. displayName, opcional, é o nome do seu cliente (de 1 a 120 caracteres) que a página do link mostra para ele reconhecer o pedido. A janela da Meta que abre em seguida mostra o nome da Luna e do negócio, e esse nome não dá para mudar. O ciclo do link também chega por webhook: onboarding.link.completed quando o cliente conclui, onboarding.link.failed quando uma tentativa não dá certo (com o motivo e a tela em que ele parou) e onboarding.link.expired quando o link vence sem uso, todos com o externalId. O link vale 72 horas para ser aberto. A resposta traz a url uma única vez: guarde-a ou envie-a agora, porque nenhuma rota devolve o token de novo. Quem tem a url pode conectar um número à sua conta, então trate-a como um segredo e mande-a só ao cliente certo. numberId é opcional e transforma o link em link de RECONEXÃO: a página do seu cliente abre direto a renovação da autorização daquele número, sem contar um número novo. Use quando credentialStatus for reauth_required, ou quando o evento number.credential_expiring avisar que a autorização vence em até 14 dias. As regras são as de POST /v1/onboarding/reconnect: número seu e com autorização que admite reconexão (podeReconectar true); caso contrário responde 409, e número que não é seu responde 404. Sem externalId, o link herda o do número. Para acompanhar, use GET /v1/onboarding/links/{id}, ou liste os números com ?externalId=. Para cancelar, use DELETE /v1/onboarding/links/{id}. As mesmas condições de POST /v1/onboarding/sessions valem aqui: a conta precisa ter o e-mail confirmado. ### GET /v1/onboarding/links/{id} Quem avisa que o seu cliente terminou é o evento number.connected, entregue no seu endpoint de webhook com o externalId do cliente. Esta leitura é a reserva, para o caso de o seu endpoint ter estado fora do ar, e não um laço de espera: não é preciso consultar de tempos em tempos. Quando o status vira used, usedAt traz o instante e numberId traz o número que resultou. O numberId aparece alguns instantes depois do used, porque a Luna registra o número em seguida; nulo no used significa que a conta foi conectada sem número. Um link que você revogou continua aqui, com status revoked e revokedAt. Quem abre a url dele recebe 404, como se nunca tivesse existido. ### DELETE /v1/onboarding/links/{id} Funciona também em link já usado ou vencido, e aí só o marca como revogado: o número conectado e o externalId dele continuam. O link fica na sua lista com status revoked. Revogar de novo um link já revogado responde 404. ### GET /v1/public/onboarding-links/{token} O token é a credencial, e não há chave de API. Token desconhecido, malformado ou revogado responde 404, sempre igual. Um link vencido ou já usado responde 200 com o status, para a página poder dizer ao cliente que peça um novo. A rota tem teto por endereço de origem. ### POST /v1/public/onboarding-links/{token}/sessions Num link de reconexão (criado com numberId), a sessão já nasce amarrada à conta do número, como em POST /v1/onboarding/reconnect. Pode ser chamada mais de uma vez enquanto o link está aberto: o cliente que fecha a janela da Meta tenta de novo. Link vencido ou já usado responde 410 com o motivo. Qualquer outro token inválido responde 404. A rota tem teto por endereço de origem. ### POST /v1/public/onboarding-links/{token}/sessions/{sessionId}/complete Só conclui uma sessão aberta por este mesmo link. Quando a conexão conclui, o link passa a used, e o externalId dele vai para o número. Se o número escolhido não é +55, o estado é COUNTRY_NOT_SUPPORTED, nada é conectado e o link continua aberto para um número brasileiro. Responde 200 mesmo quando um passo falha: o corpo traz o estado e a orientação. A rota tem teto por endereço de origem. ### POST /v1/public/onboarding-links/{token}/sessions/{sessionId}/abandon Não muda o estado da sessão. A rota tem teto por endereço de origem. --- # Plano e números Fonte: https://lunahia.com.br/docs/plano-e-numeros O plano da Luna define uma coisa só: quantos números a sua conta pode manter ativos ao mesmo tempo. Este guia mostra como ler esse limite, o que fazer quando ele chega, e como abrir uma vaga. ## O teste grátis Toda conta nova começa com um teste grátis de 14 dias, contados da confirmação do e-mail do cadastro, com capacidade para 1 número. Não precisa de liberação manual: depois de confirmar o e-mail, a conta conecta o número sozinha. A Helsen pode bloquear uma conta, e o bloqueio para a escrita e o envio como o fim do teste. A cobrança automática ainda não existe. Para contratar um plano, ampliar a capacidade ou tirar a conta da suspensão, escreva para contato@lunahia.com.br. O uso da plataforma da Meta é pago pelo negócio dono do número, direto à Meta, e não entra em nada disso. Veja [Custos da Meta](https://lunahia.com.br/docs/custos-da-meta). ## Ler o plano e o uso `GET /v1/subscription` devolve o plano da conta e quantos números estão em uso, sem que o seu sistema precise calcular nada. O escopo é `numbers:read`. ```bash curl -X GET "https://api.lunahia.com.br/v1/subscription" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/subscription', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/subscription", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` Uma conta no teste grátis ```json { "planName": "Teste grátis", "status": "trial", "suspendedReason": null, "capacity": 1, "activeNumbers": 1, "canConnectNumber": false, "capacityLeft": 0, "capacityNotice": "Esta conta já tem 1 número ativo, o máximo contratado (1). Para conectar outro, desconecte um número (DELETE /v1/numbers/{id}) ou escreva para contato@lunahia.com.br.", "writesAllowed": true, "suspendedNotice": null, "pricePerMonth": null, "currency": null, "contactEmail": "contato@lunahia.com.br", "trialEndsAt": "2026-11-03T13:00:00.000Z", "trialDaysLeft": 5, "periodo": { "inicio": "2026-10-01T00:00:00.000Z", "fim": "2026-11-01T00:00:00.000Z" }, "numerosAtivos": 1, "phoneNumberIds": ["123456789012345"] } ``` | Campo | O que diz | | --- | --- | | `capacity` | Quantos números a conta pode manter ativos ao mesmo tempo. | | `activeNumbers` | Quantos números estão ativos agora. É a conta que a capacidade usa. | | `status` | `trial` (teste em curso), `active` (conta contratada), `suspended` (escrita e envio pausados) ou `none` (e-mail ainda não confirmado). | | `suspendedReason` | Quando `status` é `suspended`: `trial_expired` (o teste terminou) ou `account_blocked` (a Helsen bloqueou a conta). | | `trialEndsAt` | Quando o teste termina. Fica preenchido depois que a conta é contratada, como registro. | | `trialDaysLeft` | Os dias que faltam para o teste terminar, já calculados pela API. | | `planName` | O nome do plano: Teste grátis durante o teste, e o nome da faixa que comporta a capacidade depois. | | `periodo` | O período corrente, calculado pela API. Mostre-o como veio. | | `canConnectNumber` | Se a conta pode abrir a conexão de um número novo agora: e-mail confirmado, conta não suspensa e vaga na capacidade. É a mesma decisão que a abertura da conexão aplica, então mostre ou esconda o botão por este campo. | | `capacityLeft` | Quantos números ainda cabem na capacidade, nunca negativo. Nulo antes de a conta começar o plano. | | `capacityNotice` | Quando `canConnectNumber` é `false`, o texto da recusa, o mesmo que a API devolve ao tentar conectar. Nulo quando pode conectar. | | `writesAllowed` | `false` só com a conta suspensa. Ler, desconectar número e revogar chave continuam valendo. | | `suspendedNotice` | O texto da suspensão, o mesmo das recusas de escrita. Nulo quando a conta não está suspensa. | | `pricePerMonth` e `currency` | O valor mensal da faixa de capacidade contratada, em reais. A Helsen cobra pela capacidade de números e por mais nada. Nulos no teste grátis e acima da última faixa (Sob consulta). Nunca é zero. | | `contactEmail` | O e-mail do comercial da Helsen, para contratar, ampliar a capacidade ou sair da suspensão. | Quando o seu sistema mostrar uma barra de uso, use `activeNumbers` e `capacity` como vieram. Um número aguardando o pagamento do cliente na Meta continua contando, porque a capacidade é de números configurados, e não de números aptos a enviar agora. ## Quando a capacidade chega Quando `activeNumbers` chega a `capacity`, abrir uma sessão de conexão (`POST /v1/onboarding/sessions`) ou criar um link de conexão (`POST /v1/onboarding/links`) responde `409` com `error: "number_capacity_reached"`. A recusa vem **antes** de o cliente final abrir a tela da Meta, porque o código que a Meta entrega no fim da conexão vale 30 segundos, e a Luna não deixa o seu cliente chegar até ali para recusar depois. Resposta `409` ```json { "error": "number_capacity_reached", "message": "Esta conta já tem 1 número ativo, o máximo contratado (1). Para conectar outro, desconecte um número (DELETE /v1/numbers/{id}) ou escreva para contato@lunahia.com.br.", "capacity": 1, "activeNumbers": 1 } ``` - Reconectar um número que já conta na capacidade **não** é recusado: ele não acrescenta nenhum. - Capacidade menor que o uso nunca desconecta ninguém. Só a próxima conexão é recusada. - Os dois caminhos para seguir são desconectar um número, ou ampliar a capacidade com o comercial. **O link de conexão não reserva vaga.** A checagem acontece quando o link é criado e quando a sessão é aberta, e de novo quando o número é registrado, que é o instante em que ele passa a contar. Se você criar 20 links numa conta com capacidade 5, os cinco primeiros clientes que terminarem ficam com os números; os outros ficam em `connecting`: o link vira `used`, mas o número não conta nem envia, e a Luna tenta de novo de tempos em tempos. Se a capacidade aumentar, eles conectam sozinhos; se as tentativas se esgotarem antes, a sessão termina em `FAILED`. Crie os links na medida em que há vaga em `GET /v1/subscription`, ou amplie a capacidade antes de mandar os links. Para o seu cliente final nunca ficar nessa espera, conte as vagas antes de entregar cada link: `capacityLeft` de `GET /v1/subscription` menos os links de número novo que continuam `open` em `GET /v1/onboarding/links?status=open`. Só entregue o link se sobrar vaga; se não sobrar, amplie a capacidade primeiro. Link de reconexão de um número que já existe não ocupa vaga nova. ## Desconectar um número `DELETE /v1/numbers/{id}` tira o número da Luna e abre uma vaga na hora. O escopo é `numbers:write`. ```bash curl -X DELETE "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status); ``` ```python import os import requests res = requests.delete( "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code) ``` - O número passa para `DISCONNECTED`, não envia mais e deixa de contar na capacidade a partir daquele instante. - O evento `number.disconnected`, com `reason: "requested_by_tenant"`, é entregue aos seus endpoints. Veja [Saúde da conta](https://lunahia.com.br/docs/saude-da-conta). - Se era o último número da Luna naquela conta de negócio, a Luna também remove a inscrição dela na conta, e a Meta deixa de mandar eventos dela. - A Luna **não** desregistra o número na Meta. O número do seu cliente continua funcionando no outro provedor ou no aplicativo do celular dele. - O histórico fica. As mensagens e as conversas continuam em `GET /v1/messages`, e o número continua em `GET /v1/numbers`, com o `externalId` e o `label` dele. - Repetir a chamada é seguro: um número já desconectado responde `204` de novo, sem novo evento. Se a Meta estiver indisponível, a chamada falha sem marcar nada e pode ser repetida. - A rota continua funcionando com o teste terminado, justamente para liberar vaga. ## Voltar a conectar Para voltar a usar um número desconectado, conecte-o de novo pelo mesmo caminho de qualquer número: um link de conexão ou uma sessão. Veja [Conectar um número](https://lunahia.com.br/docs/conectar-numero). Ele volta a contar na capacidade, e a abertura da sessão é recusada com `409 number_capacity_reached` se a conta estiver cheia. ## Dar nome a um número `PATCH /v1/numbers/{id}` troca o `externalId` (o seu identificador para o cliente dono do número) e o `label` (um nome livre e curto, de 1 a 128 caracteres, para você reconhecer o número). Mande só o que quer mudar: um campo ausente fica como está, e `null` limpa o campo. Com `autoRead: true`, a Luna marca como lida, na Meta, cada mensagem que o número receber daqui em diante, sem indicador de digitando, alguns segundos depois de ela chegar; o padrão é `false`, e o campo aparece em `GET /v1/numbers`. O escopo é `numbers:write`, e a resposta é o número inteiro. ```bash curl -X PATCH "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "externalId": "cliente-8841", "label": "Atendimento Pinheiros" }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID', { method: 'PATCH', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "externalId": "cliente-8841", "label": "Atendimento Pinheiros" }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.patch( "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "externalId": "cliente-8841", "label": "Atendimento Pinheiros", }, timeout=10, ) print(res.status_code, res.json()) ``` ## Quando o teste termina Três dias antes do fim, a Luna manda um e-mail ao responsável pela conta. Com o teste terminado e a conta sem contratação, `status` vira `suspended` com `suspendedReason: "trial_expired"`. ### Continua funcionando - Ler os seus dados (`GET`), inclusive mensagens, números e este plano. - Receber o que chega e entregar ao seu webhook. - O número continua conectado na Meta. - Desconectar um número, para liberar vaga. ### Pausa, com `403` - Enviar mensagens e as demais escritas. - Abrir uma sessão de conexão ou criar um link. - Mensagens que já estavam na fila de saída: são recusadas, com o mesmo motivo. Resposta `403` com o teste terminado ```json { "error": "trial_expired", "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br." } ``` Para continuar, escreva para contato@lunahia.com.br. Quando a conta é contratada, a suspensão sai e o envio volta, sem o seu sistema precisar refazer nada. O mesmo corpo de erro, com `account_blocked`, vale para a conta bloqueada pela Helsen. A lista completa de erros está em [Erros](https://lunahia.com.br/docs/erros). > Consulte [a referência da API](https://lunahia.com.br/docs/referencia) para os campos completos de cada rota deste guia. ## Detalhes das rotas deste guia A [referência da API](https://lunahia.com.br/docs/referencia) diz como chamar cada rota, em poucas linhas. O que explica o motivo de cada decisão, os casos de borda e os avisos está aqui, na ordem da referência. ### GET /v1/numbers Dois campos parecidos e diferentes: throughputLevel é VELOCIDADE, quantas mensagens por segundo a Meta processa; limiteDiarioDeConversas é o LIMITE DE MENSAGENS da Meta, do portfólio empresarial (business portfolio) e não de cada número: conta pessoas únicas a quem a empresa escreve fora da janela de atendimento, nas faixas TIER_250, TIER_2K, TIER_10K, TIER_100K e TIER_UNLIMITED. Um não substitui o outro, e nenhum dos dois conta o que já foi usado. throughputLevel descreve uma progressão que a Meta sobe sozinha conforme a qualidade do número. Nem todo número segue essa progressão: um número conectado em coexistência tem teto FIXO, que não sobe nunca. Quem diz qual é o caso é tetoDeVazaoPorSegundo, e ele sai na leitura de um número e na saúde dele, não nesta lista. podeRetentar diz se o estado admite nova tentativa de conexão. A decisão é da plataforma e não sua, porque cada tentativa de registro consome uma cota que a Meta conta por número numa janela de 72 horas. Esgotar essa cota do lado da Meta trava o número até a janela correr. orientacao traz, em português, o que está acontecendo com a conexão e o que fazer a respeito. Ela é escrita para você repassar ao seu cliente sem reescrever. externalId é o rótulo que você deu ao seu cliente no link de conexão. Use ?externalId= para listar só os números dele: a comparação é exata e sensível a maiúsculas, e um rótulo sem número devolve lista vazia. connection é o estado resumido, calculado pela API: status (connected, connecting, action_required ou disconnected), canSend (se enviar vai funcionar agora) e reasons, a lista de motivos com code, message e solution, prontos para você repassar ao seu cliente. É o que você mostra no painel dele em vez de combinar vários campos. ready é o veredito de prontidão: o número está registrado e a inscrição do aplicativo foi confirmada. Para filtrar, use ?state= (o estado do número), ?ready= e ?canSend= (true ou false). Para percorrer páginas, use ?limit= (de 1 a 100, 50 se omitido) e mande de volta o nextCursor da resposta anterior em ?cursor=; nulo significa o fim. O cursor é opaco: ele carrega posição, não contagem. ### GET /v1/numbers/{id} tetoDeVazaoPorSegundo é o campo que distingue teto que sobe de teto que não sobe. throughputLevel descreve a progressão que a Meta concede conforme a qualidade do número, e ela sobe com o tempo. Um número conectado em coexistência, que continua funcionando no aplicativo de celular do negócio, tem teto fixo e não entra nessa progressão. Com valor, este campo diz qual é o teto fixo em mensagens por segundo; nulo, a progressão vale e quem a descreve é throughputLevel. O valor vem do que a plataforma observou no tráfego deste número, e não do rótulo que a Meta devolveu. sincronizacaoDoHistorico conta a importação das conversas anteriores do aparelho, num número conectado em coexistência, e são QUATRO situações e não três. Nulo significa que não há importação para este número. em_curso significa que ela está acontecendo, e sincronizacaoPrazo diz até quando: passado esse instante sem concluir, a plataforma da Meta desconecta o negócio final. concluida significa que terminou, e as conversas antigas já aparecem em GET /v1/messages. recusada significa que o dono do negócio recusou compartilhar no aparelho dele, e aí não vai concluir e pedir de novo não muda isso. Não leia o percentual sozinho. sincronizacaoProgresso é um rótulo que a plataforma da Meta atribui, e cem por cento NÃO significa sucesso: a recusa chega com o progresso que já havia sido registrado. Quem diz o desfecho é sincronizacaoDoHistorico, e só ele. E ausência não é progresso zero: nulo é não haver importação, e zero é uma importação que começou e ainda não andou. Quando a Meta recusa o envio por falta de método de pagamento do negócio final, o número fica registrado e sem enviar. Esse não é um erro da plataforma e não há nada a fazer do lado da Helsen: o campo orientacao diz o que falta e onde resolver, em texto pronto para você repassar ao seu cliente. O campo awaitingPaymentSince traz o instante em que a recusa foi vista e é nulo quando não há espera. A Meta não avisa quando o pagamento é regularizado nem oferece consulta: ele só volta a nulo quando um envio seguinte é aceito. Os eventos number.payment_required e number.payment_resolved avisam as duas passagens. waba traz o estado da conta de negócio do número: restricted e disabled, lidos do último aviso da Meta; credentialExpiresAt e credentialNeverExpires, até quando vale a autorização que o cliente deu à Luna; e paymentMethodOnMeta e currency, a forma de pagamento da conta na Meta (sem ela, a Meta para de entregar mensagens de serviço depois da franquia de 1.000 por número por mês). São da conta, e valem para todos os números dela; os detalhes estão em GET /v1/business-accounts. connection é o estado resumido da conexão: status, canSend e reasons (code, message e solution de cada motivo). É a mesma conta que decide os eventos number.action_required e number.action_resolved. subscriptionConfirmedAt é o campo que mais importa aqui. Ele registra quando a inscrição do aplicativo na conta foi confirmada por leitura de volta. Sem essa inscrição nenhum evento chega, e a falha é silenciosa: o número parece perfeito e não recebe nada. credentialStatus diz se a autorização do cliente continua válida. Quando ela morre, o número precisa ser reconectado. coexistence e ready são booleanos prontos. coexistence é true quando a Luna já observou tráfego de coexistência neste número (a mesma regra do evento number.connected, e ele pode passar de false para true depois da conexão). ready é true quando o número está registrado e a inscrição foi confirmada, ou seja, quando o envio está liberado: use este campo em vez de combinar state e subscriptionConfirmedAt. ### PATCH /v1/numbers/{id} externalId é o seu identificador para o cliente dono do número, de 1 a 128 caracteres. É o fio que amarra o número ao seu cliente: ?externalId= em GET /v1/numbers, o evento number.connected e os que vêm depois trazem o mesmo valor. label é um nome livre e curto, de 1 a 128 caracteres, para você reconhecer o número. A Luna não interpreta nenhum dos dois. Mande só o que quer mudar. Um campo ausente fica como está, e null limpa o campo. O corpo precisa ter pelo menos um dos dois. Repetir o mesmo pedido deixa o mesmo estado. A resposta é o número inteiro, como em GET /v1/numbers/{id}. Número que não é seu responde 404, igual a número que não existe. ### DELETE /v1/numbers/{id} O que acontece: o número passa para o estado DISCONNECTED, não envia mais, e o evento number.disconnected, com reason requested_by_tenant, é entregue aos seus endpoints. Se era o último número da Luna naquela conta de negócio, a Luna também remove a inscrição dela na conta, e a Meta deixa de mandar eventos dela. O que NÃO acontece: a Luna não desregistra o número na Meta. O número do seu cliente continua funcionando no outro provedor ou no aplicativo do celular dele, e continua registrado na Meta. O histórico fica: mensagens e conversas continuam em GET /v1/messages, e o número continua em GET /v1/numbers com o externalId e o label dele. Para voltar a usar o número, conecte-o de novo com um link de conexão (POST /v1/onboarding/links) ou com POST /v1/onboarding/sessions. Isso conta de novo na capacidade, e é recusado com 409 number_capacity_reached se a conta estiver cheia. Repetir a chamada é seguro: um número já desconectado responde 204 de novo, sem novo evento. Se a Meta estiver indisponível, a chamada falha sem marcar nada e pode ser repetida. A rota continua funcionando com o teste grátis terminado, justamente para liberar vaga. Número que não é seu responde 404, igual a número que não existe. --- # Receber eventos Fonte: https://lunahia.com.br/docs/receber-eventos A Luna entrega ao seu servidor tudo que chega nos seus números e toda mudança de estado das mensagens que você enviou. Cada entrega é um `POST` com corpo JSON e uma assinatura que prova a origem. Este guia mostra como receber, verificar e tratar. ## Cadastre o endpoint Pelo console, use **Integração**, **Webhooks**. Pela API, `POST /v1/webhooks/endpoints` com o escopo `webhooks:write`: ```bash curl -X POST "https://api.lunahia.com.br/v1/webhooks/endpoints" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks/luna" }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "url": "https://example.com/webhooks/luna" }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/webhooks/endpoints", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "url": "https://example.com/webhooks/luna", }, timeout=10, ) print(res.status_code, res.json()) ``` Resposta `201` ```json { "id": "5c0e9a52-3a0e-4c3f-9f3e-0b3f6f1a2c77", "url": "https://example.com/webhooks/luna", "createdAt": "2026-10-06T14:00:00.000Z", "updatedAt": "2026-10-06T14:00:00.000Z", "previousSecretExpiresAt": null, "paused": false, "pausedAt": null, "lastDeliveryAt": null, "lastFailureAt": null, "lastHttpStatus": null, "secret": "whsec_EXAMPLE_NOT_A_REAL_SECRET" } ``` - O `secret` aparece nesta resposta e na da rotação, e em mais nenhuma. A Luna guarda só a forma cifrada dele. Se você o perder, rotacione para receber um novo. - A URL precisa usar `https`, sem usuário e senha embutidos, e precisa apontar para um endereço público na internet. - Endereço de rede interna, de laço local e de serviço de metadados de nuvem é recusado no cadastro **e** a cada entrega, porque um nome pode mudar de endereço entre o cadastro e a chamada. - A Luna não segue redirecionamento. Cadastre a URL final. - `GET /v1/webhooks/endpoints` lista o que já existe (escopo `webhooks:read`). Quem ainda não cadastrou nenhum recebe `200` com lista vazia, e não `404`. ```bash curl -X GET "https://api.lunahia.com.br/v1/webhooks/endpoints" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/webhooks/endpoints", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` ## Mude a URL, pause, teste e remova Tudo isso também é possível pelo console, em **Integração**, **Webhooks**. Pela API, as rotas pedem o escopo `webhooks:write`. Endpoint que não é seu responde `404`, igual a endpoint que não existe. - Cada cliente pode ter até **25 endpoints**, e cada evento é entregue a todos os que estiverem ativos e o aceitarem. O cadastro acima do limite responde `409` com `error: "webhook_endpoint_limit"`. O limite é de infraestrutura e é o mesmo para todos, e remover um endpoint libera a vaga. - A representação do endpoint traz o estado: `paused` e `pausedAt`, e o rastro da última entrega, em `lastDeliveryAt` (a última que o seu servidor aceitou), `lastFailureAt` (a última que ele não aceitou) e `lastHttpStatus` (o status da última tentativa, ou `null` se o servidor não respondeu). São instantes e um status, e não um histórico: a Luna não conta entregas. O rastro é gravado no máximo a cada 10 segundos por endpoint. O histórico, tentativa por tentativa, está em `GET /v1/webhooks/endpoints/{id}/deliveries`. - Se o seu servidor está atrás de um gateway que exige um token fixo, cadastre cabeçalhos próprios em `headers`, no `POST` ou no `PATCH`: `{ "headers": { "X-Gateway-Token": "TOKEN" } }`, até **5**. A Luna os envia em toda entrega a esse endpoint, inclusive no evento de teste. O nome é um nome de cabeçalho HTTP válido e não pode ser de transporte (`content-type`, `host`, `content-length` e afins) nem `x-luna-*`; o valor tem até 1024 caracteres ASCII visíveis. Os **valores são segredo**: ficam cifrados e nenhuma resposta os devolve, só os nomes, em `headerNames`. No `PATCH`, o objeto enviado substitui o anterior e `{}` remove todos. A assinatura `X-Luna-Signature`, com carimbo, continua sendo a prova de origem: o cabeçalho próprio é só para passar pelo gateway. - `GET /v1/webhooks/endpoints/{id}/deliveries` lista as tentativas de entrega ao endpoint dos **últimos 7 dias**, da mais recente à mais antiga, uma linha por tentativa: `eventId`, `eventType`, `status` (`success` ou `failed`), `httpStatus` (`null` quando o seu servidor não respondeu), `durationMs`, `attempt` e `at`. Filtros: `status`, `eventType` e `since`. Pagina por `cursor`, sem total. É só metadado: não traz o corpo enviado nem o que o seu servidor respondeu. O console mostra a mesma lista no endpoint, em **Integração**, **Webhooks**. ### Mudar a URL `PATCH /v1/webhooks/endpoints/{id}` com a `url` nova. Ela passa pela mesma validação do cadastro (`https` e endereço público). **O segredo continua o mesmo**: você aponta para outro servidor sem reconfigurar a verificação. Trocar a URL zera `lastDeliveryAt`, `lastFailureAt` e `lastHttpStatus`, porque eles diziam respeito ao servidor antigo. A resposta é o endpoint, como em `GET`. ```bash curl -X PATCH "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks/luna-novo" }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID', { method: 'PATCH', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "url": "https://example.com/webhooks/luna-novo" }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.patch( "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "url": "https://example.com/webhooks/luna-novo", }, timeout=10, ) print(res.status_code, res.json()) ``` ### Pausar e retomar Com `paused: true` o endpoint para de receber. **Os eventos que ocorrerem durante a pausa não são entregues depois**: pausar não adia, descarta. O que já estava na fila para ele também é descartado. Com `paused: false` ele volta a receber o que ocorrer a partir daquele momento. Se você só quer olhar a sua configuração sem perder nada, use o teste abaixo. ```bash curl -X PATCH "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "paused": true }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID', { method: 'PATCH', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "paused": true }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.patch( "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "paused": True, }, timeout=10, ) print(res.status_code, res.json()) ``` ```bash curl -X PATCH "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "paused": false }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID', { method: 'PATCH', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "paused": false }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.patch( "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "paused": False, }, timeout=10, ) print(res.status_code, res.json()) ``` ### Escolher os tipos de evento Por padrão o endpoint recebe **todos** os tipos, inclusive os que a Luna criar depois. Com `eventTypes` você escolhe quais ele recebe, no cadastro (`POST /v1/webhooks/endpoints`) ou depois (`PATCH /v1/webhooks/endpoints/{id}`). A lista enviada **substitui** a anterior, e lista vazia volta a receber todos. O filtro é só por tipo, nunca por conteúdo, conversa ou remetente, e vale daí em diante: o que ocorreu antes e foi filtrado não é entregue depois. A representação do endpoint devolve `eventTypes`, com lista vazia quando ele recebe todos. `GET /v1/webhooks/event-types` lista os tipos que `eventTypes` aceita, cada um com uma frase. ```bash curl -X PATCH "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "eventTypes": [ "message.received", "message.status", "account.restricted", "account.disabled" ] }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID', { method: 'PATCH', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "eventTypes": [ "message.received", "message.status", "account.restricted", "account.disabled" ] }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.patch( "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "eventTypes": [ "message.received", "message.status", "account.restricted", "account.disabled", ], }, timeout=10, ) print(res.status_code, res.json()) ``` Com muitos clientes, o endpoint também pode se limitar a **clientes** e a **números**: `externalIds` (os rótulos que você deu aos clientes) e `phoneNumberIds` (o UUID da Luna ou o id da Meta; a resposta devolve os ids da Meta, os mesmos de `phone_number_id`). Com a lista preenchida, o endpoint só recebe os eventos de números com um destes rótulos ou ids, inclusive os conectados depois (`externalIds`), e os eventos de link dele. Ausentes ou vazios, ele recebe de todos. O filtro vale onde os eventos são publicados, como o de tipos, e um evento que não diz sobre quem fala só chega a endpoint sem filtro. É o jeito de ter uma URL por cliente; o caminho recomendado continua sendo um endpoint só, separando por `number.external_id`. Veja [SaaS com N clientes](https://lunahia.com.br/docs/saas-com-n-clientes). > **Com a lista preenchida, um tipo novo não chega até você incluí-lo.** Quem quer tudo deixa `eventTypes` vazio. `webhook.test` não entra na lista: ele só sai quando você pede o teste. ### Webhook por número (como a “instância” de outras plataformas) Quem vem da Z-API, da Evolution ou da uazapi está acostumado a dar uma URL de webhook a cada instância. Na Luna o número é a instância, e o mesmo `POST /v1/webhooks/endpoints` aceita `phoneNumberIds`: o endpoint recebe só os eventos desses números. Passe o UUID da Luna (o `id` de `GET /v1/numbers`) ou o `metaPhoneNumberId`; um número que não é da conta responde `400`. ```bash curl -X POST "https://api.lunahia.com.br/v1/webhooks/endpoints" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks/numero-1", "phoneNumberIds": [ "YOUR_PHONE_NUMBER_ID" ] }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "url": "https://example.com/webhooks/numero-1", "phoneNumberIds": [ "YOUR_PHONE_NUMBER_ID" ] }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/webhooks/endpoints", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "url": "https://example.com/webhooks/numero-1", "phoneNumberIds": [ "YOUR_PHONE_NUMBER_ID", ], }, timeout=10, ) print(res.status_code, res.json()) ``` Para trocar a URL só desse número depois, altere o endpoint dele com `PATCH /v1/webhooks/endpoints/{id}` e o novo `url` (o `id` está em `GET /v1/webhooks/endpoints`). Os outros endpoints não mudam. Os números que não estão em nenhum filtro continuam chegando só aos endpoints sem filtro. ```bash curl -X PATCH "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks/luna-novo" }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID', { method: 'PATCH', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "url": "https://example.com/webhooks/luna-novo" }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.patch( "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "url": "https://example.com/webhooks/luna-novo", }, timeout=10, ) print(res.status_code, res.json()) ``` Para números que **ainda vão ser conectados**, o id ainda não existe e `phoneNumberIds` não serve. Dê ao cliente um `externalId` (ao criar o link de conexão ou depois, em `PATCH /v1/numbers/{id}`) e cadastre o endpoint com `externalIds`: ele recebe de todo número com esse `externalId`, inclusive os conectados depois. Se as duas listas vierem preenchidas, o número entra no endpoint se bate em qualquer uma. ```bash curl -X POST "https://api.lunahia.com.br/v1/webhooks/endpoints" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks/cliente-42", "externalIds": [ "cliente-42" ] }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "url": "https://example.com/webhooks/cliente-42", "externalIds": [ "cliente-42" ] }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/webhooks/endpoints", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "url": "https://example.com/webhooks/cliente-42", "externalIds": [ "cliente-42", ], }, timeout=10, ) print(res.status_code, res.json()) ``` No console, o mesmo está em **Integração**, **Webhooks** (cada endereço diz a quem atende) e no detalhe de cada número, na seção **Avisos deste número**. ### Enviar um evento de teste `POST /v1/webhooks/endpoints/{id}/test` envia **um** evento `webhook.test` agora, assinado, com os mesmos cabeçalhos, a mesma assinatura e as mesmas defesas de destino de uma entrega real, e devolve o resultado na própria resposta. Funciona com o endpoint pausado, e é para isso: confira antes de retomar. O teste não grava nada no endpoint, então `lastDeliveryAt` continua falando de entregas reais. Para exercitar o seu código com outro tipo, mande `{ "eventType": "number.action_required" }` (qualquer tipo de `GET /v1/webhooks/event-types`): a Luna entrega um exemplo daquele tipo, com corpo de mentira e `test: true` no envelope. Confira esse campo antes de agir sobre o evento: ele nunca vem num evento de verdade. Os eventos simulados do [Modo de teste](https://lunahia.com.br/docs/modo-de-teste) também vêm com `test: true`. `GET /v1/webhooks/endpoints` traz `limit` (o máximo de endpoints), `canCreate` e, em cada endpoint, `deliveryStatus` (`ok`, `failing`, `paused` ou `never_delivered`), e a lista de tipos agrupa cada um em `group` e `groupLabel`. ```bash curl -X POST "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID/test" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID/test', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID/test", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` Resposta `200` ```json { "delivered": true, "statusCode": 200, "durationMs": 184, "failure": null } ``` | Campo | O que é | | --- | --- | | `delivered` | `true` quando o seu servidor respondeu `2xx`, o mesmo critério de uma entrega real. | | `statusCode` | O status que o seu servidor devolveu, ou `null` se não houve resposta. | | `durationMs` | Quanto a chamada levou, em milissegundos. | | `failure` | `null` quando foi entregue. Senão, um destes: `timeout` (o servidor não respondeu a tempo), `connection` (não foi possível conectar: DNS, TLS ou porta fechada), `destination_not_allowed` (a URL deixou de apontar para um endereço público), `response_too_large` (a resposta passou do tamanho que a Luna lê) ou `http_status` (o servidor respondeu fora de `2xx`, inclusive redirecionamento, que a Luna não segue). | O corpo que o seu servidor respondeu não volta, de propósito. O limite é de **5 testes por minuto por cliente**, igual para todos, porque cada chamada é uma requisição de saída para o seu servidor. Acima disso, `429` com `Retry-After`. ### Remover `DELETE /v1/webhooks/endpoints/{id}` responde `204`, e o endpoint deixa de receber. Os eventos que já estavam na fila para ele são descartados quando chegam, e não reentregues. Os itens da fila de rejeitados que apontavam para ele são apagados junto, porque sem endpoint não há para onde re-enfileirá-los. **Isso não tem volta**, e o segredo também se perde. Para parar de receber sem perder nada, pause. ```bash curl -X DELETE "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status); ``` ```python import os import requests res = requests.delete( "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code) ``` ### Desenvolver na sua máquina A Luna só aceita uma URL `https` pública, então `http://localhost:3000` é recusado. Para desenvolver na sua máquina, exponha o seu servidor local por um túnel https (qualquer serviço de túnel serve), cadastre a URL pública que ele der e use `PATCH` para trocar a URL quando o túnel mudar. O segredo continua o mesmo. Para parar de receber enquanto o túnel está fechado, pause o endpoint. ## Como a Luna entrega - Cada entrega é um `POST` na sua URL, com `Content-Type: application/json` e o cabeçalho `X-Luna-Signature`. - Qualquer resposta `2xx` conta como entregue. A Luna espera até **10 segundos** pela resposta. - Qualquer outra coisa conta como falha: `4xx`, `5xx`, redirecionamento `3xx`, tempo esgotado e erro de conexão. - O corpo da sua resposta é descartado. Um corpo acima de 64 KB conta como falha, então responda vazio. - Responda primeiro e trabalhe depois. Se o seu tratamento é lento, grave o evento numa fila sua e devolva `2xx` na hora. ## As garantias de entrega Elas estão escritas sem eufemismo, porque quem paga uma duplicata é o consumidor final do seu produto: - A entrega é at-least-once: a mesma entrega pode chegar mais de uma vez, e isso acontece de verdade, não apenas em teoria. Um tempo limite atingido depois de o seu servidor já ter processado a requisição produz exatamente esse caso. - A ordem é garantida dentro de uma conversa, e os eventos template.status são ordenados entre si por conta de negócio, já que um template não pertence a conversa nenhuma, os eventos template.category e template.quality entram nessa mesma ordem, e os eventos de número e de conta (number.* e account.*) são ordenados entre si por número. Ela não é garantida entre conversas: dois eventos de conversas diferentes podem chegar em qualquer ordem, e um evento de uma conversa lenta pode chegar depois de um evento mais recente de outra. - A idempotência é dever seu, e o event_id é o que a plataforma dá para você cumpri-la. Ele é estável: a mesma entrega, repetida, traz o mesmo event_id. Guarde os que já processou e descarte os repetidos. - Se o seu endpoint ficar fora do ar por muito tempo, a plataforma descarta o que ficou acumulado, e você perde esses eventos: eles não serão reenviados. Quando isso acontecer, você recebe um evento backlog.dropped dizendo quantos foram descartados e de que período. Esse aviso não é descartado junto com o acumulado que ele descreve. - Novos tipos de evento podem aparecer sem que a versão do contrato mude. Se o seu servidor receber um event_type que não conhece, responda 2xx e ignore o evento. A versão só muda quando a forma de um tipo que já existe muda, e isso vem com aviso e prazo. - Num número conectado em coexistência, se a importação das conversas anteriores ainda estiver em curso quando o prazo dela se aproxima, você recebe um evento history_sync.deadline_approaching com o número e o prazo como instante. Esse prazo é a estimativa da plataforma: 24 horas contadas de quando ela viu a importação começar. O relógio da Meta começa um pouco antes, então trate o instante como limite e aja com folga. Passado o prazo sem concluir, a plataforma da Meta desconecta o negócio final e ele precisa refazer a conexão no aparelho. O aviso sai antes do prazo e nunca depois, e é um só para o número: como toda entrega, ele pode se repetir, sempre com o mesmo event_id, e um número que refaz a conexão depois não recebe um segundo aviso. O estado corrente da importação está em GET /v1/numbers/{id}/health. ## Os eventos Todo evento tem o mesmo envelope, e o `event_type` diz qual é o tipo. Os exemplos abaixo são construídos do contrato publicado: | Campo | O que é | | --- | --- | | `version` | A versão do contrato, uma data (hoje `2026-11-10`). Ela só muda quando a forma de um tipo que já existe muda, e isso vem com aviso e prazo. Um tipo novo de evento não a faz subir. A de `2026-10-28` acrescentou o objeto `number` a todo evento, explicado abaixo, e a de `2026-11-04` acrescentou `unsupported`, `edit`, `revoke` e `order` ao conteúdo de `message.received` e `message.echo`; quem lê o JSON ignorando os campos que não conhece não precisa mudar nada. | | `event_id` | O identificador estável do evento, 64 caracteres hexadecimais. A mesma entrega, repetida, traz o mesmo `event_id`. Use-o para descartar repetições. | | `event_type` | `message.received`, `message.status`, `message.echo`, `contact.identity_changed`, `contact.preferences_changed`, `backlog.dropped`, `history_sync.deadline_approaching`, `template.status`, `template.category`, `template.quality`, `number.connected`, `number.disconnected`, `number.quality_changed`, `number.display_name_reviewed`, `number.credential_expiring`, `number.payment_required`, `number.payment_resolved`, `number.action_required`, `number.action_resolved`, `onboarding.link.opened`, `onboarding.link.completed`, `onboarding.link.failed`, `onboarding.link.expired`, `account.restricted`, `account.violation`, `account.disabled`, `account.reinstated`, `account.update`, `account.limit_changed`, `account.alert` ou `webhook.test`. | | `occurred_at` | Quando o evento ocorreu, em ISO 8601, UTC, com milissegundos e o `Z` no fim. | | `phone_number_id` | O identificador do número na Meta, o mesmo `metaPhoneNumberId` que `GET /v1/numbers` devolve. É `null` em `webhook.test`, que não passa por número nenhum, e nos eventos de template, porque o template é da conta de negócio. | | `number` | O número por onde o evento passou: `id` (o da Luna, o mesmo de `GET /v1/numbers`), `phone_number_id` (o da Meta) e `external_id` (o rótulo que você deu ao seu cliente, ou `null`). Está em todo evento que passa por um número, e é `null` em `webhook.test` e nos eventos de template. Nos eventos `number.*` o mesmo objeto traz também os campos próprios do evento. | ### Separar os eventos de cada cliente seu Com muitos clientes, o caminho recomendado é **um endpoint só** para todos. Cada evento já diz de quem é: `number.external_id` é o rótulo que você deu ao cliente ao criar o link de conexão (ou em `PATCH /v1/numbers/{id}`), e `number.id` e `number.phone_number_id` são os dois identificadores do número. O seu servidor lê `external_id`, acha o cliente e entrega ao código dele. O `external_id` é `null` num número que nunca recebeu rótulo; dê um com `PATCH /v1/numbers/{id}`. Roteando por external_id (Node) ```js // external_id -> the function that handles that customer const handlers = new Map(); function handle(event) { const customer = event.number?.external_id; const handler = customer ? handlers.get(customer) : undefined; // no label, or an event you do not handle: answer 2xx and ignore if (!handler) return; handler(event); } ``` ### `message.received` Uma mensagem que chegou de um interlocutor, **completa**: o texto, e também o botão que ele tocou, a mídia com a legenda, a localização, os contatos, a reação, a resposta de um Flow, o pedido de um catálogo, a edição ou o apagamento de uma mensagem, o aviso de um tipo que a Cloud API não entrega, a mensagem que ele citou, o anúncio de onde veio e o nome que ele exibe. Todo campo está sempre presente, e é nulo quando não se aplica ao tipo. Texto ```json { "version": "2026-11-10", "event_id": "a2f4909b0fd2db8ab8b1bfe4e16487f49b86113e27bf8c3c9d10a2d0fefebc72", "event_type": "message.received", "occurred_at": "2026-10-06T14:02:11.482Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "message": { "id": "b6d84033-a8e8-4db9-aab6-565ce203cc51", "wamid": "wamid.EXAMPLE_NOT_A_REAL_ID", "wa_id": "5511900000000", "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": null, "type": "text", "text": "Oi! Queria saber o status do meu pedido.", "profile_name": "Maria Souza", "media": null, "interactive": null, "button": null, "location": null, "contacts": null, "reaction": null, "context": null, "referral": null, "unsupported": null, "edit": null, "revoke": null, "order": null } } ``` O clique num botão de resposta de uma mensagem que você enviou. O `id` que você deu ao botão volta em `message.interactive.id`, e `message.context.wamid` é a mensagem que tinha os botões. O `text` fica nulo: o título do botão está em `interactive.title`. Clique em botão ```json { "version": "2026-11-10", "event_id": "1fd66b6f86489c36c3552f14dbf49f50df6b2d946c259f7b0eaa0ef88f58adb5", "event_type": "message.received", "occurred_at": "2026-10-06T14:05:40.120Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "message": { "id": "7d1c4b8e-2a3f-4e5d-9c6b-1f0a2b3c4d5e", "wamid": "wamid.EXAMPLE_BUTTON_CLICK", "wa_id": "5511900000000", "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": null, "type": "interactive", "text": null, "profile_name": "Maria Souza", "media": null, "interactive": { "type": "button_reply", "id": "rastrear", "title": "Rastrear pedido", "description": null, "name": null, "response_json": null }, "button": null, "location": null, "contacts": null, "reaction": null, "context": { "wamid": "wamid.EXAMPLE_MESSAGE_WITH_BUTTONS", "from": "5511900000001", "forwarded": null, "frequently_forwarded": null }, "referral": null, "unsupported": null, "edit": null, "revoke": null, "order": null } } ``` Uma imagem com legenda. A legenda fica em `message.media.caption`, e não em `text`, para você não tratá-la como mensagem de texto. O arquivo sai pelo link em `message.media.url`, que baixa **sem chave de API** (veja [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens#midia)), ou por `GET /v1/messages/{id}/media`, com chave e o `message.id` do evento. Imagem com legenda ```json { "version": "2026-11-10", "event_id": "0ab56cecd18b825ebeb4548219cb8fe392fec9e56301e52be1086f3c734ace86", "event_type": "message.received", "occurred_at": "2026-10-06T14:07:03.900Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "message": { "id": "4c9e2d1a-8b7f-4a6c-b5d3-0e1f2a3b4c5d", "wamid": "wamid.EXAMPLE_IMAGE", "wa_id": "5511900000000", "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": null, "type": "image", "text": null, "profile_name": "Maria Souza", "media": { "mime_type": "image/jpeg", "sha256": "EXAMPLE_SHA256_OF_THE_FILE", "caption": "A nota fiscal do pedido", "filename": null, "voice": null, "animated": null, "url": "https://api.lunahia.com.br/v1/media/6f1a2b3c-4d5e-4f60-8a7b-9c0d1e2f3a4b.EXEMPLO_DO_SEGREDO_DE_43_CARACTERES_AAAAAAAA" }, "interactive": null, "button": null, "location": null, "contacts": null, "reaction": null, "context": null, "referral": null, "unsupported": null, "edit": null, "revoke": null, "order": null } } ``` Quem adotou um nome de usuário no WhatsApp pode escrever **sem que o telefone apareça**. Nesse caso `message.wa_id` vem **nulo** e o interlocutor é `message.user_id`, o BSUID. Trate `wa_id` como opcional e `user_id` como a chave do contato quando o telefone faltar. O guia [Usuários sem telefone (BSUID)](https://lunahia.com.br/docs/usuarios-sem-telefone) explica o que muda no seu sistema. Sem telefone (só BSUID) ```json { "version": "2026-11-10", "event_id": "e2f81dd079e4419dac363779655be694a25cc502b7646be51cdac4b0cfc276fb", "event_type": "message.received", "occurred_at": "2026-11-03T14:02:11.482Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "message": { "id": "c8a1e5d2-6f3b-4a7c-9e0d-1b2c3d4e5f60", "wamid": "wamid.EXAMPLE_NO_PHONE", "wa_id": null, "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": "mariasouza", "type": "text", "text": "Oi! Queria saber o status do meu pedido.", "profile_name": "Maria Souza", "media": null, "interactive": null, "button": null, "location": null, "contacts": null, "reaction": null, "context": null, "referral": null, "unsupported": null, "edit": null, "revoke": null, "order": null } } ``` A resposta de um Flow que você enviou chega como `interactive` com `type: "nfm_reply"`. As respostas ficam em `message.interactive.response_json`, **como texto JSON, sem interpretar**: faça o `JSON.parse` do seu lado, e use o `flow_token` que você mandou para saber de qual envio ela é. Resposta de um Flow ```json { "version": "2026-11-10", "event_id": "b9714a025db0a22bd3a63f9dfd9aa52aed7ddcae4efde825dfb2fa41e1736dd2", "event_type": "message.received", "occurred_at": "2026-11-04T14:12:30.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "message": { "id": "a4b9d2e3-6c7f-4081-9bac-1d2e3f4a5b6c", "wamid": "wamid.EXAMPLE_FLOW_REPLY", "wa_id": "5511900000000", "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": null, "type": "interactive", "text": null, "profile_name": "Maria Souza", "media": null, "interactive": { "type": "nfm_reply", "id": null, "title": null, "description": null, "name": "flow", "response_json": "{\"flow_token\":\"EXAMPLE_FLOW_TOKEN\",\"nome\":\"Maria Souza\",\"data\":\"2026-11-10\"}" }, "button": null, "location": null, "contacts": null, "reaction": null, "context": null, "referral": null, "unsupported": null, "edit": null, "revoke": null, "order": null } } ``` Um pedido montado num catálogo chega com `type: "order"` e os itens em `message.order.items`. Quantidade e preço saem como texto, do jeito que a Meta mandou. A Luna só entrega o pedido: não cobra, não calcula total e não mexe no dinheiro. Pedido de catálogo ```json { "version": "2026-11-10", "event_id": "1eaa360e693d1a7366e66ba81d7bee362a56c2b4f4ef4854e43ad35861bd7ae1", "event_type": "message.received", "occurred_at": "2026-11-04T14:10:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "message": { "id": "f3a8c1d2-5b6e-4f70-8a9b-0c1d2e3f4a5b", "wamid": "wamid.EXAMPLE_ORDER", "wa_id": "5511900000000", "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": null, "type": "order", "text": null, "profile_name": "Maria Souza", "media": null, "interactive": null, "button": null, "location": null, "contacts": null, "reaction": null, "context": null, "referral": null, "unsupported": null, "edit": null, "revoke": null, "order": { "catalog_id": "EXAMPLE_CATALOG_ID", "text": "Quero estes dois, por favor.", "items": [ { "product_retailer_id": "sku-001", "quantity": "2", "item_price": "49.90", "currency": "BRL" }, { "product_retailer_id": "sku-002", "quantity": "1", "item_price": "15.00", "currency": "BRL" } ] } } } ``` | Campo de `message` | O que é | | --- | --- | | `id` | O identificador da mensagem na Luna, um UUID. É o `id` que `GET /v1/messages/{id}/media`, `POST /v1/messages/{id}/read`, `POST /v1/messages/{id}/typing` e `POST /v1/messages/{id}/replay` pedem. | | `wamid` | O identificador da mensagem na Meta. | | `wa_id` | O telefone do interlocutor na Meta, em E.164 sem o sinal de mais. **Pode ser nulo**: quando o usuário escreveu sem que o telefone apareça, use `user_id`. | | `user_id` | O BSUID do interlocutor, como a Meta o mandou (por exemplo `US.13491208655302741918`). Nulo quando a Meta ainda não o mandou para esta conversa. | | `parent_user_id` | O BSUID pai, só quando a Meta o manda (`US.ENT.…`). Nulo no demais. | | `username` | O nome de usuário, só quando o interlocutor adotou um. Nulo no demais. | | `type` | O tipo da mensagem, no vocabulário da Meta. | | `text` | O texto, quando o tipo é texto. Nulo nos demais tipos. | | `profile_name` | O nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou. | | `media` | Imagem, vídeo, áudio, documento ou figurinha: `mime_type`, `sha256`, `caption`, `filename` (só documento), `voice` (só áudio) e `animated` (só figurinha). O `type` diz qual é. O identificador e a URL da Meta não vêm, porque você não tem o token que os abre. | | `interactive` | A escolha feita numa mensagem interativa: `type` (`button_reply`, `list_reply` ou `nfm_reply`), `id` e `title` do botão ou do item, `description` do item da lista, e, na resposta de um Flow, `name` e `response_json` (o texto JSON que a Meta mandou, sem interpretar). | | `button` | O clique num botão de resposta rápida de um template: `payload` e `text`. | | `location` | A localização compartilhada: `latitude`, `longitude`, `name`, `address` e `url`. | | `contacts` | Os cartões de contato compartilhados, uma lista. Cada um traz `name`, `phones`, `emails` e `org`. | | `reaction` | A reação: `wamid` da mensagem que a recebeu, e `emoji`. O `emoji` é nulo quando a reação foi retirada. | | `context` | A mensagem que o interlocutor citou ao responder (`wamid`, `from`), e se ela foi encaminhada (`forwarded`, `frequently_forwarded`). | | `referral` | O anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever: `source_type`, `source_id`, `source_url`, `headline`, `body`, `media_type` e `ctwa_clid`. | | `unsupported` | Presente quando o `type` é `unsupported`: o interlocutor mandou algo que a Cloud API não entrega. Traz `code`, `title` e `details`, como a Meta mandou (o código `131051` é "tipo de mensagem sem suporte"). Não há conteúdo a ler: use o aviso para o seu agente responder que não consegue ver aquilo. | | `edit` | Presente quando o `type` é `edit`: o interlocutor editou uma mensagem. Traz o `wamid` da mensagem editada e, quando o conteúdo novo é texto, `type` e `text`. **A forma exata do aviso de edição está a confirmar na documentação da Meta**: se um campo vier nulo, o envelope bruto guardou o resto. | | `revoke` | Presente quando o `type` é `revoke`: o interlocutor apagou uma mensagem para todos. Traz o `wamid` da mensagem apagada. **A forma exata está a confirmar na documentação da Meta**, como na edição. A Luna não apaga nada do que já guardou: quem decide o que fazer com a mensagem apagada é você. | | `order` | O pedido montado num catálogo: `catalog_id`, `text` e `items`, cada item com `product_retailer_id`, `quantity`, `item_price` e `currency`, como a Meta mandou. | - Os nomes dentro desses campos são os da Meta. Quem já leu a documentação da Cloud API reconhece `interactive.id`, `location.latitude` e `context`. - O `id` do evento é o que você passa às rotas. Para ler a mensagem, `GET /v1/messages/{id}`. Para achá-la a partir de um `wamid` que você já guardou, `GET /v1/messages?wamid=...`. - A mesma forma sai em `content`, em `GET /v1/messages` e em `GET /v1/messages/{id}`, com os mesmos nomes. Ali ela é nula em mensagem que você enviou. - Para baixar uma mídia, faça `GET` no link de `message.media.url`, sem chave: o link vale 30 dias, é o mesmo em toda reentrega do aviso e é dado sensível (não o registre em log). `url` é nula quando a mensagem não tem mídia que a Luna consiga obter. Se a Luna ainda estiver baixando o arquivo da Meta, a resposta é `409` com `Retry-After`: tente de novo. Com chave, `GET /v1/messages/{id}/media` com o `message.id` continua valendo. Veja [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens#midia). ### `message.status` Uma mudança de estado de uma mensagem que você enviou. Cada estado é um evento, com o seu próprio `event_id`. Enviada ```json { "version": "2026-11-10", "event_id": "464e089a80690f1792db6249678ddeced5ad5be0d46d95e2daa263779f7d92e5", "event_type": "message.status", "occurred_at": "2026-10-06T14:02:14.090Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "message": { "id": "ae60f288-7565-4315-a440-3663e9c231e1", "wamid": "wamid.EXAMPLE_NOT_A_REAL_ID", "wa_id": "5511900000000", "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": null, "status": "sent", "error_code": null, "error": null, "pricing": { "billable": false, "pricing_model": "PMP", "type": "free_customer_service", "category": "service" }, "callback_data": "atendimento-8841" } } ``` Falha ```json { "version": "2026-11-10", "event_id": "6a79ec64bfea6acc67135d032067fd6261aa568c3aea35af7999790a7730cf69", "event_type": "message.status", "occurred_at": "2026-10-06T14:02:15.311Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "message": { "id": "ae60f288-7565-4315-a440-3663e9c231e1", "wamid": "wamid.EXAMPLE_NOT_A_REAL_ID", "wa_id": "5511900000000", "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": null, "status": "failed", "error_code": 131026, "error": { "code": 131026, "title": "Message undeliverable", "message": "Message undeliverable" }, "pricing": null, "callback_data": null } } ``` | Campo de `message` | O que é | | --- | --- | | `id` | O identificador da mensagem na Luna, o mesmo que `POST /v1/messages` devolveu quando você a enviou. Nulo quando o status é de uma mensagem que a Luna não conhece. | | `wamid` | O identificador da mensagem na Meta. Nulo quando a Meta recusou o envio antes de aceitar a mensagem: ela nunca teve identificador, e o `id` é a chave. | | `wa_id` | O telefone do interlocutor na Meta. Nulo quando a conversa é só de BSUID: use `user_id`. | | `user_id`, `parent_user_id`, `username` | O BSUID do interlocutor, o BSUID pai e o nome de usuário, como em `message.received`. Todos sempre presentes, e nulos quando não se aplicam. | | `status` | O estado, no vocabulário da Meta: `sent`, `delivered`, `read`, `played` ou `failed`, e `canceled`, que é da Luna e sai quando você cancela uma mensagem na fila com `DELETE /v1/messages/{id}` (a Meta nunca a recebeu, e `wamid` e `error` vêm nulos). Novos estados podem aparecer, e quem não conhece um valor deve ignorar o evento. | | `error_code` | O código de erro da Meta quando o estado é de falha. Nulo nos demais. | | `error` | O primeiro erro que a Meta informou, com `code`, `title` e `message`, quando o estado é de falha. Nulo nos demais. O motivo em português e a ação recomendada estão em `GET /v1/messages/{id}`. | | `pricing` | O custo que a Meta aplicou à mensagem, com os nomes dela: `billable`, `pricing_model`, `type` e `category`. A Meta o informa só em `sent` e em um entre `delivered` e `read`, então nos outros estados vem nulo. Os valores de `type` e `category` são os da Meta e podem ganhar valores novos: não trate como lista fechada. É a classificação para você exibir, não a fatura. Veja [Custos da Meta](https://lunahia.com.br/docs/custos-da-meta#conferir). | | `callback_data` | A etiqueta que você mandou em `callbackData` ao enviar a mensagem, devolvida como veio, em todos os estados (inclusive `failed`). Nulo quando o envio não trouxe etiqueta. Veja [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens). | - A Meta não emite `delivered` quando a entrega e a leitura coincidem. `sent` seguido direto de `read` é uma sequência válida, e não um evento perdido. - O `id` liga o evento à mensagem que você enviou: é o mesmo que `POST /v1/messages` devolveu, e vale em `GET /v1/messages/{id}`. O `wamid` continua no evento para quem prefere a Meta como chave, e `GET /v1/messages?wamid=...` o encontra. Use o `id` como chave, porque o `wamid` é nulo quando a Meta recusa o envio. - A falha chega como `message.status` com `status: "failed"` por dois caminhos. A Meta pode aceitar a mensagem e informar a falha depois, e então o `wamid` vem preenchido. Ou ela pode recusar o envio na própria resposta (token revogado, número sem WhatsApp, parâmetro de template errado, método de pagamento): a Luna dá a mensagem por falhada na hora, não tenta de novo, e você recebe o mesmo evento, com `wamid` nulo e o `error` da Meta. Uma falha passageira da Meta, como um tempo esgotado, não é falha: a Luna tenta de novo sozinha e você não recebe `failed`. - Para o motivo de uma falha, em português e com a ação recomendada, leia `GET /v1/messages/{id}`. Veja [Erros](https://lunahia.com.br/docs/erros#envio). ### `message.echo` O dono do negócio respondeu a um cliente pelo aplicativo WhatsApp Business do celular. **Só ocorre em número conectado em coexistência.** A forma é a de `message.received`, com uma diferença que importa: `message.wa_id` é o **destinatário**, o cliente para quem o dono escreveu, e não quem escreveu. Quando a conversa é só de BSUID, `wa_id` é nulo e o destinatário é `message.user_id`. ```json { "version": "2026-11-10", "event_id": "01b53d46e858f6ab6c89e183ef9509d703f665f6cfe2eb1d6bb185df56224d88", "event_type": "message.echo", "occurred_at": "2026-10-07T13:02:30.250Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "message": { "id": "9a3e6b14-5c2d-4f81-b7a0-2d8e1c4f6a93", "wamid": "wamid.EXAMPLE_ECHO", "wa_id": "5511900000000", "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": null, "type": "text", "text": "Oi, Maria! Já separei o seu pedido, sai hoje.", "profile_name": null, "media": null, "interactive": null, "button": null, "location": null, "contacts": null, "reaction": null, "context": null, "referral": null, "unsupported": null, "edit": null, "revoke": null, "order": null } } ``` > **Este é o sinal para o seu agente ficar quieto.** Quando um humano respondeu, pause o seu agente para aquela conversa (a chave é `phone_number_id` mais `message.wa_id`) e só o retome pela regra que você definir, por exemplo depois de um intervalo sem resposta humana. Sem isso, o agente responde por cima do dono do negócio. Revogação e edição de mensagem feitas no celular não geram este evento. ### `contact.identity_changed` O contato trocou de telefone (`user_changed_number`) ou de BSUID (`user_changed_user_id`). A Luna liga a identidade nova à **mesma conversa**, sem mover o histórico, e avisa o seu sistema, que é quem guarda o contato do seu lado. Use `previous_user_id` e `user_id` para atualizar o cadastro. `wa_id`, `previous_user_id` e os dois BSUIDs pai podem vir nulos, e os valores chegam como a Meta mandou. É uma mensagem de sistema da Meta: ela não é `message.received` e não abre a janela de atendimento. ```json { "version": "2026-11-10", "event_id": "f73a65b1f155f86f94e0886ad29bac662a822fabf796b626cdf865c7060f0db9", "event_type": "contact.identity_changed", "occurred_at": "2026-11-03T15:20:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "contact": { "wamid": "wamid.EXAMPLE_IDENTITY_CHANGE", "change_type": "user_changed_user_id", "wa_id": null, "user_id": "BR.98765432109876543210", "previous_user_id": "BR.13491208655302741918", "parent_user_id": null, "previous_parent_user_id": null } } ``` ### `contact.preferences_changed` O contato mudou uma preferência na Meta, hoje a de receber mensagens de marketing: pediu para parar (por exemplo `preference.value` igual a `stop`) ou voltou a aceitar. `preference.category`, `preference.value` e `preference.detail` chegam **como a Meta mandou**, sem lista fechada, e qualquer um pode vir nulo. **A Luna não bloqueia nenhum envio por causa do aviso**: o seu sistema decide, e deve parar de mandar marketing a quem pediu. O evento sai no mesmo grupo de ordem da conversa do contato. > **Só chega se o campo `user_preferences` estiver assinado no app da Meta**, e essa assinatura é feita no painel da Meta, uma vez, por quem administra o app. A forma exata do corpo que a Meta manda nesse campo está a confirmar na documentação dela: a Luna lê com tolerância, e o que a Meta mandar além do que está aqui fica no envelope bruto por 7 dias. Sem nenhum identificador do usuário no aviso (nem `wa_id` nem `user_id`), não há evento. ```json { "version": "2026-11-10", "event_id": "4236ccfb21e7cec359d1e1b5b5f3f8e65cb3e8a8db0fc86e4d95da037796e97c", "event_type": "contact.preferences_changed", "occurred_at": "2026-11-04T16:45:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "contact": { "wa_id": "5511900000000", "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": null, "profile_name": "Maria Souza" }, "preference": { "category": "marketing_messages", "value": "stop", "detail": "User requested to stop marketing messages" } } ``` ### `backlog.dropped` A plataforma descartou eventos do acumulado do seu endpoint e **não os reenviará**. É o aviso, e ele não é descartado junto com o que descreve. ```json { "version": "2026-11-10", "event_id": "f76937420c2e818b87ce9b6acc5cb192c059ed2e33cda23339d5cf650b762ce5", "event_type": "backlog.dropped", "occurred_at": "2026-10-06T14:30:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "backlog": { "motivo": "idade", "quantidade": 37, "janela_inicio": "2026-10-06T09:00:00.000Z", "janela_fim": "2026-10-06T14:30:00.000Z" } } ``` | Campo de `backlog` | O que é | | --- | --- | | `motivo` | `idade`, quando as mensagens ficaram velhas demais para serem acionáveis. `volume`, quando o acumulado do endpoint passou do teto da plataforma. | | `quantidade` | Quantos eventos foram descartados nesta ocorrência. | | `janela_inicio` | O evento mais antigo descartado. | | `janela_fim` | O evento mais recente descartado. | Quando isso acontece, reconcilie pelo histórico: `GET /v1/messages` traz o que entrou e saiu, do mais recente ao mais antigo. ### `history_sync.deadline_approaching` O aviso da importação do histórico de um número em coexistência. O objeto traz o prazo e mais nada. Veja [Conectar um número](https://lunahia.com.br/docs/conectar-numero#coexistencia). ```json { "version": "2026-11-10", "event_id": "d42ca56e44ef023d52b0a0739dcf3afb0d5054a8b84321c41e432ed6707b043f", "event_type": "history_sync.deadline_approaching", "occurred_at": "2026-10-07T03:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "history_sync": { "prazo": "2026-10-07T09:00:00.000Z" } } ``` ### `template.status` A Meta aprovou, rejeitou, pausou ou desativou um template. Não tem número nem conversa (`phone_number_id` é `null`): o template é da conta de negócio. Os eventos de template são ordenados entre si por conta de negócio. Em `template`, `external_id` é o rótulo do cliente dono do template: o `externalId` dos números da conta quando todos eles têm o mesmo, e `null` quando a conta tem números de clientes diferentes, quando algum número não tem rótulo e quando ela não tem número conectado (nesses casos ligue o evento ao cliente por `waba_id`; `template.category` e `template.quality` trazem o mesmo campo). Também em `template`, `id` é o identificador da Luna, o mesmo de `GET /v1/templates`, `waba_id` é a conta de negócio do template (o `wabaId` da mesma rota, para ligar o evento a um cliente seu sem ler outra rota) e `reason` é o motivo que a Meta informou para a rejeição ou a pausa, ou `null` quando ela não informa (as aprovações vêm sem motivo). `status` é o texto da Meta, e valores novos podem aparecer. ```json { "version": "2026-11-10", "event_id": "821d41ec2c33a28abe8a0baf97db034baaef1dbe511a6e546a37eca4ad565c65", "event_type": "template.status", "occurred_at": "2026-10-07T13:20:00.000Z", "phone_number_id": null, "number": null, "template": { "id": "3f6a1c52-9d4e-4b87-a1f0-5e2c7b9d8a14", "name": "confirmacao_de_pedido", "language": "pt_BR", "waba_id": "102290129340398", "external_id": "cliente-8841", "status": "REJECTED", "category": "UTILITY", "reason": "INVALID_FORMAT" } } ``` ### `number.connected` Um número terminou de ser conectado e está registrado na Cloud API. É o sinal de que o seu cliente concluiu a conexão que você abriu com [o link de conexão](https://lunahia.com.br/docs/conectar-numero): você não precisa consultar `GET /v1/numbers` de tempos em tempos. `number.external_id` é o rótulo que você deu ao cliente ao criar o link, e `number.id` é o identificador da Luna do número, e `number.waba_id` é a conta de negócio dele (o `waba.id` de `GET /v1/numbers`). `number.coexistence` é `true` quando a Luna já observou tráfego de coexistência nele, e pode ser `false` no instante da conexão e mudar depois: o valor corrente está no campo `coexistence` de `GET /v1/numbers/{id}`. Para saber se o envio já está liberado, leia o campo `ready` da mesma rota. ```json { "version": "2026-11-10", "event_id": "458470a340db14358f03ac02fde7e3839cb6887f3071c06c57a3d9d456621996", "event_type": "number.connected", "occurred_at": "2026-10-07T13:45:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "waba_id": "102290129340398", "coexistence": false } } ``` > O aviso é feito uma vez por número, e só para quem tem um endpoint ativo. Se o seu endpoint ainda não existia, ou estava pausado, quando o número ficou pronto, você o recebe se cadastrar ou retomar o endpoint dentro de 24 horas; passado esse prazo ele nunca é enviado, e `GET /v1/numbers` continua sendo a fonte da verdade. ### `number.payment_required` e `number.payment_resolved` O pagamento do número na Meta, nas duas passagens. `number.payment_required` sai quando a Meta recusa um envio por falta de método de pagamento do negócio dono da conta (erro `131042`) e o número entra na espera. `number.payment_resolved` sai quando um envio volta a ser aceito. Sai **uma vez por passagem**, e não a cada mensagem recusada: as mensagens recusadas chegam como `message.status` com `status: "failed"`. Em `number`, `id` é o identificador da Luna, `external_id` é o rótulo que você deu ao cliente, e `awaiting_payment_since` (só em `number.payment_required`) é o mesmo valor de `awaitingPaymentSince` em `GET /v1/numbers/{id}`. O guia [Pagamento na Meta](https://lunahia.com.br/docs/pagamento-na-meta) explica o que fazer e o que dizer ao seu cliente. Entrou na espera ```json { "version": "2026-11-10", "event_id": "50a49cee4b216c529e3f7cdd0be525f8902ff6aff66439e004dfe34a0c979fcf", "event_type": "number.payment_required", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "awaiting_payment_since": "2026-10-13T12:00:00.000Z" } } ``` Voltou a enviar ```json { "version": "2026-11-10", "event_id": "6a956161dd17bb975533e63286e811ae62b77b3350107945952b2e53f0a9d1e2", "event_type": "number.payment_resolved", "occurred_at": "2026-10-13T15:30:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841" } } ``` ### `number.display_name_reviewed` O nome de exibição do número (o que o contato vê no lugar do telefone) passa por uma revisão da Meta. Este evento sai quando o estado dessa revisão muda, por exemplo de `pending_review` para `approved` ou `declined`. `number.status` é o mesmo `displayNameStatus` de `GET /v1/numbers/{id}`: `approved`, `pending_review`, `declined`, `expired` ou `none`; novos valores podem aparecer. `number.name` é o nome a que o estado se refere: o nome pedido, quando há um pedido, senão o nome em uso. A Meta não manda o motivo da recusa nesta consulta, e a Luna não o devolve. A Luna confere o nome de cada número periodicamente, então o evento chega com atraso de até cerca de uma hora. Um nome aprovado só passa a valer depois que o número é registrado de novo, como o guia [O que o número faz na Meta](https://lunahia.com.br/docs/numero-na-meta#nome-de-exibicao) explica. ```json { "version": "2026-11-10", "event_id": "23fd01fabc59f4c9ffda20955726e7e3e19c6a05cf609197c8b3c0aef8405e76", "event_type": "number.display_name_reviewed", "occurred_at": "2026-11-04T14:20:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "waba_id": "102290129340398", "status": "declined", "name": "Clínica Sorriso Centro" } } ``` ### `number.action_required` e `number.action_resolved` O aviso que o seu sistema mostra ao cliente dele: **o número precisa de ação**. `number.action_required` sai quando a lista de motivos de `connection` passa de vazia para não vazia, e `number.action_resolved` quando ela esvazia. É o mesmo cálculo de `connection` em `GET /v1/numbers` e `GET /v1/numbers/{id}`: `status`, `can_send` e `reasons`, cada motivo com `code` (para o seu código comparar), `message` e `solution` (em português, prontos para repassar). Os motivos: `pin_required`, `registration_blocked`, `credential_invalid`, `credential_expired`, `credential_expiring`, `payment_required`, `payment_method_missing`, `account_restricted`, `account_disabled`, `trial_expired` e `account_blocked`; novos códigos podem aparecer. Um motivo nem sempre tira o envio: `can_send` diz se enviar vai funcionar agora. O evento sai **uma vez na passagem**, e não a cada mudança da lista; quem precisa do estado corrente lê `connection`. Um número que você desconecta não gera `number.action_resolved`: `number.disconnected` já avisou. Precisa de ação ```json { "version": "2026-11-10", "event_id": "8832cdd12544436fce3b39d709158baa046091d010b5ed144a289c81b807c710", "event_type": "number.action_required", "occurred_at": "2026-10-28T15:02:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "status": "action_required", "can_send": false, "reasons": [ { "code": "payment_required", "message": "A Meta recusou um envio deste número por falta de método de pagamento na conta de WhatsApp Business do negócio.", "solution": "O dono da conta cadastra o método de pagamento no WhatsApp Manager da Meta. A Luna não intermedeia esse pagamento. Quando um envio voltar a ser aceito, o aviso sai do ar." } ] } } ``` Não precisa mais ```json { "version": "2026-11-10", "event_id": "3279de99ef1bc2ade5d88bde7a2fd878b8faabddc179b8dceebded74d5b7394b", "event_type": "number.action_resolved", "occurred_at": "2026-10-28T15:40:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "status": "connected", "can_send": true } } ``` ### `onboarding.link.opened`, `onboarding.link.completed`, `onboarding.link.failed` e `onboarding.link.expired` O ciclo do [link de conexão](https://lunahia.com.br/docs/conectar-numero) que você mandou a um cliente, com o `externalId` dele em `link.external_id`. `onboarding.link.opened`: o cliente abriu o link pela primeira vez (`link.opened_at`), uma vez por link e não de novo quando ele volta à página; serve para saber quem abriu e travou sem concluir. `onboarding.link.completed`: o cliente concluiu a conexão (o link passa a `used`); `link.waba_id` é a conta que o cliente conectou, mesmo quando a conta veio sem número, e `link.number_id` traz o número quando a Luna já o registrou (`number` então vem no mesmo formato dos eventos de número, com telefone e `waba_id`); `number.connected` avisa quando ele fica pronto. `onboarding.link.failed`: uma tentativa não deu certo, uma vez por tentativa (`link.session_id`), e o link segue aberto até vencer. `link.reason` diz por quê: `abandoned` (o cliente fechou a janela da Meta, e `link.step` é a tela em que parou), `error` (a janela da Meta relatou um erro, em `link.error_code`), `failed` (a Luna tentou concluir e não conseguiu), `country_not_supported` (o número não é +55) ou `registration_blocked` (a Meta bloqueou o registro por 72 horas). `onboarding.link.expired`: o link venceu sem uso, e um link usado nunca gera este evento. Os quatro saem uma vez, e `number` é `null` quando o evento ainda não tem número. O guia de [um SaaS com muitos clientes](https://lunahia.com.br/docs/saas-com-n-clientes) usa os quatro. Link aberto ```json { "version": "2026-11-10", "event_id": "b8a277c5c9377c213ee4c3b79c3e83829f3bef5f69521db1a0434da05acfbc1d", "event_type": "onboarding.link.opened", "occurred_at": "2026-10-28T15:21:40.000Z", "phone_number_id": null, "number": null, "link": { "id": "7c3e5a19-2b4d-4f60-8a1e-9d0b3c5f7a21", "external_id": "cliente-8841", "opened_at": "2026-10-28T15:21:40.000Z" } } ``` Conexão concluída ```json { "version": "2026-11-10", "event_id": "fd3596b2273541c7a77c69cb8a2ddb0e060052ddc84f251b5a76961053b578b1", "event_type": "onboarding.link.completed", "occurred_at": "2026-10-28T15:30:12.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "waba_id": "102290129340398" }, "link": { "id": "7c3e5a19-2b4d-4f60-8a1e-9d0b3c5f7a21", "external_id": "cliente-8841", "used_at": "2026-10-28T15:30:12.000Z", "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b" } } ``` Tentativa que não deu certo ```json { "version": "2026-11-10", "event_id": "cabf3f3478bda2efd0e9a3726d503dbcd575bec16cc0ccf5fc65cdcb4c88cea3", "event_type": "onboarding.link.failed", "occurred_at": "2026-10-28T15:12:40.000Z", "phone_number_id": null, "number": null, "link": { "id": "7c3e5a19-2b4d-4f60-8a1e-9d0b3c5f7a21", "external_id": "cliente-8841", "session_id": "2e8f4b60-1a3c-4d57-9b0e-6c7d8e9f0a12", "reason": "abandoned", "step": "phone_number_setup", "error_code": null } } ``` Link vencido ```json { "version": "2026-11-10", "event_id": "1df73af80cf86f74267290bc13fcd1f82551997dd79845170b35c78f40b563ad", "event_type": "onboarding.link.expired", "occurred_at": "2026-10-31T15:00:00.000Z", "phone_number_id": null, "number": null, "link": { "id": "7c3e5a19-2b4d-4f60-8a1e-9d0b3c5f7a21", "external_id": "cliente-8841", "expired_at": "2026-10-31T15:00:00.000Z" } } ``` ### `account.restricted`, `account.violation`, `account.disabled`, `account.reinstated` e `account.update` A saúde da conta de WhatsApp Business do número: restrição, violação de política, desativação, reativação, e qualquer outro aviso de conta da Meta (`account.update`, com o `event` cru dela e o resto em `details`). O aviso é da **conta**, e a Luna o entrega **uma vez para cada número conectado dela**: todos têm o mesmo `waba_id` dentro do objeto `waba`. O que cada um significa e o que fazer está em [Saúde da conta](https://lunahia.com.br/docs/saude-da-conta). Conta restrita ```json { "version": "2026-11-10", "event_id": "d3b1b97cb8b69ac0bf9db087b5200febbea3dcbcc8d0a4108913592b51fdaf29", "event_type": "account.restricted", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "waba": { "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "restrictions": [ { "restriction_type": "RESTRICTED_ADD_PHONE_NUMBER_ACTION", "expiration": "2026-11-13T12:00:00Z", "remediation": null } ] } } ``` Violação de política ```json { "version": "2026-11-10", "event_id": "a2fa828795bf24fd8e7460738c1a1e11a1bcd278fc09a0d238f92ba8c5994441", "event_type": "account.violation", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "waba": { "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "violation_type": "ALCOHOL_VIOLATION" } } ``` Conta desativada ```json { "version": "2026-11-10", "event_id": "b0308dcc1ab6324eaea0474f1bcdec28146d3a6eb62668a1425fb3a7d6aad778", "event_type": "account.disabled", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "waba": { "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "ban_date": "2026-10-13" } } ``` Conta reativada ```json { "version": "2026-11-10", "event_id": "135a9c7b3f192a7cab5ea55f68e0a8113e8d8e80acaa0ae8dad7f20aaf61f2db", "event_type": "account.reinstated", "occurred_at": "2026-10-14T09:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "waba": { "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "ban_date": null } } ``` Outro aviso de conta ```json { "version": "2026-11-10", "event_id": "f663ad9f077e865db5d29245db96fe579e9aaa487bdf2f9d91a6e535af3d7949", "event_type": "account.update", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "waba": { "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "event": "ACCOUNT_DELETED", "details": {} } } ``` ### `account.limit_changed`, `number.disconnected` e `number.quality_changed` `account.limit_changed`: a Meta mudou o limite da conta (`daily_conversation_limit` e `max_phone_numbers_per_waba`), que vale para todos os números dela. `number.disconnected`: o número deixou de estar conectado à Luna, e `reason` diz o aviso da Meta que causou isso. `number.quality_changed`: a avaliação de qualidade do número mudou. A Meta não tem webhook para qualidade, então esse evento chega com atraso de até cerca de uma hora. Veja [Saúde da conta](https://lunahia.com.br/docs/saude-da-conta). Limite da conta ```json { "version": "2026-11-10", "event_id": "a3bddf693de91539edaebb432d0d4f936b40822085cafa5c7864ae149756dbff", "event_type": "account.limit_changed", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "waba": { "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "daily_conversation_limit": "TIER_2K", "max_phone_numbers_per_waba": null } } ``` Número desconectado ```json { "version": "2026-11-10", "event_id": "0dfe4e31d4e40e4a5da6d3f42f0d44b660f67ce551b2a43966e5fb0390fcd741", "event_type": "number.disconnected", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "waba_id": "102290129340398", "reason": "PARTNER_APP_UNINSTALLED", "disconnection_reason": null, "initiated_by": null } } ``` Qualidade do número ```json { "version": "2026-11-10", "event_id": "cc81de4eb28ad6a80e39c6cca13eb4b6db12f223f3c1346552cbc24795bcdbbe", "event_type": "number.quality_changed", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "waba_id": "102290129340398", "previous_quality_rating": "GREEN", "quality_rating": "YELLOW" } } ``` ### `number.credential_expiring` e `account.alert` `number.credential_expiring`: a autorização que o seu cliente deu à Luna vence em até 14 dias (`credential_expires_at`). Sai uma vez por vencimento e por número, e a renovação se faz com um link de reconexão (`POST /v1/onboarding/links` com `numberId`). `account.alert`: um alerta que a Meta mandou sobre a conta (o campo `account_alerts`), com `alert_type`, `alert_severity`, `alert_status`, `alert_description` e o resto em `details`, tudo como a Meta mandou. Os dois estão explicados em [Saúde da conta](https://lunahia.com.br/docs/saude-da-conta#credencial). Autorização perto de vencer ```json { "version": "2026-11-10", "event_id": "33b03111fe7f1f225626ece55b50955389e78742a6b99059f05be056ce2b2260", "event_type": "number.credential_expiring", "occurred_at": "2026-11-21T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "waba_id": "102290129340398", "credential_expires_at": "2026-12-05T12:00:00.000Z" } } ``` Alerta da Meta sobre a conta ```json { "version": "2026-11-10", "event_id": "fb613a0660724669d9251d4185488ec26409b34345c592b908ce9747b8430f99", "event_type": "account.alert", "occurred_at": "2026-10-19T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "waba": { "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "entity_type": "WABA", "entity_id": "102290129340398", "alert_severity": "INFORMATIONAL", "alert_status": "ACTIVE", "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED", "alert_description": "Messaging limit increase deferred.", "details": {} } } ``` ### `template.category` e `template.quality` Como `template.status`, não têm número nem conversa (`phone_number_id` é `null`), trazem `template.waba_id` e saem em ordem com ele, por conta de negócio. `template.category`: a Meta mudou, ou avisou que vai mudar, a categoria de um template. O aviso prévio traz `correct_category` e `scheduled_for`, e a mudança feita traz `previous_category` e `new_category`. **A categoria muda o preço que a Meta cobra do negócio**, e a mudança de `UTILITY` para `MARKETING` o sobe; veja [Templates](https://lunahia.com.br/docs/templates). `template.quality`: a nota de qualidade do template mudou, e nota baixa antecede a pausa. Aviso prévio de categoria ```json { "version": "2026-11-10", "event_id": "67e825cdeb1f139ea3f76761c2e087a272352caca49dea9ab471383293a8ca07", "event_type": "template.category", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": null, "number": null, "template": { "id": "3f6a1c52-9d4e-4b87-a1f0-5e2c7b9d8a14", "name": "pedido_confirmado", "language": "pt_BR", "waba_id": "102290129340398", "external_id": "cliente-8841", "category": "UTILITY", "previous_category": null, "new_category": null, "correct_category": "MARKETING", "scheduled_for": "2026-10-14T17:46:40.000Z" } } ``` Categoria mudada ```json { "version": "2026-11-10", "event_id": "a088e870f11e399bc1d40266c5d07e18d0b13da6d1cf4d2021cbb232451ed86d", "event_type": "template.category", "occurred_at": "2026-10-14T17:46:40.000Z", "phone_number_id": null, "number": null, "template": { "id": "3f6a1c52-9d4e-4b87-a1f0-5e2c7b9d8a14", "name": "pedido_confirmado", "language": "pt_BR", "waba_id": "102290129340398", "external_id": "cliente-8841", "category": "MARKETING", "previous_category": "UTILITY", "new_category": "MARKETING", "correct_category": null, "scheduled_for": null } } ``` Qualidade do template ```json { "version": "2026-11-10", "event_id": "8624296410fe8b7631164b57d667847f22145595d3bac4ae644e32930aab9321", "event_type": "template.quality", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": null, "number": null, "template": { "id": "3f6a1c52-9d4e-4b87-a1f0-5e2c7b9d8a14", "name": "pedido_confirmado", "language": "pt_BR", "waba_id": "102290129340398", "external_id": "cliente-8841", "previous_quality_score": "GREEN", "new_quality_score": "YELLOW" } } ``` ### `webhook.test` O evento de teste. **Ele só chega quando você o pede**, em `POST /v1/webhooks/endpoints/{id}/test`: a Luna nunca o envia por conta própria. Não tem número nem conversa (`phone_number_id` é `null`), e o objeto traz o id do endpoint, para você saber qual deles foi testado quando dois apontam para a mesma URL. É assinado como qualquer entrega, e é um bom caso para exercitar a sua verificação. ```json { "version": "2026-11-10", "event_id": "6af3f85d8fedc8bb0f6d5bb6b4631e324574c539763c25cf113fd40db822cea8", "event_type": "webhook.test", "occurred_at": "2026-10-07T12:00:00.000Z", "phone_number_id": null, "number": null, "webhook_test": { "endpoint_id": "5c0e9a52-3a0e-4c3f-9f3e-0b3f6f1a2c77" } } ``` ## Verifique a assinatura Qualquer pessoa pode mandar um `POST` para a sua URL. A assinatura é o que prova que a entrega veio da Luna. **Verifique antes de tratar o evento.** Cada entrega traz um cabeçalho: **Em palavras simples.** Você e a Luna compartilham um segredo: o `secret` que a resposta do cadastro devolve, e que começa com `whsec_`. Antes de mandar cada evento, a Luna mistura o segredo com o conteúdo do evento e escreve o resultado no cabeçalho `X-Luna-Signature`, como um carimbo. Quem não sabe o segredo não consegue fazer um carimbo igual. Ao receber, você refaz a mesma mistura e vê se o carimbo bate: se bater, o evento veio da Luna e ninguém o mudou no caminho. **Por que importa.** O endereço do seu webhook é público. Sem conferir o carimbo, qualquer pessoa pode mandar um evento falso (um “pedido pago”, por exemplo) e o seu sistema agiria como se fosse verdadeiro. 1. Do cabeçalho, pegue o número depois de `t=` (o instante em que a Luna assinou) e os valores depois de `v1=` (os carimbos). 2. Junte o `t`, um ponto e o **corpo exatamente como chegou** (os mesmos bytes, sem abrir o JSON e montar de novo), e faça a mistura com o seu segredo: é o HMAC-SHA256, que qualquer linguagem tem pronto. 3. Compare o resultado com cada `v1`. Igual a algum: pode confiar. Diferente de todos: responda `401` e ignore o evento. ```http X-Luna-Signature: t=1760000000,v1=3f1c0a9e5b7d2c4a6e8f0b1d3c5a7e9f2b4d6c8a0e1f3a5b7c9d1e3f5a7b9c1d ``` 1. Leia o `t`, o instante da assinatura em segundos desde 1970. Recuse a entrega se ele estiver a mais de **300 segundos** do seu relógio, para qualquer lado. Isso impede que alguém reapresente uma requisição capturada. 2. Calcule o HMAC-SHA256 do texto `t` + `.` + **corpo bruto**, com o segredo do endpoint como chave, e escreva o resultado em hexadecimal. O segredo é a string inteira, `whsec_` incluído. 3. Compare o resultado com **cada** valor `v1=` do cabeçalho, em tempo constante. Se algum for igual, a assinatura é válida. - Use os **bytes exatos** que chegaram. Se você ler o JSON e serializar de novo, a ordem das chaves ou o escape pode mudar, e a assinatura falha de forma intermitente. Em Express, use `express.raw({ type: "application/json" })` nesta rota. Em Flask, `request.get_data()`. Em FastAPI, `await request.body()`. - Compare em tempo constante (`timingSafeEqual`, `compare_digest`), e nunca com `==`. - Durante a rotação do segredo o cabeçalho traz **duas** assinaturas, `v1=` repetido. Você conhece uma delas, e pode ser a segunda. Por isso o código confere todas. - Responda `401` a uma assinatura inválida. A Luna conta só `2xx` como entregue, então um `401` nunca é tomado por sucesso. ### A função de verificação Salve como `verify.mjs` (Node) ou `verify.py` (Python): ```js import crypto from 'node:crypto'; 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; } ``` ```python import hashlib import hmac import re import time 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 ``` ### Um servidor completo Salve como `server.mjs` ou `server.py`, ao lado do arquivo anterior, e rode com `LUNA_WEBHOOK_SECRET` definida: ```js import http from 'node:http'; import { verifyLunaSignature } from './verify.mjs'; const SECRET = process.env.LUNA_WEBHOOK_SECRET; // whsec_... const seen = new Set(); // em produção: um banco ou Redis, com prazo de validade async function handle(event) { switch (event.event_type) { case 'message.received': // wa_id pode ser null (usuário sem telefone): então a chave é o user_id console.log('received', event.message.wa_id ?? event.message.user_id, event.message.text); break; case 'message.status': console.log('status', event.message.wamid, event.message.status); break; default: console.log('ignored', event.event_type); // tipos novos podem aparecer } } 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 primeiro, trabalhe depois const event = JSON.parse(raw.toString('utf8')); if (seen.has(event.event_id)) return; // pelo menos uma vez: descarte as repetições seen.add(event.event_id); handle(event).catch((err) => console.error('handler failed', err)); // o tratamento nunca roda na thread da requisição: o trabalho vai para uma fila }); }) .listen(Number(process.env.PORT ?? 3000)); ``` ```python import json import os import queue import threading from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer from verify import verify_luna_signature SECRET = os.environ["LUNA_WEBHOOK_SECRET"] # whsec_... seen = set() # em produção: um banco ou Redis, com prazo de validade seen_lock = threading.Lock() events = queue.Queue() # o tratamento nunca roda na thread da requisição: o trabalho vai para uma fila def handle(event): kind = event["event_type"] if kind == "message.received": # wa_id pode ser null (usuário sem telefone): então a chave é o user_id print("received", event["message"]["wa_id"] or event["message"]["user_id"], event["message"]["text"]) elif kind == "message.status": print("status", event["message"]["wamid"], event["message"]["status"]) else: print("ignored", kind) # tipos novos podem aparecer def worker(): # um trabalhador pega os eventos um a um (chame o LLM aqui, e não na requisição) 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))) header = self.headers.get("X-Luna-Signature") if not verify_luna_signature(raw, header, SECRET): self.send_response(401) self.send_header("Content-Length", "0") self.end_headers() return self.send_response(200) # responda 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 # pelo menos uma vez: descarte as repetições seen.add(event["event_id"]) if not repeated: events.put(event) threading.Thread(target=worker, daemon=True).start() ThreadingHTTPServer(("", int(os.environ.get("PORT", "3000"))), Handler).serve_forever() ``` > O `Set` em memória do exemplo some quando o processo reinicia. Em produção, guarde os `event_id` já processados num banco ou num Redis, com prazo de expiração, e descarte os repetidos. ### Conferir à mão, no terminal Para ver a conta acontecer, ou para depurar um `401` que você não entende, faça o passo 2 no terminal com o `openssl`. O exemplo usa um segredo e um corpo de mentira; troque pelo seu segredo, pelo `t` do cabeçalho e pelos bytes do corpo que o seu servidor recebeu: ```bash SEGREDO='whsec_EXEMPLO_NAO_E_UM_SEGREDO' T=1760000000 CORPO='{"ok":true}' printf '%s' "$T.$CORPO" | openssl dgst -sha256 -hmac "$SEGREDO" | awk '{print $NF}' ``` Resultado ```text 22c562eb3e7a1c918e80953b5b95428cd92c8d3942fc77a190d116b53aa68258 ``` Um cabeçalho `X-Luna-Signature: t=1760000000,v1=` seguido desse resultado seria válido para esse segredo e esse corpo. O `printf` (e não `echo`) evita que o terminal acrescente uma quebra de linha ao corpo, o que mudaria o resultado. > Serviços que mostram o que chegou na sua URL, como o webhook.site, servem para **ver** o evento, mas copiar o corpo da tela pode mudar espaços e quebras de linha, e a assinatura deixa de bater. Confira dentro do seu servidor, com os bytes que ele recebeu. ## Retentativas, rejeitados e reenvio ### Quando a entrega falha - A Luna tenta de novo com espera crescente. O teto de cada espera é de 30 segundos, 90 segundos, 4,5 minutos, 13,5 minutos e 40,5 minutos, e depois 1 hora entre as tentativas seguintes. A espera de cada tentativa é sorteada entre a metade e o valor cheio. - Cinco falhas seguidas abrem um disjuntor: a Luna para de bater no endpoint e deixa passar uma sonda por minuto. Três sucessos seguidos o fecham. Quando o endpoint volta, o acumulado é entregue em ritmo crescente, para não derrubá-lo de novo. - Quando a política de retentativa se esgota, a Luna desiste e o evento vai para a **fila de rejeitados**. - Separado disso, o acumulado de um endpoint tem dois tetos: 10.000 eventos pendentes e seis horas de idade. O mais antigo é descartado ao passar de qualquer um, e você recebe `backlog.dropped`. - Esses valores são técnicos e idênticos para todos os clientes. ### A fila de rejeitados Um evento chega aqui depois de a política de retentativa se esgotar. Ele não é entregue de novo sozinho: ou você o re-enfileira, ou ele fica lá até a retenção expirar. Todos os tipos de evento chegam aqui, inclusive `message.echo` e `template.status`; neste último o `wamid` vem nulo, porque não há mensagem. Escopo `webhooks:read` para listar e `webhooks:write` para re-enfileirar. ```bash curl -X GET "https://api.lunahia.com.br/v1/webhooks/dlq?limit=50" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/webhooks/dlq?limit=50', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/webhooks/dlq?limit=50", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` Resposta `200` ```json { "items": [ { "id": "0b6f6f2a-6d3e-4b8e-9a52-2f3c1d4e5a60", "endpointId": "5c0e9a52-3a0e-4c3f-9f3e-0b3f6f1a2c77", "eventType": "message.received", "wamid": "wamid.EXAMPLE_NOT_A_REAL_ID", "rejectedAt": "2026-10-06T16:00:00.000Z", "failureReason": "http_5xx", "requeuedAt": null } ], "nextCursor": null } ``` - `failureReason` é a classe da última falha: `http_4xx` (o seu servidor entendeu e recusou), `http_5xx` (aceitou e quebrou), `timeout`, `conexao`, `destino_recusado` ou `reenvio_pedido`. Este último não é falha: é um reenvio que você mesmo pediu em `POST /v1/messages/{id}/replay`, e já nasce com `requeuedAt` preenchido. - A resposta não traz total, de propósito. Para saber quantos itens há, pagine até `nextCursor` vir nulo. O `limit` vai até 100. - O corpo do evento não vem na lista. Re-enfileire para recebê-lo no seu endpoint, assinado como qualquer outra entrega. ```bash curl -X POST "https://api.lunahia.com.br/v1/webhooks/dlq/YOUR_DLQ_ITEM_ID/reenfileirar" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/webhooks/dlq/YOUR_DLQ_ITEM_ID/reenfileirar', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/webhooks/dlq/YOUR_DLQ_ITEM_ID/reenfileirar", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` A resposta é `202`: o pedido foi registrado, e a entrega acontece de forma assíncrona. Repetir a chamada para o mesmo item responde `409` com `error: "already_requeued"` e o instante do primeiro pedido, e não republica de novo. Se o seu endpoint ainda estiver fora do ar, a entrega será adiada e retentada pela política de sempre. Não adianta pedir em massa para acelerar. ### Reenviar o evento de uma mensagem Para testar o seu endpoint, ou para recuperar o evento de uma mensagem que você já tem, peça o reenvio. O escopo é `webhooks:write`, e não `messages:*`: o escopo acompanha o efeito, e o efeito é causar entrega no seu endpoint. ```bash curl -X POST "https://api.lunahia.com.br/v1/messages/YOUR_MESSAGE_ID/replay" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages/YOUR_MESSAGE_ID/replay', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages/YOUR_MESSAGE_ID/replay", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` Resposta `202` ```json { "deliveryId": "9f2a1b0c-3d4e-4f5a-8b9c-0d1e2f3a4b5c", "requestedAt": "2026-10-06T18:30:00.000Z" } ``` - Cada pedido produz uma entrega nova, com `deliveryId` próprio. Chamar duas vezes produz duas entregas, e não um erro. - O reenvio não fura a fila nem pula defesa nenhuma. - O `event_id` do evento reenviado é **o mesmo** do original. Ele nasce da mensagem (o `wamid` e o contato, ou o `wamid` e o estado), e não da entrega. Se o seu servidor descarta os `event_id` que já viu, vai descartar o reenvio também: para testar, tire esse `event_id` da sua lista de vistos antes de pedir. O `deliveryId` da resposta identifica o pedido de reenvio, e não o evento. - O evento reenviado depende da mensagem: para uma mensagem recebida é o `message.received`; para uma enviada é o **último `message.status`** dela (`sent`, `delivered`, `read`, `failed` ou `canceled`), com o mesmo formato e a mesma assinatura do original, e é o `message.status` mais recente, e não a lista deles. O reenvio sai marcado como reenvio pedido (`failureReason: "reenvio_pedido"` em `GET /v1/webhooks/dlq`), igual ao da recebida. Mensagem enviada que a Meta ainda não aceitou, ou que ainda não tem nenhum `message.status`, responde `400`, e o estado dela está em `GET /v1/messages/{id}`. Um endpoint que não recebe o tipo (`eventTypes`) não conta como destino do reenvio. - Sem endpoint ativo (nenhum cadastrado, ou todos pausados) a resposta é `409` com `error: "no_webhook_endpoint"`, e não um `202` que não se cumpre. ## Rotacione o segredo Rotacione quando o segredo vazar, ou quando você o perder. A rotação não derruba a sua integração: ```bash curl -X POST "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID/rotacionar" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID/rotacionar', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID/rotacionar", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` - A resposta traz o segredo novo, uma única vez. - O segredo anterior continua produzindo assinatura válida por **sete dias**. Nesse período cada entrega carrega as duas assinaturas no mesmo cabeçalho. - `previousSecretExpiresAt` diz quando o anterior deixa de valer. Enquanto ele estiver no futuro, o endpoint está no meio de uma rotação. - Rotacionar de novo antes do fim da janela descarta o mais antigo dos dois: nunca existem três segredos válidos. ### O segredo vazou: revogue o anterior na hora Os sete dias protegem a sua integração, e num vazamento viram risco: quem tem o segredo antigo continua assinando entregas que parecem legítimas. Para encerrar a sobreposição, rotacione com `revokePrevious: true`. O anterior deixa de valer no mesmo instante, e `previousSecretExpiresAt` volta nulo. ```bash curl -X POST "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID/rotacionar" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "revokePrevious": true }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID/rotacionar', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "revokePrevious": true }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID/rotacionar", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "revokePrevious": True, }, timeout=10, ) print(res.status_code, res.json()) ``` > O custo é este: as entregas que já saíram assinadas só com o segredo antigo falham na verificação do seu lado. Troque o segredo na sua configuração logo depois de rotacionar. > O contrato completo de cada rota está na [referência da API](https://lunahia.com.br/docs/referencia), na seção Webhooks. ## Detalhes das rotas deste guia A [referência da API](https://lunahia.com.br/docs/referencia) diz como chamar cada rota, em poucas linhas. O que explica o motivo de cada decisão, os casos de borda e os avisos está aqui, na ordem da referência. ### GET /v1/webhooks/endpoints O segredo de assinatura NÃO vem aqui, e não vem de rota nenhuma. Ele sai uma única vez, na resposta do cadastro e na da rotação: a Luna guarda apenas a forma cifrada dele. Se você o perdeu, rotacione para receber um novo: não existe caminho de recuperação, e isso é desenho. Use esta rota para descobrir se já existe endpoint antes de cadastrar um. Cliente sem nenhum endpoint recebe 200 com lista vazia, e não 404. quando previousSecretExpiresAt estiver no futuro, aquele endpoint está no meio de uma rotação: as entregas carregam duas assinaturas, e as duas são válidas até aquele instante. ### POST /v1/webhooks/endpoints O segredo aparece nesta resposta e em mais nenhuma. Guarde-o no momento em que o receber: a Luna guarda apenas a forma cifrada dele, e nenhuma rota o devolve. Se você o perder, rotacione para receber um novo. A URL precisa usar https e precisa apontar para um endereço público na internet. Endereço de rede interna, de laço local e de serviço de metadados de nuvem são recusados aqui e também no momento de cada entrega, porque um nome pode mudar de endereço entre o cadastro e a chamada. A Luna não segue redirecionamento: cadastre a URL final. eventTypes, opcional, escolhe os tipos de evento que este endpoint recebe (por exemplo, só message.received e message.status). Ausente ou vazio, ele recebe todos, inclusive os tipos que a Luna criar depois. O filtro é só por tipo, nunca por conteúdo ou remetente. externalIds e phoneNumberIds, opcionais, limitam o endpoint a clientes seus e a números: ele só recebe os eventos de números com um destes externalId (inclusive os conectados depois) ou com um destes ids (o UUID da Luna ou o id da Meta), e os eventos de link de conexão com o externalId. Ausentes ou vazios, ele recebe de todos. É o jeito de ter uma URL por cliente seu; o external_id continua em todo evento, nos dois jeitos. O filtro é só por identificador, e a assinatura, a ordem, o reenvio e a fila de rejeitados são os de qualquer endpoint. Cada cliente pode ter até 25 endpoints, e cada evento é entregue a todos os que estiverem ativos e aceitarem o tipo e o cliente dele. Com 25 já cadastrados, a resposta é 409 (webhook_endpoint_limit): remova um com DELETE /v1/webhooks/endpoints/{id} para liberar a vaga. O limite é de infraestrutura e igual para todos. ### GET /v1/webhooks/event-types A lista cresce quando a Luna cria um tipo novo, sem mudar a versão do contrato. O evento webhook.test não está nela: ele só sai quando você pede o teste de um endpoint. ### GET /v1/webhooks/endpoints/{id} O segredo não vem aqui, e não vem de rota nenhuma. A Luna guarda apenas a forma cifrada dele. quando previousSecretExpiresAt estiver no futuro, o endpoint está no meio de uma rotação: as entregas carregam duas assinaturas, e as duas são válidas até aquele instante. ### PATCH /v1/webhooks/endpoints/{id} A URL nova passa pela mesma validação do cadastro (https e endereço público), e o segredo de assinatura continua o mesmo: você aponta para outro servidor sem reconfigurar a verificação. Trocar a URL zera lastDeliveryAt, lastFailureAt e lastHttpStatus, porque eles diziam respeito ao servidor antigo. paused: true pausa. Um endpoint pausado não recebe eventos novos, e os eventos que ocorrerem durante a pausa NÃO são entregues depois: pausar não adia, descarta. O que já estava na fila para ele também é descartado. paused: false retoma, e ele passa a receber o que ocorrer a partir daquele momento. Pausar um endpoint já pausado não muda pausedAt. eventTypes troca a lista de tipos de evento que o endpoint recebe: a lista enviada substitui a anterior, e lista vazia volta a receber todos. O filtro vale daí em diante, e é só por tipo. O que ocorreu antes e foi filtrado não é entregue depois. externalIds e phoneNumberIds trocam, do mesmo jeito, os clientes e os números de que o endpoint recebe eventos: a lista enviada substitui a anterior, e lista vazia volta a receber de todos. phoneNumberIds aceita o UUID da Luna ou o id da Meta e devolve os ids da Meta, os mesmos que os eventos trazem em phone_number_id. headers troca, do mesmo jeito, os cabeçalhos próprios que a Luna envia em cada entrega: o objeto enviado substitui o anterior, e {} remove todos. Valem as regras do cadastro (até 5, nome de cabeçalho válido e não reservado, valor ASCII de até 1024 caracteres). Os valores são segredo e nunca voltam; a resposta traz só os nomes, em headerNames. Você pode testar um endpoint pausado com POST /v1/webhooks/endpoints/{id}/test antes de retomá-lo. Endpoint que não é seu responde 404, igual a endpoint que não existe. Devolve o endpoint como GET /v1/webhooks/endpoints/{id}. ### DELETE /v1/webhooks/endpoints/{id} O que acontece com o que ainda estava pendente: os eventos que já estavam na fila de entrega para este endpoint são descartados quando chegam, e não são reentregues nem vão para a fila de rejeitados. Os itens que já estavam na fila de rejeitados (GET /v1/webhooks/dlq) e apontavam para ele são apagados junto: sem endpoint, não há para onde re-enfileirá-los. Isso não tem volta, e o segredo de assinatura também se perde. Para parar de receber sem perder nada, pause com PATCH. Remover libera uma vaga do limite de 25 endpoints por cliente. Endpoint que não é seu responde 404, igual a endpoint que não existe. ### GET /v1/webhooks/endpoints/{id}/deliveries É o histórico que GET /v1/webhooks/endpoints/{id} não tem: uma linha por tentativa de entrega ao endpoint, dos últimos 7 dias. Cada evento pode aparecer várias vezes (o mesmo eventId, com attempt 1, 2, 3...) até o seu servidor aceitar ou a Luna desistir; o que ela desistiu de entregar está em GET /v1/webhooks/dlq. httpStatus é nulo quando o seu servidor não respondeu (tempo esgotado, conexão recusada, endereço que deixou de ser público). status é success para 2xx e failed no resto, inclusive redirecionamento, que a Luna não segue. A lista não traz o corpo enviado, o cabeçalho nem o que o seu servidor respondeu, e não tem total: pagine por nextCursor até ele vir nulo. Endpoint que não é seu responde 404, igual a endpoint que não existe. ### POST /v1/webhooks/endpoints/{id}/test Funciona com o endpoint pausado, que é para isso: confira antes de retomar. delivered é true quando o seu servidor respondeu 2xx. Quando não, failure diz o porquê (timeout, connection, destination_not_allowed, response_too_large ou http_status) e statusCode traz o status que ele devolveu. O corpo da resposta do seu servidor não volta, de propósito. O evento webhook.test só existe quando você o pede: a Luna nunca o envia por conta própria. Ele não tem número nem conversa (phone_number_id é null) e traz o id do endpoint em webhook_test.endpoint_id. O limite é de 5 testes por minuto por cliente, igual para todos, porque cada chamada é uma requisição de saída para o seu servidor. Acima disso, 429 com Retry-After. Endpoint que não é seu responde 404, igual a endpoint que não existe. ### POST /v1/webhooks/endpoints/{id}/rotacionar O segredo anterior continua produzindo assinatura válida por sete dias, e durante essa janela cada entrega carrega as duas assinaturas no mesmo cabeçalho. Isso existe para que rotacionar não derrube a sua integração: você troca a configuração do seu lado quando puder, dentro da janela, sem perder entrega. O instante exato em que o anterior deixa de valer vem em previousSecretExpiresAt. Rotacionar de novo antes do fim da janela descarta o mais antigo dos dois: em nenhum momento existem três segredos válidos. Se o segredo anterior vazou, envie o corpo {"revokePrevious": true}: ele deixa de valer no mesmo instante, e previousSecretExpiresAt volta nulo. O custo é que as entregas que já saíram assinadas só com ele falham na verificação do seu lado, então troque a configuração logo. Sem corpo, nada muda. ### GET /v1/webhooks/dlq Um evento chega aqui depois de a política de retentativa ter se esgotado: recuo exponencial, disjuntor e drenagem progressiva já tendo sido aplicados. Ele não é entregue de novo sozinho: ou você o re-enfileira, ou ele permanece aqui até a retenção expirar. Todos os tipos de evento chegam aqui, inclusive message.echo e template.status. O template.status não tem mensagem, então o wamid vem nulo, e re-enfileirá-lo entrega o mesmo evento de estado do template. A resposta não traz total nem contagem, de propósito: a Luna não conta entregas, e nenhum número desta API alimenta cobrança. Para saber quantos itens há, pagine até nextCursor vir null. Cada item traz numberId e externalId (o número por onde o evento passou e o seu rótulo para o cliente dele; nulos em template.* e quando a mensagem já não está na Luna), attempts (quantas vezes a Luna tentou entregar esse evento) e lastHttpStatus (o que o seu endpoint respondeu na última tentativa, nulo quando ele não respondeu). São o diagnóstico de UMA entrega, e não somas. allowedActions traz requeue enquanto o item não foi re-enfileirado. Filtre com ?endpointId=, ?externalId= e ?requeued= (true ou false). O corpo do evento não vem aqui. Re-enfileire para recebê-lo pelo seu endpoint, assinado como qualquer outra entrega. ### POST /v1/webhooks/dlq/{id}/reenfileirar Repetir a chamada para o mesmo item responde 409 com o instante do primeiro pedido, e não republica de novo. Isso existe para que dois cliques, ou uma retentativa sua, não produzam duas entregas do mesmo evento. Re-enfileirar não fura a fila nem pula as defesas: se o seu endpoint ainda estiver fora do ar, a entrega será adiada e retentada pela política de sempre, sem que nenhuma requisição chegue a sair. Não é necessário esperar o seu servidor voltar para pedir, mas também não adianta pedir em massa para acelerar. Item que não é seu responde 404, igual a item que não existe. --- # Enviar mensagens Fonte: https://lunahia.com.br/docs/enviar-mensagens Uma rota envia todos os tipos de mensagem: `POST /v1/messages`. O campo `type` diz qual é o tipo, e um corpo sem `type` é lido como texto. Este guia cobre os tipos, a regra da janela de 24 horas, a idempotência e como acompanhar a entrega. ## O básico - A chave de API precisa do escopo `messages:write`. - `from` é o número de origem: o **UUID da Luna** (o `id` que `GET /v1/numbers` devolve) ou o **id da Meta** (o `metaPhoneNumberId`). Os dois valem. - `to` é o telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Por exemplo, `5511999990000`. Nesta versão a Luna começa conversa só com telefones do Brasil: começam por `55` e têm 12 ou 13 dígitos. Outro formato (sem DDI, ou de outro país) responde `400` com `campos: [{campo: "to"}]`, salvo para quem já escreveu para o seu número: essa conversa continua respondível. - A resposta é `202` com o `id` da mensagem na Luna e `status: "queued"`. Ela existe antes de a Meta responder. ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "text": { "body": "Olá! Recebemos seu pedido e já estamos preparando." } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID(), }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "text": { "body": "Olá! Recebemos seu pedido e já estamos preparando." } }), }); console.log(res.status, await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "text": { "body": "Olá! Recebemos seu pedido e já estamos preparando.", }, }, timeout=10, ) print(res.status_code, res.json()) ``` Resposta `202` ```json { "id": "ae60f288-7565-4315-a440-3663e9c231e1", "status": "queued" } ``` O texto vai até 4096 caracteres, o mesmo limite da Cloud API. A Luna conta em unidades UTF-16, então um emoji pode contar 2: a documentação da Meta não diz como ela conta, e a Luna prefere recusar a mais a deixar a Meta recusar depois. Com `preview_url: true` em `text`, a Meta busca a primeira URL do texto para montar uma prévia. Ele vem desligado. ### Por que `202` e não `200` O limite que mais aperta na plataforma da Meta é o do mesmo destinatário: ela tolera uma rajada curta e, passada a rajada, uma mensagem a cada seis segundos. A Luna opera com folga sobre esses números (rajada de 30 e uma a cada 7 segundos), então as primeiras mensagens de uma conversa saem na hora e só as seguintes esperam. Um agente que responde em rajada dispara isso sozinho. A Luna aceita, enfileira e entrega à Meta no ritmo que ela permite, e esse limite nunca volta para você como `429`. O `wamid` e o estado de entrega chegam depois, pelo webhook. Todos os limites, com os números, estão em [Limites e ritmo](https://lunahia.com.br/docs/limites-e-ritmo). ### Qual identificador usar Todo lugar que recebe um **número** aceita os dois identificadores dele: o UUID da Luna (o `id` de `GET /v1/numbers`) e o id da Meta (o `metaPhoneNumberId`, o mesmo que os eventos trazem em `phone_number_id`). Use o que o seu sistema já guarda. Um id que não é seu responde `404` (ou lista vazia, num filtro), igual a um que não existe. | Onde | Qual identificador | | --- | --- | | `POST /v1/messages`, `from` | O número: UUID da Luna ou id da Meta. | | As rotas `/v1/numbers/{id}`, `.../health` e `.../media` | O número: UUID da Luna ou id da Meta. | | O filtro `phoneNumberId` de `GET /v1/messages`, `/v1/conversations` e `/v1/templates` | O número: UUID da Luna ou id da Meta. | | O filtro `externalId` de mensagens, conversas, links e números | O rótulo que você deu ao cliente. Filtra tudo que é dele, sem você guardar o mapa de números. | | `GET /v1/messages/{id}` | O `id` da mensagem na Luna, o mesmo que o `202` devolveu. | | `reaction.message_id` | O `wamid` da mensagem que recebe a reação. | ## Marcar como lida e mostrar “digitando” As duas rotas agem sobre uma mensagem **recebida**, e são síncronas: respondem `200` quando a Meta aceita. A razão é que um sinal desses perde o valor com o tempo. Escopo `messages:write`. ```bash curl -X POST "https://api.lunahia.com.br/v1/messages/YOUR_MESSAGE_ID/read" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages/YOUR_MESSAGE_ID/read', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages/YOUR_MESSAGE_ID/read", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` ```bash curl -X POST "https://api.lunahia.com.br/v1/messages/YOUR_MESSAGE_ID/typing" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages/YOUR_MESSAGE_ID/typing', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages/YOUR_MESSAGE_ID/typing", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` - Mensagem que você enviou, mensagem que não é sua e mensagem que não existe respondem `404`, todas iguais. - A plataforma da Meta não tem indicador de digitando isolado. Chamar `/typing` **também marca a mensagem como lida**. Não há como fazer uma coisa sem a outra. - O indicador some sozinho quando você responde, com teto de 25 segundos do lado da Meta. Não há rota para desligá-lo, e não é preciso. ### Uma etiqueta sua no envio Mande `callbackData` (de 1 a 512 caracteres) em `POST /v1/messages` para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna o repassa à Meta (`biz_opaque_callback_data`, [documentação da Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status)), guarda com a mensagem e o devolve como veio em `callback_data` de **todo** `message.status` (`sent`, `delivered`, `read`, `failed`) e em `callbackData` de `GET /v1/messages` e `GET /v1/messages/{id}`. Vale em qualquer tipo de mensagem, inclusive template, e com a chave de teste os estados simulados o trazem também. A Luna não o interpreta. **Não ponha dado pessoal nele**: ele viaja em cada evento. ### Digitando no próprio envio Para uma resposta parecer escrita por uma pessoa, mande `typingMs` (de 1 a 25000, em milissegundos) em `POST /v1/messages`. A Luna liga o indicador de digitando na **última mensagem que o contato mandou**, espera esse tempo e só então envia. A espera não segura as outras conversas do seu número: a ordem da conversa é a de sempre, e o `202` volta na hora. - Só vale dentro da janela de atendimento. Se a conversa não tem mensagem recebida nas últimas 24 horas (por exemplo, um template para iniciar conversa), a Luna **ignora** `typingMs` e envia na hora, sem erro. - Como em `/typing`, ligar o indicador **também marca aquela mensagem recebida como lida**. - Se a Meta recusar o indicador, a mensagem sai mesmo assim, sem esperar. Durante a espera a mensagem ainda está na fila e pode ser cancelada com `DELETE /v1/messages/{id}`. - A espera conta no tempo até o envio: o evento `sent` chega `typingMs` depois, mais o tempo normal da fila. ## A janela de 24 horas Texto livre só sai para quem escreveu para o seu número nas últimas 24 horas. Fora dessa janela, o único caminho é um **template aprovado pela Meta**. Enviar o template não reabre a janela: ela abre quando o contato escreve ou liga para o seu número, e a cada novo contato dele recomeça. Até lá, texto livre continua recusado. Template e reação passam mesmo com a janela fechada. (O [glossário](https://lunahia.com.br/docs/glossario#janela) tem a definição curta.) A Luna aplica a regra por você: fora da janela, a mensagem livre é recusada com `409` **antes** de qualquer ida à Meta, porque uma chamada recusada lá é gasta à toa e conta como erro contra o seu número. Resposta `409` ```json { "error": "window_closed", "message": "A janela de atendimento desta conversa está fechada. Só é possível enviar mensagem livre até 24 horas depois da última mensagem do contato.", "fechadaEm": "2026-10-05T14:02:11.482Z", "acaoRecomendada": "Para falar com este contato agora, envie um template aprovado. A mensagem livre volta a ser aceita quando o contato responder, porque é a resposta dele que abre a janela. Se este contato escreveu há pouco e a janela devia estar aberta, confira o campo to: use o telefone do evento recebido (wa_id). A Luna já acha a conversa do celular brasileiro com e sem o nono dígito, mas qualquer outra diferença no telefone não encontra a conversa. Se o contato escreveu sem telefone (só com BSUID), envie com recipient igual ao user_id do evento, e não com to." } ``` Esta resposta não traz `Retry-After`, e de propósito: a janela não abre com o tempo. Ela abre quando o contato escreve ou liga, e enviar um template não a abre. Repetir o pedido só repete a recusa. Se o contato escreveu há pouco e mesmo assim a janela aparece fechada, confira o `to`: use o telefone do evento (`wa_id`). A Meta entrega alguns celulares brasileiros sem o nono dígito (`553190009991`) e outros com ele (`5531990009991`), e a Luna acha a conversa nas duas grafias: o envio de texto vai para o `wa_id` que a Meta usou, e cai na mesma conversa. Qualquer outra diferença no telefone (um dígito trocado, sem o DDD) não acha a conversa, e a Luna a vê como um contato que nunca escreveu. O template não consulta a conversa e vai para o telefone como você o escreveu. Se o contato escreveu **sem telefone** (só com BSUID), o `wa_id` do evento é nulo: envie com `recipient`, igual ao `user_id` do evento, e não com `to`. Veja [Usuários sem telefone (BSUID)](https://lunahia.com.br/docs/usuarios-sem-telefone). ### Veja a janela antes de enviar `GET /v1/conversations` devolve uma linha por interlocutor, por número, da mais ativa para a mais parada. Escopo `messages:read`. Cada conversa traz `numberId` (o número da Luna, o mesmo id de `GET /v1/numbers`, igual a `phoneNumberId`), `externalId` (o rótulo que você deu ao cliente dono do número, ou nulo) e `contactName`, o nome que o interlocutor exibe no WhatsApp, como a Meta o mandou na última mensagem recebida que trouxe um (nulo se ele nunca mandou). Para achar as conversas de uma pessoa, filtre por `?waId=`, com igualdade exata (o celular do Brasil vale com e sem o nono dígito): devolve a conversa dela em cada número. ```bash curl -X GET "https://api.lunahia.com.br/v1/conversations?phoneNumberId=YOUR_NUMBER_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/conversations?phoneNumberId=YOUR_NUMBER_ID', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/conversations?phoneNumberId=YOUR_NUMBER_ID", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` Resposta `200` (resumida) ```json { "data": [ { "id": "0f2c8e6a-1d3b-4a5c-9e7f-2b4d6a8c0e12", "waId": "5511999990000", "phoneNumberId": "7a1c9d3e-5f2b-4c8a-9d6e-1b3f5a7c9e11", "displayNumber": "+55 11 99999-0000", "lastMessage": { "direction": "inbound", "type": "text", "bodyText": "Oi! Queria saber o status do meu pedido.", "createdAt": "2026-10-06T14:02:11.482Z" }, "windowOpen": true, "windowExpiresAt": "2026-10-07T14:02:11.482Z", "windowSource": "usuario" } ], "nextCursor": null } ``` - `windowOpen: true` quer dizer que você pode mandar mensagem livre para aquele interlocutor agora. `false` quer dizer que o caminho é um template. - `windowExpiresAt` diz quando a janela fecha, e `windowSource` diz o que a abriu: `usuario`, `anuncio` ou `desconhecido`. O valor `template` existe no vocabulário e não é mais gravado, porque enviar um template não abre a janela. Quando não há janela conhecida, os campos vêm nulos ou falsos, e nunca ausentes. - O `id` da conversa é o que `GET /v1/messages?conversationId=` aceita. O filtro `phoneNumberId` aceita o UUID da Luna ou o id da Meta, e `externalId` filtra pelos números de um cliente seu. - Uma limitação que vale conhecer: o agrupamento é pelo `waId` que a plataforma gravou. Se o identificador que a Meta registrou difere do que foi digitado no envio, a mesma pessoa pode aparecer em duas conversas. - A resposta não traz contagem nenhuma: nem total, nem contador por interlocutor. ## Idempotência Mande o cabeçalho `Idempotency-Key` se você retenta. Com ele, repetir o pedido não produz segundo envio. O exemplo de texto acima já o manda, com um UUID novo a cada chamada. - O cabeçalho é opcional. Quem não retenta não precisa dele. - O formato aceito é de 1 a 255 caracteres visíveis, sem espaço (um UUID cabe de sobra). Um cabeçalho vazio, maior que isso ou com espaço responde `400` com `campos: [{campo: "Idempotency-Key"}]`, e nada é enviado. Se você não quer idempotência, não mande o cabeçalho. - A chave é um valor que **você** escolhe para cada mensagem lógica. Um UUID para cada mensagem serve. Reuse a mesma chave só ao retentar a mesma mensagem. - A mesma chave com o **mesmo corpo** devolve a mensagem original, com o mesmo `202` e o mesmo `id`. A mesma chave com um **corpo diferente** responde `409` com `error: "idempotency_key_reused"`, e nada é enviado: uma chave identifica uma mensagem, e não uma conversa. Para uma mensagem nova, use uma chave nova. - **Para um agente de IA, a chave é determinística.** Em vez de um UUID novo a cada tentativa, use uma chave que nasce da mensagem que você responde, como `resp-`, com o `id` da mensagem recebida. A entrega do webhook é pelo menos uma vez, e o seu tratamento pode rodar duas vezes para o mesmo evento: com a mesma chave, as duas tentativas viram uma só resposta. O laço completo está em [Agente de IA](https://lunahia.com.br/docs/agente-de-ia#idempotencia). - O escopo da chave é o seu cliente: a mesma chave em dois clientes é aceita nos dois. - A garantia vale também quando a retentativa atravessa a virada do mês. ## Responder citando Para responder a uma mensagem específica, de modo que o contato veja a citação, mande `context.message_id` em qualquer envio de texto, mídia, localização, contatos ou interativa. Ele aceita o `id` da Luna (o `message.id` do evento `message.received`, ou o `id` que este envio devolveu) **ou** o `wamid` da Meta. A Luna troca o `id` pelo `wamid` antes de enviar. ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "text": { "body": "Sim, o seu pedido sai hoje." }, "context": { "message_id": "YOUR_MESSAGE_ID" } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID(), }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "text": { "body": "Sim, o seu pedido sai hoje." }, "context": { "message_id": "YOUR_MESSAGE_ID" } }), }); console.log(res.status, await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "text": { "body": "Sim, o seu pedido sai hoje.", }, "context": { "message_id": "YOUR_MESSAGE_ID", }, }, timeout=10, ) print(res.status_code, res.json()) ``` - **Template e reação não aceitam.** A Meta não permite citar nesses dois tipos, e a Luna responde `400` com `campo: "context"` e o motivo, antes de enfileirar. - **O `id` precisa ser de uma mensagem da mesma conversa**: o mesmo número e o mesmo destinatário. Um `id` que não existe, que é de outro cliente ou de outra conversa responde `400` com `campo: "context.message_id"`. - **A mensagem citada precisa já ter sido aceita pela Meta.** Uma mensagem que você acabou de enviar só tem `wamid` depois de `sent`. Antes disso a Luna responde `400` e pede para tentar de novo. - Com `Idempotency-Key`, repetir o pedido citando pelo `id` ou pelo `wamid` da mesma mensagem conta como o mesmo corpo. ## Os tipos de mensagem Todos usam `POST /v1/messages` com `from`, `to` e `type`. Abaixo, só o que muda em cada tipo. Todos, menos reação e template, exigem a janela aberta. > **O corpo é estrito.** Um campo que a Luna não conhece, em qualquer nível, responde `400` com o nome do campo e o motivo `Campo não reconhecido por esta rota.`, em vez de ser descartado em silêncio. Se o seu envio chegou com `202`, todo campo que você mandou foi lido. Por isso o que pertence ao tipo vai **dentro do objeto do tipo**, e nunca no topo do corpo: `image.caption`, `document.filename`, `location.latitude`. ### Texto `type: "text"` (ou omitido), com `text.body` de 1 a 4096 caracteres. É o exemplo da seção anterior. ### Imagem `type: "image"`, com `image.link` **ou** `image.id`, nunca os dois. `image.caption` de até 1024 caracteres. Veja [mídia](#midia) para escolher entre `link` e `id`. ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "image", "image": { "link": "https://example.com/pedido.jpg", "caption": "Seu pedido saiu para entrega." } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "image", "image": { "link": "https://example.com/pedido.jpg", "caption": "Seu pedido saiu para entrega." } }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "image", "image": { "link": "https://example.com/pedido.jpg", "caption": "Seu pedido saiu para entrega.", }, }, timeout=10, ) print(res.status_code, res.json()) ``` ### Documento `type: "document"`, com `document.link` ou `document.id`. `document.filename` (até 240 caracteres) é o nome com que o arquivo aparece para quem recebe, e `document.caption` tem até 1024. ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "document", "document": { "id": "YOUR_MEDIA_ID", "filename": "nota-fiscal.pdf", "caption": "Sua nota fiscal." } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "document", "document": { "id": "YOUR_MEDIA_ID", "filename": "nota-fiscal.pdf", "caption": "Sua nota fiscal." } }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "document", "document": { "id": "YOUR_MEDIA_ID", "filename": "nota-fiscal.pdf", "caption": "Sua nota fiscal.", }, }, timeout=10, ) print(res.status_code, res.json()) ``` ### Vídeo `type: "video"`, com `video.link` ou `video.id`, e `video.caption` de até 1024 caracteres. ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "video", "video": { "id": "YOUR_MEDIA_ID", "caption": "Veja como montar." } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "video", "video": { "id": "YOUR_MEDIA_ID", "caption": "Veja como montar." } }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "video", "video": { "id": "YOUR_MEDIA_ID", "caption": "Veja como montar.", }, }, timeout=10, ) print(res.status_code, res.json()) ``` ### Áudio `type: "audio"`, com `audio.link` ou `audio.id`. Áudio não tem legenda. ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "audio", "audio": { "id": "YOUR_MEDIA_ID" } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "audio", "audio": { "id": "YOUR_MEDIA_ID" } }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "audio", "audio": { "id": "YOUR_MEDIA_ID", }, }, timeout=10, ) print(res.status_code, res.json()) ``` **Mensagem de voz.** Com `audio.voice: true`, o áudio chega como mensagem de voz (a bolinha com a forma de onda), e não como arquivo. A Meta exige um arquivo **.ogg com codec OPUS**. A Luna não converte áudio: converta antes de enviar. Se `audio.link` termina numa extensão de áudio que não é OGG, como `.mp3`, a Luna responde `400` e diz isso, em vez de gastar o envio. Com `audio.id`, a Luna não vê o tipo do arquivo, e a conferência é da Meta: o arquivo errado volta como `message.status` com `failed`. ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "audio", "audio": { "link": "https://example.com/resposta.ogg", "voice": true } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "audio", "audio": { "link": "https://example.com/resposta.ogg", "voice": true } }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "audio", "audio": { "link": "https://example.com/resposta.ogg", "voice": True, }, }, timeout=10, ) print(res.status_code, res.json()) ``` Converter um MP3 (por exemplo, a voz de um sintetizador) para OGG com OPUS, com o ffmpeg ```text ffmpeg -i entrada.mp3 -c:a libopus -b:a 32k -ar 48000 -ac 1 saida.ogg ``` ### Figurinha `type: "sticker"`, com `sticker.link` ou `sticker.id`. ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "sticker", "sticker": { "id": "YOUR_MEDIA_ID" } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "sticker", "sticker": { "id": "YOUR_MEDIA_ID" } }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "sticker", "sticker": { "id": "YOUR_MEDIA_ID", }, }, timeout=10, ) print(res.status_code, res.json()) ``` ### Localização `type: "location"`, com `location.latitude` (de -90 a 90) e `location.longitude` (de -180 a 180), e `location.name` e `location.address` opcionais, de até 1000 caracteres. ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "location", "location": { "latitude": -19.9227, "longitude": -43.9451, "name": "Praça da Liberdade", "address": "Belo Horizonte, MG" } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "location", "location": { "latitude": -19.9227, "longitude": -43.9451, "name": "Praça da Liberdade", "address": "Belo Horizonte, MG" } }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "location", "location": { "latitude": -19.9227, "longitude": -43.9451, "name": "Praça da Liberdade", "address": "Belo Horizonte, MG", }, }, timeout=10, ) print(res.status_code, res.json()) ``` ### Contatos `type: "contacts"`, com uma lista de um a vinte cartões. Cada cartão exige `name.formatted_name`, e aceita `phones`, `emails`, `addresses`, `urls`, `org` e `birthday` (`AAAA-MM-DD`). ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "contacts", "contacts": [ { "name": { "formatted_name": "Ana Souza", "first_name": "Ana", "last_name": "Souza" }, "phones": [ { "phone": "+55 11 99999-0001", "type": "CELL" } ] } ] }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "contacts", "contacts": [ { "name": { "formatted_name": "Ana Souza", "first_name": "Ana", "last_name": "Souza" }, "phones": [ { "phone": "+55 11 99999-0001", "type": "CELL" } ] } ] }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "contacts", "contacts": [ { "name": { "formatted_name": "Ana Souza", "first_name": "Ana", "last_name": "Souza", }, "phones": [ { "phone": "+55 11 99999-0001", "type": "CELL", }, ], }, ], }, timeout=10, ) print(res.status_code, res.json()) ``` ### Reação `type: "reaction"`, com o `wamid` da mensagem que recebe a reação em `reaction.message_id` e o `emoji`. Mande `emoji` vazio para remover uma reação que você já tinha posto. Passa mesmo com a janela fechada. ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "reaction", "reaction": { "message_id": "wamid.EXAMPLE_NOT_A_REAL_ID", "emoji": "👍" } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "reaction", "reaction": { "message_id": "wamid.EXAMPLE_NOT_A_REAL_ID", "emoji": "👍" } }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "reaction", "reaction": { "message_id": "wamid.EXAMPLE_NOT_A_REAL_ID", "emoji": "👍", }, }, timeout=10, ) print(res.status_code, res.json()) ``` ### Interativa: botões de resposta `type: "interactive"` com `interactive.type: "button"`. De um a três botões. O `id` de cada botão (até 256 caracteres) volta no evento `message.received` quando ele é tocado, em `message.interactive.id`, e o `title` tem até 20 caracteres. O corpo (`body.text`) vai até 1024, e o rodapé (`footer.text`) até 60. O cabeçalho (`header`) é opcional, e pode ser texto (até 60 caracteres), imagem, vídeo ou documento. ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "button", "body": { "text": "Podemos confirmar a entrega para amanhã?" }, "action": { "buttons": [ { "type": "reply", "reply": { "id": "confirma", "title": "Confirmar" } }, { "type": "reply", "reply": { "id": "remarca", "title": "Remarcar" } } ] } } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "button", "body": { "text": "Podemos confirmar a entrega para amanhã?" }, "action": { "buttons": [ { "type": "reply", "reply": { "id": "confirma", "title": "Confirmar" } }, { "type": "reply", "reply": { "id": "remarca", "title": "Remarcar" } } ] } } }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "button", "body": { "text": "Podemos confirmar a entrega para amanhã?", }, "action": { "buttons": [ { "type": "reply", "reply": { "id": "confirma", "title": "Confirmar", }, }, { "type": "reply", "reply": { "id": "remarca", "title": "Remarcar", }, }, ], }, }, }, timeout=10, ) print(res.status_code, res.json()) ``` ### Interativa: lista `interactive.type: "list"`. `action.button` é o rótulo do botão que abre a lista (até 20 caracteres). De uma a dez seções, e de uma a dez linhas por seção. Cada linha tem `id` (até 200), `title` (até 24) e `description` opcional (até 72). O `title` da seção tem até 24 caracteres. ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "list", "body": { "text": "Qual horário fica melhor?" }, "action": { "button": "Ver horários", "sections": [ { "title": "Manhã", "rows": [ { "id": "h09", "title": "09:00" }, { "id": "h10", "title": "10:00", "description": "Primeiro horário livre" } ] } ] } } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "list", "body": { "text": "Qual horário fica melhor?" }, "action": { "button": "Ver horários", "sections": [ { "title": "Manhã", "rows": [ { "id": "h09", "title": "09:00" }, { "id": "h10", "title": "10:00", "description": "Primeiro horário livre" } ] } ] } } }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "list", "body": { "text": "Qual horário fica melhor?", }, "action": { "button": "Ver horários", "sections": [ { "title": "Manhã", "rows": [ { "id": "h09", "title": "09:00", }, { "id": "h10", "title": "10:00", "description": "Primeiro horário livre", }, ], }, ], }, }, }, timeout=10, ) print(res.status_code, res.json()) ``` ### Interativa: botão com link `interactive.type: "cta_url"`. Um botão com `display_text` (até 20 caracteres) e `url` (até 2048), em `action.parameters`. ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "cta_url", "body": { "text": "Acompanhe o seu pedido pelo link." }, "action": { "parameters": { "display_text": "Acompanhar", "url": "https://example.com/pedido/88213" } } } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "cta_url", "body": { "text": "Acompanhe o seu pedido pelo link." }, "action": { "parameters": { "display_text": "Acompanhar", "url": "https://example.com/pedido/88213" } } } }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "cta_url", "body": { "text": "Acompanhe o seu pedido pelo link.", }, "action": { "parameters": { "display_text": "Acompanhar", "url": "https://example.com/pedido/88213", }, }, }, }, timeout=10, ) print(res.status_code, res.json()) ``` ### Interativa: pedido de localização `interactive.type: "location_request_message"`. Só o `body.text` (até 1024 caracteres): a Luna põe a ação `send_location`, que mostra ao contato o botão "Enviar localização". A resposta chega em `message.received` com `type: "location"`, no campo `message.location`. ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "location_request_message", "body": { "text": "Para calcular o frete, compartilhe a sua localização." } } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "location_request_message", "body": { "text": "Para calcular o frete, compartilhe a sua localização." } } }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "location_request_message", "body": { "text": "Para calcular o frete, compartilhe a sua localização.", }, }, }, timeout=10, ) print(res.status_code, res.json()) ``` ### Interativa: pedido de endereço `interactive.type: "address_message"`, com `body.text` e, em `action.parameters`, o `country` (duas letras, o padrão é `BR`) e, se quiser, `values` (campos já preenchidos), `saved_addresses` (até 20) e `validation_errors`. Os nomes dos campos do endereço são os que a Meta define para o país, e a Luna os repassa como vieram. **A Meta documenta este recurso para poucos países, e se ele vale para o Brasil está a confirmar na documentação da Meta**: quando não vale, a Meta recusa o envio e o motivo chega no evento `message.status`. ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "address_message", "body": { "text": "Confirme o endereço de entrega." }, "action": { "parameters": { "country": "BR" } } } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "address_message", "body": { "text": "Confirme o endereço de entrega." }, "action": { "parameters": { "country": "BR" } } } }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "address_message", "body": { "text": "Confirme o endereço de entrega.", }, "action": { "parameters": { "country": "BR", }, }, }, }, timeout=10, ) print(res.status_code, res.json()) ``` ### Interativa: carrossel de mídia `interactive.type: "carousel"`, com `body.text` e de dois a dez cartões em `action.cards`. Cada cartão tem `card_index` (de 0 a 9, sem repetir), `header` com uma imagem ou um vídeo (por `id` ou `link`, como em mídia), `body.text` opcional (até 160 caracteres) e um botão com link em `action.parameters` (`display_text` e `url`). Os limites de cartões e de texto são os da Meta e estão a confirmar na documentação dela. ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "carousel", "body": { "text": "Veja as novidades da semana." }, "action": { "cards": [ { "card_index": 0, "header": { "type": "image", "image": { "link": "https://example.com/camiseta.jpg" } }, "body": { "text": "Camiseta básica" }, "action": { "parameters": { "display_text": "Comprar", "url": "https://example.com/camiseta" } } }, { "card_index": 1, "header": { "type": "image", "image": { "link": "https://example.com/bone.jpg" } }, "body": { "text": "Boné" }, "action": { "parameters": { "display_text": "Comprar", "url": "https://example.com/bone" } } } ] } } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "carousel", "body": { "text": "Veja as novidades da semana." }, "action": { "cards": [ { "card_index": 0, "header": { "type": "image", "image": { "link": "https://example.com/camiseta.jpg" } }, "body": { "text": "Camiseta básica" }, "action": { "parameters": { "display_text": "Comprar", "url": "https://example.com/camiseta" } } }, { "card_index": 1, "header": { "type": "image", "image": { "link": "https://example.com/bone.jpg" } }, "body": { "text": "Boné" }, "action": { "parameters": { "display_text": "Comprar", "url": "https://example.com/bone" } } } ] } } }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "carousel", "body": { "text": "Veja as novidades da semana.", }, "action": { "cards": [ { "card_index": 0, "header": { "type": "image", "image": { "link": "https://example.com/camiseta.jpg", }, }, "body": { "text": "Camiseta básica", }, "action": { "parameters": { "display_text": "Comprar", "url": "https://example.com/camiseta", }, }, }, { "card_index": 1, "header": { "type": "image", "image": { "link": "https://example.com/bone.jpg", }, }, "body": { "text": "Boné", }, "action": { "parameters": { "display_text": "Comprar", "url": "https://example.com/bone", }, }, }, ], }, }, }, timeout=10, ) print(res.status_code, res.json()) ``` ### Interativa: Flow `interactive.type: "flow"`. O Flow precisa existir e estar publicado na conta de negócio do número, no Gerenciador do WhatsApp: a Luna só o **envia**, não cria nem publica Flows. Identifique-o com `flow_id` **ou** `flow_name` (exatamente um, senão `400`), dê o rótulo do botão em `flow_cta` e, para ligar a resposta a este envio, mande um `flow_token`. `flow_action_payload` abre o Flow numa tela (`screen`) com os `data` que você quiser. Use `mode: "draft"` para testar um Flow ainda não publicado. A resposta do contato chega em `message.received` como `interactive.type: "nfm_reply"`, com as respostas em `response_json`. Veja [Receber eventos](https://lunahia.com.br/docs/receber-eventos). ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "flow", "body": { "text": "Agende a sua visita em poucos toques." }, "action": { "parameters": { "flow_id": "1234567890", "flow_cta": "Agendar", "flow_token": "agendamento-88213", "flow_action_payload": { "screen": "INICIO", "data": { "nome": "Ana" } } } } } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "flow", "body": { "text": "Agende a sua visita em poucos toques." }, "action": { "parameters": { "flow_id": "1234567890", "flow_cta": "Agendar", "flow_token": "agendamento-88213", "flow_action_payload": { "screen": "INICIO", "data": { "nome": "Ana" } } } } } }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "flow", "body": { "text": "Agende a sua visita em poucos toques.", }, "action": { "parameters": { "flow_id": "1234567890", "flow_cta": "Agendar", "flow_token": "agendamento-88213", "flow_action_payload": { "screen": "INICIO", "data": { "nome": "Ana", }, }, }, }, }, }, timeout=10, ) print(res.status_code, res.json()) ``` ### Interativa: produto do catálogo `interactive.type: "product"` e `"product_list"`. A Luna só **envia** a mensagem de um catálogo que já existe na conta de negócio do número: ela não cria, lê nem edita catálogo ou produto. `action.catalog_id` é o identificador do catálogo, e `product_retailer_id` é o ID de conteúdo (o SKU) do produto nele. Se nenhum produto enviado existir no catálogo, a Meta recusa, e o motivo chega em `message.status` com `failed`. - `product` mostra um produto. `body` e `footer` são opcionais (corpo até 1024 caracteres, rodapé até 60), e não leva `header`. - `product_list` mostra uma lista: `header` (sempre `type: "text"`, até 60 caracteres) e `body` são obrigatórios, `footer` é opcional. `action.sections` tem de uma a dez seções, cada uma com `title` (até 24 caracteres) e `product_items`, e **no máximo 30 produtos no total**. Com mais de uma seção, todas precisam de `title`. Quebrar uma dessas regras responde `400` com o campo, antes do `202`. - Como toda interativa, exigem a janela de 24 horas aberta. Quando o cliente escolhe itens e envia o carrinho, a resposta chega em `message.received` com `order`. - Os limites de texto são os das outras interativas. A doc da Meta fixa o teto de 30 produtos; o resto é conferido por ela, e uma recusa dela chega como `failed`. ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "product", "body": { "text": "Esta é a ração que você pediu." }, "footer": { "text": "Estoque limitado" }, "action": { "catalog_id": "1234567890", "product_retailer_id": "RACAO-10KG" } } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "product", "body": { "text": "Esta é a ração que você pediu." }, "footer": { "text": "Estoque limitado" }, "action": { "catalog_id": "1234567890", "product_retailer_id": "RACAO-10KG" } } }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "product", "body": { "text": "Esta é a ração que você pediu.", }, "footer": { "text": "Estoque limitado", }, "action": { "catalog_id": "1234567890", "product_retailer_id": "RACAO-10KG", }, }, }, timeout=10, ) print(res.status_code, res.json()) ``` ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "product_list", "header": { "type": "text", "text": "Mais vendidos" }, "body": { "text": "Escolha à vontade." }, "action": { "catalog_id": "1234567890", "sections": [ { "title": "Rações", "product_items": [ { "product_retailer_id": "RACAO-10KG" }, { "product_retailer_id": "RACAO-3KG" } ] }, { "title": "Petiscos", "product_items": [ { "product_retailer_id": "OSSO-1" } ] } ] } } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "product_list", "header": { "type": "text", "text": "Mais vendidos" }, "body": { "text": "Escolha à vontade." }, "action": { "catalog_id": "1234567890", "sections": [ { "title": "Rações", "product_items": [ { "product_retailer_id": "RACAO-10KG" }, { "product_retailer_id": "RACAO-3KG" } ] }, { "title": "Petiscos", "product_items": [ { "product_retailer_id": "OSSO-1" } ] } ] } } }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "interactive", "interactive": { "type": "product_list", "header": { "type": "text", "text": "Mais vendidos", }, "body": { "text": "Escolha à vontade.", }, "action": { "catalog_id": "1234567890", "sections": [ { "title": "Rações", "product_items": [ { "product_retailer_id": "RACAO-10KG", }, { "product_retailer_id": "RACAO-3KG", }, ], }, { "title": "Petiscos", "product_items": [ { "product_retailer_id": "OSSO-1", }, ], }, ], }, }, }, timeout=10, ) print(res.status_code, res.json()) ``` ### Template `type: "template"`, com `template.name` e `template.language.code` (por exemplo `pt_BR`, que precisa bater com o idioma aprovado) e os `components` que preenchem as variáveis. É o que abre uma conversa fora da janela. Veja [Templates](https://lunahia.com.br/docs/templates#enviar). ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "template", "template": { "name": "confirmacao_de_pedido", "language": { "code": "pt_BR" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "parameter_name": "nome", "text": "Ana" } ] } ] } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID(), }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "template", "template": { "name": "confirmacao_de_pedido", "language": { "code": "pt_BR" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "parameter_name": "nome", "text": "Ana" } ] } ] } }), }); console.log(res.status, await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "template", "template": { "name": "confirmacao_de_pedido", "language": { "code": "pt_BR", }, "components": [ { "type": "body", "parameters": [ { "type": "text", "parameter_name": "nome", "text": "Ana", }, ], }, ], }, }, timeout=10, ) print(res.status_code, res.json()) ``` ## Mídia Imagem, vídeo, áudio, documento e figurinha aceitam duas formas de apontar o arquivo. Use uma ou outra, nunca as duas. - `link`: a URL pública do arquivo, que a Meta baixa no momento do envio. Ela precisa responder sem autenticação. - `id`: o identificador de um arquivo que você já subiu. Com ele a Meta não precisa baixar nada da sua infraestrutura, o envio fica mais rápido, e você reaproveita o mesmo arquivo em várias mensagens. A Meta retém o arquivo enviado por 30 dias. Depois disso, suba de novo. ### Áudio em MP3 A mensagem de voz (`audio.voice: true`) exige **OGG com codec OPUS**, e a Luna **não converte** áudio: converta antes de enviar ou de subir o arquivo. Quem tem a voz em MP3 (por exemplo, a saída de um sintetizador de fala) converte com o ffmpeg. O comando abaixo gera OPUS a 48 kHz em mono, que é o que a mensagem de voz do WhatsApp usa. Converter MP3 em OGG com OPUS ```text ffmpeg -i entrada.mp3 -c:a libopus -b:a 32k -ar 48000 -ac 1 saida.ogg ``` ### Subir um arquivo `POST /v1/numbers/{id}/media`, em `multipart/form-data`, no campo `file`. O `id` na URL é o do número **na Luna**. Escopo `messages:write`. A resposta traz o `mediaId`, e não uma URL: a URL de download da Meta expira em cinco minutos, e uma URL guardada nasce errada. ```bash curl -X POST "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/media" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -F "file=@./pedido.jpg;type=image/jpeg" ``` ```js import { readFile } from 'node:fs/promises'; const form = new FormData(); form.append( 'file', new Blob([await readFile('./pedido.jpg')], { type: 'image/jpeg' }), 'pedido.jpg', ); const res = await fetch('https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/media', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, body: form, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/media", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, files={"file": ("pedido.jpg", open("pedido.jpg", "rb"), "image/jpeg")}, timeout=10, ) print(res.status_code, res.json()) ``` Resposta `200` ```json { "mediaId": "1425835918205946" } ``` Um arquivo acima do teto da plataforma (100 MiB, o mesmo para todos os clientes) é recusado com `413` antes de qualquer ida à Meta. ### Baixar pelo link do aviso O aviso `message.received` (e o `message.echo`) já traz o link para baixar o arquivo em `message.media.url`, no formato `https://api.lunahia.com.br/v1/media/{token}`. Faça um `GET` nele, **sem** chave de API, e siga o redirecionamento: a resposta é um `302` para uma URL assinada que dura poucos minutos. - Quem tiver o link baixa o arquivo. Trate-o como dado sensível: não o registre em log, não o mande por canal que você não controla e não o guarde onde outras pessoas leiam. - O link é o mesmo em toda reentrega e em todo replay do aviso, e vale 30 dias contados do recebimento da mensagem. Depois disso, e para um link que não existe, a resposta é `404`. A mídia continua saindo por `GET /v1/messages/{id}/media`, com chave, até o fim da retenção de 90 dias. - O aviso pode chegar antes de a Luna terminar de baixar o arquivo da Meta. Nesse caso o link responde `409` com `error: "media_not_ready"`, `estado: "pendente"` e o cabeçalho `Retry-After`, em segundos: espere esse tempo e tente de novo. `falhou` e `expirado` também respondem `409`, sem `Retry-After`. - `url` é nula quando a mensagem não tem arquivo que a Luna consiga obter (a Meta não mandou identificador, ou o prazo de obtenção acabou). - A rota tem um teto de requisições por minuto por endereço de origem, o mesmo para todos. Baixando e salvando o arquivo pelo link, esperando enquanto a Luna ainda baixa: ```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")) ``` ### Baixar a mídia que o cliente enviou `GET /v1/messages/{id}/media` devolve uma URL assinada, emitida pela Luna, para a mídia que ela já guardou. Escopo `messages:read`. É o caminho com chave, que continua valendo ao lado do link do aviso: use-o para uma mensagem antiga, ou quando o link venceu. ```bash curl -X GET "https://api.lunahia.com.br/v1/messages/YOUR_MESSAGE_ID/media" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages/YOUR_MESSAGE_ID/media', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/messages/YOUR_MESSAGE_ID/media", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` Resposta `200` ```json { "url": "https://EXAMPLE.r2.cloudflarestorage.com/EXAMPLE_BUCKET/midia/EXAMPLE_KEY?X-Amz-Expires=300&X-Amz-Signature=EXAMPLE", "expiraEm": "2026-10-06T14:07:11.482Z" } ``` - A URL expira em poucos minutos e é uma credencial de portador: quem a tiver baixa o arquivo, sem apresentar chave. Não a guarde, não a registre em log e não a mande por canal que você não controla. Quando ela expirar, chame a rota de novo. - Se a mídia ainda não foi obtida, a resposta é `409` com `error: "media_not_ready"` e o `estado` atual, sem URL. `pendente` e `falhou` voltam sozinhos, porque a varredura retenta dentro da janela de sete dias da Meta. `expirado` é definitivo. - Uma mensagem **sem mídia** (de texto, por exemplo) responde `404 not_found`, o mesmo de uma mensagem que não existe ou que é de outro cliente: não há um erro à parte. O `409 media_not_ready` é só para a mídia que existe e ainda não foi obtida. - A URL aponta para o armazenamento da Luna, nunca para a Meta, e não tem o domínio da marca. Baixando e salvando o arquivo (a URL já vem assinada, então a segunda chamada **não** leva `Authorization`): ```js import { writeFile } from 'node:fs/promises'; const API = process.env.LUNA_API_URL ?? 'https://api.lunahia.com.br'; const KEY = process.env.LUNA_API_KEY; const EXTENSIONS = { 'image/jpeg': '.jpg', 'image/png': '.png', 'audio/ogg': '.ogg', 'application/pdf': '.pdf' }; // Baixa a mídia de uma mensagem recebida. async function downloadMedia(messageId) { const res = await fetch(API + '/v1/messages/' + messageId + '/media', { headers: { Authorization: 'Bearer ' + KEY }, }); if (res.status === 404) return null; // mensagem sem mídia responde 404, igual à que não existe if (res.status === 409) return null; // media_not_ready: a Luna ainda está buscando, tente de novo em alguns segundos if (!res.ok) throw new Error('media route answered ' + res.status); const link = await res.json(); // a URL já vem assinada e dura poucos minutos: sem cabeçalho Authorization const file = await fetch(link.url); const type = (file.headers.get('content-type') ?? '').split(';')[0]; const name = messageId + (EXTENSIONS[type] ?? ''); await writeFile(name, Buffer.from(await file.arrayBuffer())); return name; } console.log(await downloadMedia(process.env.LUNA_MESSAGE_ID)); ``` ```python import json import os import urllib.error import urllib.request API = os.environ.get("LUNA_API_URL", "https://api.lunahia.com.br") KEY = os.environ["LUNA_API_KEY"] EXTENSIONS = {"image/jpeg": ".jpg", "image/png": ".png", "audio/ogg": ".ogg", "application/pdf": ".pdf"} def download_media(message_id): # Baixa a mídia de uma mensagem recebida. req = urllib.request.Request( f"{API}/v1/messages/{message_id}/media", headers={"Authorization": f"Bearer {KEY}"}, ) try: with urllib.request.urlopen(req, timeout=15) as res: link = json.load(res) except urllib.error.HTTPError as err: if err.code == 404: return None # mensagem sem mídia responde 404, igual à que não existe if err.code == 409: return None # media_not_ready: a Luna ainda está buscando, tente de novo em alguns segundos raise # a URL já vem assinada e dura poucos minutos: sem cabeçalho Authorization with urllib.request.urlopen(link["url"], timeout=60) as file: data = file.read() extension = EXTENSIONS.get(file.headers.get_content_type(), "") name = message_id + extension with open(name, "wb") as out: out.write(data) return name print(download_media(os.environ["LUNA_MESSAGE_ID"])) ``` ## Acompanhe a entrega O caminho principal é o webhook: cada mudança de estado chega como `message.status`, e a falha também, inclusive a recusa que a Meta dá na própria resposta ao envio (nela o `wamid` do evento é nulo, e o `id` é a chave). Veja [Receber eventos](https://lunahia.com.br/docs/receber-eventos#eventos). Para consultar uma mensagem na hora, ou reconciliar, use `GET /v1/messages/{id}` (escopo `messages:read`). ```bash curl -X GET "https://api.lunahia.com.br/v1/messages/YOUR_MESSAGE_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages/YOUR_MESSAGE_ID', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/messages/YOUR_MESSAGE_ID", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` Resposta `200` ```json { "id": "ae60f288-7565-4315-a440-3663e9c231e1", "wamid": null, "content": null, "status": "failed", "criadaEm": "2026-10-06T14:02:11.000Z", "enviadaEm": null, "entregueEm": null, "lidaEm": null, "erros": [ { "codigo": 131026, "categoria": "nao_entregavel", "mensagem": "O destinatário não pode receber esta mensagem: o número não tem WhatsApp, ou não existe.", "acaoRecomendada": "Confira o número do destinatário e reenvie para o número correto. Repetir o envio para o mesmo número não muda o resultado.", "original": { "error": { "message": "Message undeliverable", "type": "OAuthException", "code": 131026, "fbtrace_id": "EXAMPLE_TRACE_ID" } } } ] } ``` - `wamid` é o identificador da Meta, o mesmo que os eventos trazem, e é nulo enquanto a Meta não aceitou o envio. `content` traz o que a mensagem carrega além do texto, nos dois sentidos. Na **recebida**, com os nomes da Meta, o mesmo conteúdo do evento `message.received`. Na **enviada**, o que você mandou, de volta, para o suporte responder "o que o robô mandou para esse cliente?": em `template`, o `name`, o `language` e os valores das variáveis (`variables`); em `sent_interactive`, o `body`, os botões (`buttons`) ou itens (`items`) e o endereço do botão de URL (`cta.url`); em `media`, a legenda e o `filename`, sem o link do arquivo; e `location`, `reaction`, `contacts` e `context` como na recebida. É nulo em mensagem de texto enviada (o texto está em `bodyText`). - `status` é o estado mais recente da mensagem enviada, na ordem da tabela abaixo. É nulo na mensagem recebida, que não tem estado de entrega. - `enviadaEm`, `entregueEm` e `lidaEm` são nulos enquanto a etapa não aconteceu. `lidaEm` também fica nulo quando o destinatário desliga a confirmação de leitura. - `erros` lista o que deu errado, em ordem de acontecimento, e vem vazio quando nada deu. Veja [Erros](https://lunahia.com.br/docs/erros#envio). - `pricing` é o custo que a Meta aplicou à mensagem, com os nomes dela (`billable`, `pricing_model`, `type`, `category`), e é nulo enquanto ela não o informou. Veja [Custos da Meta](https://lunahia.com.br/docs/custos-da-meta#conferir). - A resposta não traz contagem de tentativas nem qualquer número de consumo. ## Os estados da mensagem O estado só avança. Uma mensagem passa por eles nesta ordem, e pode pular etapas: a Meta não manda `delivered` quando a entrega e a leitura coincidem, então `sent` seguido de `read` é normal. | Estado | Onde aparece | Significa | | --- | --- | --- | | `queued` | Só na resposta `202` do envio | A mensagem foi aceita e está na fila de saída. É como a Luna chama o estado `accepted` na hora do aceite. | | `accepted` | `GET /v1/messages/{id}` e a lista, logo depois do `202` | Ainda na fila: a Meta não recebeu a mensagem. | | `sent` | Consulta e evento `message.status` | A Meta aceitou o envio. | | `delivered` | Consulta e evento | Chegou ao aparelho do destinatário. | | `read` | Consulta e evento | O destinatário leu. Não vem se ele desligou a confirmação de leitura. | | `played` | Consulta e evento | O destinatário reproduziu a mensagem de voz. | | `failed` | Consulta e evento | A mensagem não saiu ou não chegou. O motivo está em `erros` e, no evento, em `error_code`. É o estado mais alto: depois dele nada o substitui. | | `canceled` | Consulta e evento | Você cancelou a mensagem na fila com `DELETE /v1/messages/{id}` e a Meta nunca a recebeu. É terminal. Só quem ainda está em `accepted` pode ser cancelado; depois que o envio sai, a resposta é `409`. | ### O histórico `GET /v1/messages` devolve o que entrou e saiu, do mais recente ao mais antigo. Filtre por número com `phoneNumberId`, por cliente seu com `externalId`, por interlocutor com `conversationId` ou com `waId` (o telefone só com dígitos, e o celular do Brasil vale com e sem o nono dígito), e por `wamid` para achar a mensagem de um evento. Cada mensagem traz `content` com o que ela carrega além do texto: na recebida, o mesmo conteúdo do evento `message.received`; na enviada, o que você mandou (o template com as variáveis, os botões, a legenda). `limit` vai de 1 a 100. Para percorrer páginas, mande de volta o `nextCursor` da resposta anterior no parâmetro `cursor`. Quando ele vem nulo, acabou. O cursor é opaco: não tente construir um à mão. Parâmetro que a rota não conhece volta `400` com o nome dele. ```bash curl -X GET "https://api.lunahia.com.br/v1/messages?conversationId=YOUR_CONVERSATION_ID&limit=20" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages?conversationId=YOUR_CONVERSATION_ID&limit=20', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/messages?conversationId=YOUR_CONVERSATION_ID&limit=20", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` Resposta `200` (resumida) ```json { "data": [ { "id": "ae60f288-7565-4315-a440-3663e9c231e1", "direction": "outbound", "wamid": "wamid.EXAMPLE_NOT_A_REAL_ID", "type": "text", "bodyText": "Olá! Recebemos seu pedido e já estamos preparando.", "content": null, "status": "delivered", "waId": "5511999990000", "displayNumber": "+55 11 99999-0000", "createdAt": "2026-10-06T14:02:11.000Z" } ], "nextCursor": null } ``` > Ao receber `429`, `409` ou outro erro, veja [Erros](https://lunahia.com.br/docs/erros). O contrato completo de `POST /v1/messages` está na [referência da API](https://lunahia.com.br/docs/referencia), na seção Mensagens. ## Detalhes das rotas deste guia A [referência da API](https://lunahia.com.br/docs/referencia) diz como chamar cada rota, em poucas linhas. O que explica o motivo de cada decisão, os casos de borda e os avisos está aqui, na ordem da referência. ### GET /v1/messages Filtre por número com phoneNumberId, que aceita o UUID da Luna ou o id da Meta. Filtre por cliente seu com externalId, o rótulo que você deu no link de conexão: sai só o que passou pelos números dele. Filtre por interlocutor com conversationId, que é o id devolvido por GET /v1/conversations. Filtre por wamid, o identificador da Meta que os eventos de webhook trazem, para achar a mensagem de um evento. Filtre por waId, o telefone do interlocutor só com dígitos: o celular do Brasil vale com e sem o nono dígito. Filtre por userId, o BSUID do interlocutor, quando ele escreveu sem telefone. Parâmetro que a rota não conhece volta 400 com o nome dele, em vez de ser ignorado. Para percorrer páginas, mande de volta o nextCursor que veio na resposta anterior. Quando ele vem nulo, acabou. O campo content traz o que a mensagem carrega além do texto, nos dois sentidos. Na recebida, com os nomes de campo da Meta, os mesmos do evento message.received. Na enviada, o que você mandou, de volta: template (nome, idioma e valores das variáveis), sent_interactive (corpo, botões ou itens e o endereço do botão de URL), media (legenda e nome do arquivo, sem o link), location, reaction, contacts e context. Ele vem nulo em mensagem de texto enviada, que está em bodyText. O campo pricing traz o custo que a Meta aplicou à mensagem que você enviou, com os nomes dela, e vem nulo enquanto ela não o informou. Cada mensagem traz numberId (o número da Luna, o id de GET /v1/numbers), externalId (o rótulo do número), conversationId e errorSummary: quando a mensagem falhou, o código, a mensagem e a ação recomendada do último erro, sem o corpo original da Meta (ele continua em erros, em GET /v1/messages/{id}). Para achar o que falhou, filtre com ?status=failed. Também filtram ?direction= (inbound ou outbound), ?since= (inclusivo) e ?until= (exclusivo), em ISO 8601. createdAt é a data da mensagem: a que a Meta informou, quando ela é conhecida, e a de chegada na Luna nas demais. A conversa importada do histórico do aplicativo (coexistência) traz as datas reais, de até 180 dias atrás, e a ordem da lista, o ?since=, o ?until= e o cursor usam essa mesma data. Para buscar só o que chegou depois da última consulta, não use ?since=: uma mensagem importada depois tem data antiga. Use os eventos message.received e message.echo. O cursor é opaco: ele carrega posição, não contagem. Não tente construir um à mão. format=csv devolve text/csv, uma linha para cada mensagem devolvida, com os mesmos filtros e a mesma ordem: id, direction, wamid, type, bodyText, status, waId, userId, displayNumber, numberId, externalId, conversationId, errorCode, errorMessage e createdAt. Sem format=csv o limit vai até 100; com ele, o padrão e o máximo são 1000 linhas por chamada. Se houver mais, a próxima página vem no cabeçalho X-Luna-Next-Cursor (ausente na última): mande-o em cursor e repita até o cabeçalho sumir. O texto das mensagens vem de gente de fora; uma célula que começaria com =, +, - ou @ sai com um apóstrofo na frente, para a planilha não a executar como fórmula. ### POST /v1/messages Por que 202 e não 200: o limite que mais aperta na plataforma da Meta é o do mesmo destinatário: passada uma rajada curta, uma mensagem a cada seis segundos. Um agente que responde em rajada dispara isso sozinho. Enfileirar é o produto, e devolver 429 seria transferir o problema para você com outro nome. from é o número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. to é o telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Para responder a quem escreveu, use o wa_id que veio no evento: a Meta entrega alguns celulares brasileiros sem o nono dígito, e a Luna acha a conversa com e sem ele, mas nenhuma outra diferença no telefone, então a janela aparece fechada. Para quem escreveu sem telefone (BSUID), mande recipient com o user_id do evento, no lugar de to: um dos dois, nunca os dois, e nenhum responde 400. Um template de autenticação não vai para BSUID (a Meta exige o telefone) e é recusado com 400 antes da Meta. Veja [Usuários sem telefone (BSUID)](https://lunahia.com.br/docs/usuarios-sem-telefone). Mande o cabeçalho Idempotency-Key se você retenta. Com ele, repetir o pedido não produz segundo envio. A mesma chave com o mesmo corpo devolve a mensagem original; a mesma chave com um corpo diferente responde 409 idempotency_key_reused, e nada é enviado. A janela de atendimento é aplicada aqui: fora dela, mensagem livre é recusada com 409 antes de qualquer ida à Meta, porque uma chamada recusada por lá é gasta à toa e conta como erro contra o seu número. A resposta diz quando a janela fechou e o que fazer. Template e reação passam mesmo com a janela fechada. O template é o caminho para iniciar conversa fora dela, mas enviá-lo não reabre a janela: quem a reabre é o contato, ao escrever de volta. Até lá, texto livre continua recusado com 409. Consulte GET /v1/conversations para saber o estado da janela antes de tentar. Ao enviar um template com cabeçalho de mídia, a mídia vai no componente de cabeçalho do envio, e cada mensagem fornece a sua. O handle usado na criação do template é apenas o exemplo que a Meta revisa: ele não vira o conteúdo entregue, e não há nada a reaproveitar dele aqui. Para escolher entre link e identificador de mídia, vale a mesma recomendação publicada em POST /v1/numbers/{id}/media. Para responder citando uma mensagem, mande context.message_id com o id da Luna (o message.id do evento message.received, ou o id que um envio devolveu) ou com o wamid da Meta. A Luna troca o id pelo wamid antes de enviar. Só se cita mensagem da mesma conversa, e só uma que a Meta já aceitou. Template e reação não aceitam context: a resposta é 400, com o motivo. Para enviar áudio como mensagem de voz, mande audio.voice: true com um arquivo .ogg com codec OPUS. A Luna não converte áudio: um link cuja extensão é de outro formato de áudio, como .mp3, é recusado com 400. Para converter um MP3: ffmpeg -i entrada.mp3 -c:a libopus -b:a 32k -ar 48000 -ac 1 saida.ogg. O corpo é estrito: um campo que a Luna não conhece, em qualquer nível, responde 400 com o nome do campo, em vez de ser descartado em silêncio. Se o envio voltou 202, todo campo que você mandou foi lido. ### GET /v1/conversations A ordem é por atividade real e não por data de abertura: uma conversa aberta há meses e ativa hoje vem primeiro. lastMessage traz a mensagem mais recente daquela conversa, e ela é conteúdo, não resumo estatístico. A data de lastMessage e a ordem seguem a data da mensagem (a que a Meta informou, quando conhecida): uma conversa importada do histórico não sobe para o topo por ter sido importada hoje. Conversa que ainda não teve mensagem devolve lastMessage nulo e continua na lista. Cada linha diz se a janela de atendimento está aberta. windowOpen verdadeiro significa que você pode mandar mensagem livre para aquele interlocutor agora; falso significa que o caminho é enviar um template, e a mensagem livre volta a ser aceita quando o contato responder. windowExpiresAt diz quando ela fecha, e windowSource diz o que a abriu: usuario, anuncio ou desconhecido. Quando não há janela conhecida os três vêm nulos ou falsos, e nunca ausentes. Não sai contagem nenhuma daqui. Nem total, nem contador por interlocutor, nem agregado por período. O nextCursor carrega posição e não quantidade, e você não deve tentar construir um à mão. Filtre por número com phoneNumberId, que aceita o UUID da Luna ou o id da Meta. Filtre por cliente seu com externalId, o rótulo que você deu no link de conexão. Para percorrer páginas, mande de volta o nextCursor que veio na resposta anterior. Quando ele vem nulo, acabou. Filtre por interlocutor com waId (o telefone) ou userId (o BSUID). Desde o BSUID, waId pode ser null: quem escreveu sem que o telefone apareça tem a conversa identificada por userId, com parentUserId e username quando a Meta os manda. Quando a mesma conversa traz os dois, ela é uma só, e o id dela não mudou. Uma limitação que vale conhecer antes de integrar: o agrupamento é pelo waId, que é o identificador que a plataforma gravou para aquele interlocutor. Quando o identificador registrado pela Meta difere do que foi digitado no envio, o mesmo interlocutor humano aparece em duas conversas, com dois identificadores. A Luna devolve o que a plataforma gravou e não adivinha equivalência, porque adivinhar erraria nos dois sentidos. ### GET /v1/messages/{id}/media A URL expira em poucos minutos e é uma credencial de portador: quem a tiver baixa o arquivo, sem apresentar chave nenhuma. Não a guarde, não a coloque em log e não a mande por canal que você não controla. Quando ela expirar, chame esta rota de novo. A URL nunca aponta para a Meta. Ela aponta para o armazenamento da Luna, no domínio da API de objetos do provedor, porque URL assinada não funciona com domínio customizado. Não espere um domínio da marca aqui. Se a mídia ainda não foi obtida, a resposta é 409 com o estado atual e sem URL: pendente e falhou voltam sozinhos, porque a varredura retenta dentro da janela de sete dias da Meta; expirado é definitivo, porque passada essa janela o identificador não resolve mais e não há segunda chave. Mensagem que não é sua responde 404, igual a mensagem que não existe. ### GET /v1/media/{token} Quem tiver o link baixa o arquivo, sem chave. Trate-o como dado sensível: não o registre em log, não o mande por canal que você não controla e não o guarde onde outras pessoas leiam. O token tem 256 bits, e o endereço de origem das chamadas tem um teto por minuto, o mesmo para todos. O link vale por 30 dias contados do recebimento da mensagem. Depois disso, e para um token que não existe, a resposta é 404, a mesma nos dois casos. A mídia continua saindo por `GET /v1/messages/{id}/media`, com chave, até o fim da retenção de 90 dias. Mídia pronta responde 302 com `Location` para uma URL assinada que vale poucos minutos. Peça o link de novo (não a URL assinada) quando precisar baixar outra vez: cada chamada emite uma assinatura nova. A resposta traz `cache-control: no-store` e `referrer-policy: no-referrer`. O aviso pode chegar antes de a Luna terminar de baixar o arquivo da Meta. Nesse caso a resposta é 409 `media_not_ready` com `estado: "pendente"` e o cabeçalho `Retry-After`, em segundos: espere esse tempo e chame de novo. `falhou` e `expirado` também respondem 409, sem `Retry-After`. ### POST /v1/messages/{id}/read Esta rota é síncrona, ao contrário do envio. A razão é que confirmação de leitura perde valor com o tempo: a que chega meia hora depois já foi lida, do outro lado, como ausência de leitura. Enfileirá-la entregaria o sinal quando ele não significa mais nada. Só vale para mensagem recebida. Mensagem que você enviou, mensagem que não é sua e mensagem que não existe respondem 404 igual. Ela é uma chamada à plataforma como qualquer outra, e é contada no mesmo ritmo do seu número que o envio usa. ### POST /v1/messages/{id}/typing Esta rota é síncrona, e é a que mais depende disso: um indicador de digitando enfileirado seria entregue depois de a presença ter acabado. Não é entrega atrasada: é uma afirmação falsa sobre o presente. Saiba de uma coisa antes de integrar: a plataforma da Meta não tem indicador isolado. O indicador é campo do mesmo corpo que marca a mensagem como lida, e exige o identificador de uma mensagem recebida para saber em qual conversa exibir. Então chamar esta rota TAMBÉM marca aquela mensagem como lida. Não há como fazer uma coisa sem a outra. O indicador some sozinho quando você responde, com teto de vinte e cinco segundos do lado da Meta. Não existe rota para desligá-lo, e não é preciso. Ela é contada no mesmo ritmo do seu número que o envio usa. ### POST /v1/numbers/{id}/media O id na URL é o número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. Use o identificador no lugar de link ao enviar mídia: com ele a Meta não precisa baixar nada da sua infraestrutura, o envio fica mais rápido e você pode reaproveitar o mesmo arquivo em várias mensagens. O identificador vale trinta dias. Depois disso, suba o arquivo de novo. A resposta não traz URL, e isso é decisão e não omissão: a URL de download da Meta expira em cinco minutos, e uma URL guardada é um valor que já nasce errado, e o retry que a usasse falharia sempre, muito depois de a causa ter passado. Arquivo acima do teto é recusado com 413 antes de qualquer ida à Meta, para não gastar chamada sua. O teto é o mesmo para todos os clientes: ele existe por capacidade de infraestrutura, e não varia. ### GET /v1/messages/{id} O campo wamid é o identificador da Meta, o mesmo que os eventos de webhook trazem: é por ele que você liga um evento recebido a esta mensagem. Ele vem nulo enquanto a Meta não aceitou o envio. O campo erros traz a lista do que deu errado, em ordem de acontecimento. Cada item tem a explicação em português e a ação recomendada, e traz junto o campo original: o corpo de erro da Meta sem reescrita e sem filtro, que é o que o suporte dela reconhece. O fbtrace_id dentro dele é o que faz um chamado avançar quando a nossa explicação não bastar. Atenção ao repassar a resposta: o campo original pode conter o telefone do consumidor final e trechos da conversa. Trate-o com o mesmo cuidado do restante do conteúdo das mensagens antes de mandá-lo a terceiros. O campo content traz o que a mensagem carrega além do texto, nos dois sentidos. Na recebida, com os nomes de campo da Meta, os mesmos do evento message.received. Na enviada, o que você mandou, de volta: template (nome, idioma e valores das variáveis), sent_interactive (corpo, botões ou itens e o endereço do botão de URL), media (legenda e nome do arquivo, sem o link), location, reaction, contacts e context. Ele vem nulo em mensagem de texto enviada, que está em bodyText. A lista reúne o que a Meta recusou na hora do envio e o que ela informou depois, por evento de status. Você não precisa saber de qual das duas veio cada item: em ambos os casos ela recusou algo, e a ação recomendada é a que resolve. O campo pricing traz a classificação de custo que a Meta aplicou a esta mensagem, com os nomes dela. A resposta não traz contagem de tentativas nem qualquer número de consumo. Para o histórico completo das suas mensagens, use GET /v1/messages. Mensagem que não é sua responde 404, igual a mensagem que não existe. ### DELETE /v1/messages/{id} Só uma mensagem que ainda está na fila de saída (accepted) pode ser cancelada. Ela passa a canceled, um estado terminal que nada substitui, a Meta nunca a recebe, e o evento message.status com status canceled chega ao seu webhook. O 204 já é a confirmação: a mensagem não sai mais. O evento só sai quando chega a vez dela na fila da conversa, o que pode levar de alguns segundos a um minuto se havia muitas mensagens antes dela ou um typingMs longo. Cancelar e enviar nunca acontecem os dois: a Luna decide no banco, em uma escrita só, quem chegou primeiro. Se o envio já foi reservado ou a mensagem já saiu, a resposta é 409 message_not_cancelable, com o estado atual em status. Confira o resultado com GET /v1/messages/{id}. Só vale para mensagem que você enviou. Mensagem recebida, mensagem que não é sua e mensagem que não existe respondem 404 igual. ### POST /v1/messages/{id}/replay Cada pedido produz uma entrega nova, com deliveryId próprio. Chamar duas vezes produz duas entregas, e não um erro: o segundo pedido é um pedido, e não um clique repetido. Use o deliveryId para distinguir a reentrega que você pediu de uma reentrega automática por falha. O reenvio não fura a fila nem pula defesa nenhuma. Se o seu endpoint estiver fora do ar, a entrega será adiada e retentada pela política de sempre, sem que nenhuma requisição chegue a sair. Não adianta pedir em massa para acelerar. Mensagem recebida reenvia o message.received. Mensagem enviada reenvia o último message.status dela, igual ao original e marcado como reenvio pedido; se a Meta ainda não aceitou a mensagem ou nenhum status chegou, a resposta é 400. Se você ainda não cadastrou um endpoint de webhook, a resposta é 409: não há para onde entregar, e um 202 aqui seria uma confirmação que não se cumpre. Mensagem que não é sua responde 404, igual a mensagem que não existe. A resposta não traz contagem de nada, de propósito: nenhum número desta API alimenta cobrança. --- # 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-`. 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-`. 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-`. Uma segunda resposta à mesma mensagem (o fallback de template, por exemplo) leva outro sufixo: `resp--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). --- # Usuários sem telefone (BSUID) Fonte: https://lunahia.com.br/docs/usuarios-sem-telefone Quem adotou um nome de usuário no WhatsApp pode escrever para o seu cliente sem que o telefone dele apareça. A Meta identifica esse usuário por um BSUID. A Luna recebe, guarda e entrega o BSUID, e o seu sistema precisa tratar o telefone como opcional. ## O que é o BSUID O BSUID é o identificador do usuário que não depende do telefone. Tem o código do país (duas letras), um ponto e até 128 letras e números: `US.13491208655302741918`. O BSUID pai, que a Meta manda em alguns portfólios, tem `ENT` depois do país: `US.ENT.11815799212886844830`. **Guarde o valor inteiro, como veio**: a Luna e a Meta não o normalizam, e um valor alterado deixa de achar o usuário. O telefone continua existindo. A Meta o manda no webhook quando houve mensagem ou ligação nos dois sentidos nos últimos 30 dias, ou quando o usuário está no livro de contatos do portfólio. Fora disso, só o BSUID chega. **Não existe API que converta telefone em BSUID**, nem o contrário: a Luna não tem como descobrir um a partir do outro. ## O que muda nos eventos `message.received`, `message.status` e `message.echo` ganham três campos, sempre presentes e nulos quando não se aplicam: `user_id` (o BSUID), `parent_user_id` e `username`. E `wa_id` **pode ser nulo**: quando o usuário escreve sem telefone, o interlocutor é o `user_id`. Os valores chegam como a Meta mandou. Mensagem de quem não mostra o telefone ```json { "version": "2026-11-10", "event_id": "e2f81dd079e4419dac363779655be694a25cc502b7646be51cdac4b0cfc276fb", "event_type": "message.received", "occurred_at": "2026-11-03T14:02:11.482Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "message": { "id": "c8a1e5d2-6f3b-4a7c-9e0d-1b2c3d4e5f60", "wamid": "wamid.EXAMPLE_NO_PHONE", "wa_id": null, "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": "mariasouza", "type": "text", "text": "Oi! Queria saber o status do meu pedido.", "profile_name": "Maria Souza", "media": null, "interactive": null, "button": null, "location": null, "contacts": null, "reaction": null, "context": null, "referral": null, "unsupported": null, "edit": null, "revoke": null, "order": null } } ``` > **É uma mudança de contrato**, e por isso a versão dos eventos subiu para `2026-11-03` (e subiu de novo para `2026-11-04` com o conteúdo de entrada completo). `wa_id` deixou de ser sempre um texto: quem o lia sem checar o nulo precisa tratar o caso. Antes dela, a Luna não recebia a mensagem de quem escrevia sem telefone. Tipo novo de evento (`contact.identity_changed`, abaixo) não sobe a versão. No status de uma mensagem que você enviou por BSUID, `wa_id` também pode ser nulo e o `user_id` identifica o destinatário. O evento fica no mesmo grupo de ordem da conversa: a ordem dentro da conversa continua garantida. Status (com telefone e BSUID) ```json { "version": "2026-11-10", "event_id": "464e089a80690f1792db6249678ddeced5ad5be0d46d95e2daa263779f7d92e5", "event_type": "message.status", "occurred_at": "2026-10-06T14:02:14.090Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "message": { "id": "ae60f288-7565-4315-a440-3663e9c231e1", "wamid": "wamid.EXAMPLE_NOT_A_REAL_ID", "wa_id": "5511900000000", "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": null, "status": "sent", "error_code": null, "error": null, "pricing": { "billable": false, "pricing_model": "PMP", "type": "free_customer_service", "category": "service" }, "callback_data": "atendimento-8841" } } ``` ## Qual é a chave do contato no seu sistema Use o BSUID (`user_id`) como chave do contato quando ele vier, e o telefone como atributo. Quando a mensagem traz os dois, a Luna liga telefone e BSUID na **mesma conversa**: a conversa que você já tinha por telefone continua com o mesmo `id`, e passa a ter o `userId`. Nenhum histórico é reescrito. O telefone mais recente que o próprio usuário usou vence. Se uma conversa já tem outro telefone e chega uma mensagem do mesmo BSUID com um telefone novo, a Luna passa a usar o novo. Duas conversas nunca são fundidas: se o telefone novo já pertence a outra conversa do número, ele não é movido, e as duas conversas continuam, cada uma achável por uma das identidades. Uma conversa sem telefone em GET /v1/conversations ```json { "id": "0f2c8e6a-1d3b-4a5c-9e7f-2b4d6a8c0e12", "waId": null, "userId": "BR.13491208655302741918", "parentUserId": null, "username": "mariasouza", "numberId": "7a1c9d3e-5f2b-4c8a-9d6e-1b3f5a7c9e11", "windowOpen": true } ``` `GET /v1/conversations` e `GET /v1/messages` devolvem `userId`, `parentUserId` e `username`, e `waId` passa a poder ser `null`. Os dois ganham o filtro `userId`, que é igualdade exata e devolve lista vazia quando nada casa. `GET /v1/conversations?waId=` continua achando a conversa pelo telefone. ## Como responder a quem não tem telefone `POST /v1/messages` aceita `recipient`, o BSUID do destinatário, no lugar de `to`. Mande **um dos dois**: os dois juntos, ou nenhum, respondem 400. Para responder, use o `user_id` do evento recebido. Envio por BSUID ```json { "from": "123456789012345", "recipient": "BR.13491208655302741918", "text": { "body": "Oi, Maria! Seu pedido saiu para entrega." } } ``` - **A janela de 24 horas funciona igual.** Uma conversa só de BSUID abre a janela quando o usuário escreve, e texto livre fora dela responde 409 `window_closed`. Template passa fora da janela, como para qualquer destinatário. - **Template de autenticação não vai para BSUID.** Os templates de autenticação de um toque, zero toque e copiar código precisam do telefone. A Luna recusa com 400, antes da Meta, quando conhece o template, ele é de autenticação e o destino é `recipient`. Se ela não conhece o template (criado direto no painel da Meta), a Meta recusa com o erro `131062`. Envie esse template para o telefone, em `to`. - **Erro `131062`**: a Meta recusou o destinatário por BSUID para este envio. A Luna o devolve como não entregável, com a ação: enviar para o telefone, em `to`. Não adianta repetir por BSUID. - **Responder citando** exige a mesma conversa: cite uma mensagem da conversa do `recipient` que você está usando. > Se o seu cadastro tem o telefone de um contato que escreveu só com BSUID, **não** o use em `to` para responder: a Luna não sabe que os dois são a mesma pessoa, abriria outra conversa por telefone, com a janela fechada, e recusaria o texto livre. Use `recipient` com o `user_id` que você recebeu. ## Quando o contato troca de telefone ou de BSUID A Meta avisa a troca com uma mensagem de sistema (`user_changed_number` ou `user_changed_user_id`). A Luna liga a identidade nova à mesma conversa, não abre a janela de atendimento (não é uma mensagem que o usuário escreveu) e entrega o evento `contact.identity_changed`. Ele traz `previous_user_id` e `user_id`: use os dois para atualizar o contato no seu cadastro. Os campos que a Meta omite vêm nulos. Troca de BSUID ```json { "version": "2026-11-10", "event_id": "f73a65b1f155f86f94e0886ad29bac662a822fabf796b626cdf865c7060f0db9", "event_type": "contact.identity_changed", "occurred_at": "2026-11-03T15:20:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "contact": { "wamid": "wamid.EXAMPLE_IDENTITY_CHANGE", "change_type": "user_changed_user_id", "wa_id": null, "user_id": "BR.98765432109876543210", "previous_user_id": "BR.13491208655302741918", "parent_user_id": null, "previous_parent_user_id": null } } ``` ## O que a Luna não faz - Não converte telefone em BSUID nem BSUID em telefone: a Meta não oferece essa consulta. - Não funde duas conversas que, no seu cadastro, são a mesma pessoa. Isso é decisão do seu sistema, que tem os dois identificadores. - Não garante a ordem estrita dos eventos no instante em que uma conversa só de BSUID ganha o telefone: a chave de ordem muda uma vez, naquele momento, e eventos em voo de antes e de depois podem chegar em qualquer ordem entre si. A ordem dentro da conversa vale antes e depois dessa passagem. Os eventos estão em [Receber eventos](https://lunahia.com.br/docs/receber-eventos), o envio em [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens) e os erros em [Erros](https://lunahia.com.br/docs/erros). Cada campo de `GET /v1/conversations`, `GET /v1/messages` e `POST /v1/messages` está na [referência da API](https://lunahia.com.br/docs/referencia). --- # O que o número faz na Meta Fonte: https://lunahia.com.br/docs/numero-na-meta Cada número conectado tem, na Meta, um perfil que o contato vê, uma lista de quem foi bloqueado e códigos que abrem uma conversa. A Luna deixa você mexer nos três pela API, com o mesmo token do seu cliente, sem que ele precise abrir o painel da Meta. A [referência da API](https://lunahia.com.br/docs/referencia) traz cada rota e cada campo. Este guia explica o que a referência não cabe em poucas linhas: o que a Meta recusa, o que não vale em coexistência e o que ainda está a confirmar. ## O que vale para todas as rotas - O `id` na URL é o do número: o UUID da Luna (o `id` de `GET /v1/numbers`) ou o id da Meta (`metaPhoneNumberId`). Número de outro cliente, ou que não existe, responde o mesmo `404`. - Cada chamada gasta **uma** unidade do limite de gestão da Meta para a conta de negócio do número: 200 por hora, o mesmo balde da conexão e dos templates. Esgotado, a resposta é `429` com `Retry-After`. É um limite técnico da Meta, igual para todos. - Número desconectado da Luna responde `409` (`number_disconnected`). Conta suspensa recusa o que cria ou muda; apagar, desbloquear e ler seguem abertos. - Quando a Meta recusa o pedido (campo longo demais, fora da janela de 24 horas, autorização vencida), a resposta é `422` com `error: "meta_rejected"`. O campo `meta` traz o que aconteceu, o que fazer e o erro original dela. Falha da Meta (erro de servidor ou de rede) não vira `422`. - Nenhuma destas rotas aceita a chave de um cliente final: use a chave da sua conta. ## Perfil do negócio `GET /v1/numbers/{id}/profile` lê, e `PATCH` muda, o que o contato vê no WhatsApp: `about` (o recado curto), `address`, `description`, `email`, `websites`, `vertical` (o ramo, no vocabulário da Meta, sem lista fechada aqui) e a foto. A leitura devolve também `profilePictureUrl`, que é da Meta e pode expirar: baixe o arquivo se precisar guardá-lo. ```bash curl -X PATCH "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/profile" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "about": "Atendimento de segunda a sexta", "websites": [ "https://example.com" ] }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/profile', { method: 'PATCH', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "about": "Atendimento de segunda a sexta", "websites": [ "https://example.com" ] }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.patch( "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/profile", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "about": "Atendimento de segunda a sexta", "websites": [ "https://example.com", ], }, timeout=10, ) print(res.status_code, res.json()) ``` O `PATCH` troca só os campos que você mandar. `websites` aceita até dois e a lista inteira substitui a que existe. Para trocar a foto, mande `profilePictureHandle`, o handle de um arquivo subido pelo envio resumível da Meta: o mesmo handle que `POST /v1/template-assets` devolve serve, **o que está a confirmar na documentação da Meta**. Os limites de tamanho dos campos (139 caracteres no recado, 256 no endereço, 512 na descrição, 128 no e-mail) também estão a confirmar: a Luna só poupa a chamada que a Meta recusaria, e a Meta é a juíza. ## Nome de exibição O nome de exibição é o nome que o contato vê no topo da conversa, e a Meta o revisa. Ele não está no `profile`: está em `GET /v1/numbers/{id}` e em cada item de `GET /v1/numbers`. `displayName` é o nome em uso. `displayNameStatus` é o estado da revisão, em minúsculas: `approved`, `pending_review`, `declined`, `expired` ou `none`; novos valores podem aparecer, então não trate a lista como fechada. `pendingDisplayName` é o nome pedido que ainda não é o nome em uso (em revisão, recusado, ou aprovado à espera do novo registro). Os três são nulos até a Luna ler o número pela primeira vez, o que acontece em até cerca de uma hora. **A Meta não informa o motivo de uma recusa nessa consulta**, e a Luna não devolve um: o negócio vê o motivo no WhatsApp Manager, no gerenciador da Meta. Para pedir a mudança, mande `displayName` no `PATCH /v1/numbers/{id}/profile`, sozinho ou junto de outros campos do perfil. A resposta é `202`: o pedido foi aceito pela Meta e está em revisão, com `displayNameStatus: "pending_review"` e `pendingDisplayName` com o nome pedido. A Meta aceita até 10 mudanças de nome a cada 30 dias e recusa o pedido fora das regras dela, que volta como `422` com o erro original. Quando a revisão termina, o evento `number.display_name_reviewed` avisa. **Um nome aprovado só passa a valer depois que o número é registrado de novo** (`POST /{PHONE_NUMBER_ID}/register` na Meta), em até 14 dias da aprovação; passado o prazo, é preciso pedir de novo. A Luna ainda não oferece esse novo registro por rota: se o nome aprovado não aparecer em `displayName`, fale com o suporte. > **Número em coexistência não tem perfil pela API.** A Meta lista o perfil comercial entre o que deixa de funcionar quando o número continua no aplicativo do celular. A Luna recusa antes, com `409` e `error: "not_available_in_coexistence"`, sem gastar a chamada de gestão. Quem precisa mudar o perfil faz isso no aplicativo WhatsApp Business do celular do negócio. ## Bloquear usuários `POST /v1/numbers/{id}/blocked-users` bloqueia, `GET` lista e `DELETE /v1/numbers/{id}/blocked-users/{user}` desbloqueia. Cada usuário é um **telefone** (só dígitos, como em `to`) ou um **BSUID** (como o evento `message.received` o traz em `user_id`). Até 50 por chamada. O **BSUID pai** (`XX.ENT.…`) não bloqueia: a Luna recusa com `400` e diz a posição, sem repetir o valor. Essa regra vem do plano do produto e está a confirmar na documentação da Meta. ```bash curl -X POST "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/blocked-users" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "users": [ "5511900000000" ] }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/blocked-users', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "users": [ "5511900000000" ] }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/blocked-users", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "users": [ "5511900000000", ], }, timeout=10, ) print(res.status_code, res.json()) ``` Resposta `200` ```json { "done": [{ "input": "5511900000000", "waId": "5511900000000", "userId": null, "reasons": [] }], "failed": [] } ``` A resposta separa o que a Meta aceitou (`done`) do que ela recusou (`failed`, com `reasons`, o texto dela). **A Meta só deixa bloquear quem escreveu ao número nas últimas 24 horas**, e a Luna não confere isso antes: quem conhece a janela é a Meta, e o motivo volta por usuário. A lista (`GET`) usa `limit` e `cursor`, e o `nextCursor` é o da Meta. ## QR code e link curto `POST /v1/numbers/{id}/qr-codes` cria um código que abre uma conversa com o número, com `prefilledMessage` (até 140 caracteres, a confirmar na documentação da Meta) já escrita. Devolve o `code`, o `link` curto (wa.me) e, se você mandou `imageFormat` (`PNG` ou `SVG`), o `imageUrl`. `GET` lista os que existem e `DELETE /v1/numbers/{id}/qr-codes/{code}` apaga: quem ainda tem o QR impresso deixa de abrir a conversa. ```bash curl -X POST "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/qr-codes" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prefilledMessage": "Oi, quero um orçamento", "imageFormat": "PNG" }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/qr-codes', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "prefilledMessage": "Oi, quero um orçamento", "imageFormat": "PNG" }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID/qr-codes", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "prefilledMessage": "Oi, quero um orçamento", "imageFormat": "PNG", }, timeout=10, ) print(res.status_code, res.json()) ``` Resposta `201` ```json { "code": "4O4YGZEG3RIVE1", "prefilledMessage": "Oi, quero um orçamento", "link": "https://wa.me/message/4O4YGZEG3RIVE1", "imageUrl": "https://example.com/qr.png" } ``` A Luna não guarda nada: o código, o link e a imagem vivem na Meta. O `imageUrl` é da Meta e pode expirar, então baixe o arquivo na hora se for imprimir. Nenhuma rota devolve quantas vezes o código foi lido. ## Quando o contato pede para parar de receber marketing A Meta avisa pelo campo `user_preferences` que o usuário mudou uma preferência, hoje a de mensagens de marketing. A Luna entrega o aviso como o evento `contact.preferences_changed`, com o contato (`wa_id`, `user_id`, `username`, `profile_name`) e `preference` (`category`, `value`, `detail`, como a Meta mandou). **A Luna não bloqueia nenhum envio por causa dele**: o seu sistema guarda o pedido e para de mandar marketing a quem pediu. Veja o evento em [Receber eventos](https://lunahia.com.br/docs/receber-eventos). O evento ```json { "version": "2026-11-10", "event_id": "4236ccfb21e7cec359d1e1b5b5f3f8e65cb3e8a8db0fc86e4d95da037796e97c", "event_type": "contact.preferences_changed", "occurred_at": "2026-11-04T16:45:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "contact": { "wa_id": "5511900000000", "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": null, "profile_name": "Maria Souza" }, "preference": { "category": "marketing_messages", "value": "stop", "detail": "User requested to stop marketing messages" } } ``` > **O aviso só existe se o campo `user_preferences` estiver assinado no app da Meta.** Essa assinatura é feita no painel da Meta, e não por esta API. A forma exata do corpo que a Meta manda no campo está a confirmar na documentação dela, e a Luna lê com tolerância. --- # Modo de teste Fonte: https://lunahia.com.br/docs/modo-de-teste Para montar e testar a sua integração sem mandar mensagem de verdade, crie uma chave de teste. Com ela, enviar uma mensagem não vai à Meta, não usa número seu e não conta na capacidade do plano: a Luna devolve o mesmo `202` e entrega ao seu webhook os eventos que a Meta mandaria, simulados, assinados e marcados com `test: true`. A [referência da API](https://lunahia.com.br/docs/referencia) traz cada rota e cada campo. Este guia explica o que ela não cabe em poucas linhas: o que a chave de teste alcança, o que sai e quando, e o que o modo de teste não simula. ## Criar a chave de teste `POST /v1/api-keys` com `mode: "test"`. A resposta traz o segredo uma única vez, como em qualquer chave. O campo `mode` aparece também na lista de chaves (`live` ou `test`) e **não muda depois**: para sair do modo de teste, use outra chave. ```bash curl -X POST "https://api.lunahia.com.br/v1/api-keys" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "label": "teste da integração", "profile": "agent", "mode": "test" }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/api-keys', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "label": "teste da integração", "profile": "agent", "mode": "test" }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/api-keys", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "label": "teste da integração", "profile": "agent", "mode": "test", }, timeout=10, ) print(res.status_code, res.json()) ``` - A chave de teste é da conta inteira: `externalId` junto com `mode: "test"` responde `400`. - Ela **só usa duas rotas**: `POST /v1/messages` e `POST /v1/test-mode/inbound-messages`. Em qualquer outra, a resposta é `403` com `error: "test_key_not_allowed"`, antes de validar o corpo. É isso que garante que ela nunca lê nem muda número, conta ou template, e que nunca chega à Meta. - Os escopos valem como em qualquer chave: o envio pede `messages:write`. O perfil `agent` já o tem. - A chave de teste não é um número e **não conta na capacidade do plano**. ## Enviar e receber os estados Envie como sempre, com a chave de teste. O corpo é validado pelo mesmo contrato do envio de verdade (um corpo inválido responde `400`), e `from` é um texto livre: a Luna não procura o número, então use o `phone_number_id` que o seu código usará em produção. ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "1000000000000001", "to": "5511900000000", "type": "text", "text": { "body": "Olá! Esta mensagem é de teste." } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "from": "1000000000000001", "to": "5511900000000", "type": "text", "text": { "body": "Olá! Esta mensagem é de teste." } }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "from": "1000000000000001", "to": "5511900000000", "type": "text", "text": { "body": "Olá! Esta mensagem é de teste.", }, }, timeout=10, ) print(res.status_code, res.json()) ``` Resposta `202`, igual à do envio de verdade ```json { "id": "ae60f288-7565-4315-a440-3663e9c231e1", "status": "queued" } ``` Depois do `202`, a Luna entrega aos seus endpoints de webhook três eventos `message.status`, na ordem: `sent` (cerca de 0,3 segundo depois), `delivered` (cerca de 1 segundo) e `read` (cerca de 2 segundos). Os tempos são aproximados. O `id` do evento é o que o `202` devolveu. O evento `sent` ```json { "version": "2026-11-10", "event_id": "bda40971d61ae76b36ab297565598f9427fd64ef16af8a62d201c8f596eb1006", "event_type": "message.status", "occurred_at": "2026-11-03T15:00:00.300Z", "phone_number_id": "1000000000000001", "test": true, "number": { "id": "03af3f4b-3a6f-4867-880f-eb5e847a6a8f", "phone_number_id": "1000000000000001", "external_id": null }, "message": { "id": "ae60f288-7565-4315-a440-3663e9c231e1", "wamid": "wamid.TESTE_ae60f28875654315a4403663e9c231e1", "wa_id": "5511900000000", "user_id": null, "parent_user_id": null, "username": null, "status": "sent", "error_code": null, "error": null, "pricing": null } } ``` - **`test: true` no envelope.** É o que separa o evento simulado de um de verdade. Se o seu código age sobre o evento, confira esse campo. - Sai **assinado** com o segredo do seu endpoint, com os mesmos cabeçalhos e a mesma assinatura de uma entrega real. Quem verifica a assinatura de verdade verifica a deste evento. Veja [Receber eventos](https://lunahia.com.br/docs/receber-eventos). - O `wamid` começa com `wamid.TESTE_`, para nunca se confundir com um da Meta. O `number.id` é um identificador de mentira, estável para o mesmo `phone_number_id`, e `number.external_id` é nulo. - `pricing` vem nulo: a mensagem não foi à Meta, então ninguém a classificou. **Quem recebe:** os endpoints ativos, sem filtro de cliente nem de número, que aceitam o tipo do evento. Um endpoint pausado, ou restrito a clientes ou a números, não recebe o evento simulado. A entrega é de **uma tentativa só**: não há reenvio, o evento não vai para a fila de rejeitados e uma falha dele não pausa o endpoint. Sem nenhum endpoint, o `202` sai do mesmo jeito e nada chega. ## Simular uma falha de envio Três números em `to` fazem o envio de teste terminar em `failed`, para você ver o seu código tratar a recusa sem gastar um número de verdade. Para eles sai **um único** `message.status`, com `status: "failed"`, `error_code` e `error` (`code`, `title` e `message`) no formato do erro que a Meta informa. Não saem `sent`, `delivered` nem `read`. - `5511900009901`: `failed` com o erro `131026` (mensagem não entregável: o número não tem WhatsApp, ou não aceitou os termos). - `5511900009902`: `failed` com o erro `131047` (a janela de 24 horas está fechada: só vale um template). - `5511900009903`: `failed` com o erro `131049` (a Meta não entregou para preservar a saúde do ecossistema, o limite de marketing por pessoa). Só a chave de teste tem esse comportamento. Com a chave de produção, esses números não têm nada de especial: o envio segue o caminho de sempre. ## Simular uma mensagem recebida `POST /v1/test-mode/inbound-messages` entrega aos seus endpoints **uma** `message.received` de exemplo, em cerca de meio segundo, para você exercitar o fluxo de atendimento sem esperar um contato escrever. O corpo é opcional: `text` (o texto), `waId` (o telefone de quem "escreveu", só dígitos) e `phoneNumberId` (o que aparece no evento). Ausentes, valem um texto de exemplo, `5511900000000` e `123456789012345`. ```bash curl -X POST "https://api.lunahia.com.br/v1/test-mode/inbound-messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "text": "Quero a segunda via do boleto" }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/test-mode/inbound-messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "text": "Quero a segunda via do boleto" }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/test-mode/inbound-messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "text": "Quero a segunda via do boleto", }, timeout=10, ) print(res.status_code, res.json()) ``` Resposta `202` ```json { "id": "3f6a1c52-9d4e-4b87-a1f0-5e2c7b9d8a14", "wamid": "wamid.TESTE_3f6a1c529d4e4b87a1f05e2c7b9d8a14", "endpoints": 1 } ``` `endpoints` diz quantos dos seus endpoints vão receber o evento. Zero quer dizer que nada vai chegar: cadastre um endpoint. Esta rota aceita também a chave comum, e então faz o mesmo que `POST /v1/webhooks/endpoints/{id}/test` com `eventType: "message.received"`, só que para todos os endpoints de uma vez. Para exercitar os outros tipos de evento, use essa rota de teste do endpoint, que aceita qualquer tipo. ## O que o modo de teste não faz - **Não grava nada.** A mensagem não aparece em `GET /v1/messages`, e a chave de teste nem lê essa rota. O `id` existe só nos eventos. - **Não confere a janela de 24 horas, o template aprovado, as variáveis dele, o telefone do destinatário (+55) nem o número.** Por isso um envio que a produção recusaria com `409`, `400` ou `422` passa no modo de teste. Teste esses caminhos com um número de verdade. - **Só simula as três falhas dos números mágicos.** Fora deles os estados são `sent`, `delivered` e `read`. Para outro `failed`, use `POST /v1/webhooks/endpoints/{id}/test` com `eventType: "message.status"` ou construa o evento a partir dos exemplos de [Receber eventos](https://lunahia.com.br/docs/receber-eventos). - **Não é idempotente.** O cabeçalho `Idempotency-Key` é ignorado: cada envio gera um `id` novo e três eventos novos. - **Os estados saem de um temporizador do processo da Luna.** Se o processo reiniciar entre um estado e outro, os que faltavam não saem. Repita o envio. - Há um teto técnico de entregas simuladas agendadas ao mesmo tempo, igual para todos. Passou dele, a resposta é `429` com `Retry-After`. Espere o tempo indicado. - Conta suspensa recusa o envio de teste como recusa o de verdade (`403`, veja [Plano e números](https://lunahia.com.br/docs/plano-e-numeros)). ## Passar para produção Troque a chave de teste por uma chave comum. O resto do código é o mesmo, porque o envio e os eventos têm a mesma forma. Enquanto os dois ambientes convivem, descarte ou separe o que vem com `test: true`. Para usar o modo de teste no n8n ou com o SDK, veja [SDK e n8n](https://lunahia.com.br/docs/sdk-e-n8n). --- # SDK e n8n Fonte: https://lunahia.com.br/docs/sdk-e-n8n A API da Luna é HTTP comum com uma especificação OpenAPI, e você pode chamá-la de qualquer linguagem e de qualquer ferramenta. No n8n, o caminho que funciona hoje usa só os nós padrão: um Webhook para receber, um Code para conferir a assinatura e um HTTP Request para enviar. O SDK Node/TypeScript e o nó próprio do n8n estão em preparação. A [referência da API](https://lunahia.com.br/docs/referencia) é o contrato. As ferramentas não têm regra de negócio: a [janela de 24 horas](https://lunahia.com.br/docs/glossario#janela), a capacidade do plano e o template aprovado são conferidos pela API, que responde com o motivo. ## n8n hoje: os nós padrão Um fluxo de quatro peças, todas de fábrica no n8n: o **Webhook** recebe o evento da Luna (com o corpo bruto), o **Code** confere a assinatura, o **Respond to Webhook** devolve `200` ou `401`, e o **HTTP Request** envia a resposta pela API. Você precisa de uma chave de API com `messages:write` e do número de origem (`metaPhoneNumberId`, de `GET /v1/numbers`). ### 1. O nó Webhook - **HTTP Method**: `POST`. **Path**: `luna` (ou o que preferir). - **Respond**: “Using ‘Respond to Webhook’ Node”. É o que permite responder `401` a uma assinatura que não confere. - Em **Options**, ligue **Raw Body**. Este é o passo que costuma faltar: a assinatura é calculada sobre os **bytes exatos** do corpo, e sem essa opção o n8n entrega o JSON já aberto e a conta não bate. Com ela, o corpo chega como dado binário na propriedade `data`. - Ative o fluxo e copie a **Production URL**. Cadastre-a como endpoint da Luna (`POST /v1/webhooks/endpoints`, como em [Primeiros passos](https://lunahia.com.br/docs/primeiros-passos#webhook)) e guarde o `secret` da resposta: ele aparece uma única vez. A URL de teste do n8n não serve, porque só vive enquanto você escuta no editor. ### 2. O nó Code: conferir a assinatura Modo **Run Once for All Items**, linguagem JavaScript. O código faz a conferência que [Receber eventos](https://lunahia.com.br/docs/receber-eventos#assinatura) explica em palavras, e devolve `valid` (verdadeiro ou falso) e, se valer, o `event` já lido. Troque `SECRET` pelo segredo do passo anterior. ```js const crypto = require('crypto'); const SECRET = 'whsec_PASTE_YOUR_SECRET_HERE'; // cole aqui o segredo do seu endpoint (whsec_...). Em produção, guarde-o numa credencial ou numa variável. const TOLERANCE_SECONDS = 300; const header = $input.first().json.headers['x-luna-signature'] ?? ''; // o cabeçalho da assinatura (o nó Webhook escreve os nomes dos cabeçalhos em minúsculas) const raw = await this.helpers.getBinaryDataBuffer(0, 'data'); // os bytes exatos que chegaram: o nó Webhook precisa estar com a opção Raw Body ligada const m = /^t=(\d{1,15}),/.exec(header); if (!m) return [{ json: { valid: false } }]; const t = Number(m[1]); // recuse o que é velho demais (uma entrega capturada e repetida depois) if (Math.abs(Math.floor(Date.now() / 1000) - t) > TOLERANCE_SECONDS) { return [{ json: { valid: false } }]; } // refaça a conta com o seu segredo e compare com cada v1 const expected = crypto.createHmac('sha256', SECRET).update(t + '.').update(raw).digest(); let valid = false; // na troca do segredo o cabeçalho traz dois valores v1: confira todos for (const [, hex] of header.matchAll(/v1=([0-9a-fA-F]{64})/g)) { if (crypto.timingSafeEqual(Buffer.from(hex, 'hex'), expected)) valid = true; } // o próximo nó lê valid e, se for verdadeiro, o evento return [{ json: { valid, event: valid ? JSON.parse(raw.toString('utf8')) : null } }]; ``` > O nó Code só usa os módulos do Node que o administrador do n8n liberou. Se o `require('crypto')` for recusado, defina `NODE_FUNCTION_ALLOW_BUILTIN=crypto` no ambiente do n8n (num n8n que você mesmo hospeda) e reinicie. ### 3. O nó HTTP Request: enviar a resposta Depois de um nó “IF” que deixa passar só o que tem `valid` verdadeiro, e de outro que filtra `event.event_type` igual a `message.received`, o HTTP Request chama a API: | Campo | Valor | | --- | --- | | Method | `POST` | | URL | `https://api.lunahia.com.br/v1/messages` | | Cabeçalho `Authorization` | `Bearer hlsn_...` (a sua chave; no n8n, prefira uma credencial “Header Auth”) | | Cabeçalho `Idempotency-Key` | `resp-` seguido do `id` da mensagem recebida: com ele, repetir a execução não envia duas respostas | | Body (JSON) | `from` (o seu número), `to` (o `wa_id` do evento) e `text.body` | ### Um fluxo pronto para importar O JSON abaixo é o fluxo inteiro: Webhook, Code, IF, as duas respostas, o filtro de mensagem recebida e o HTTP Request. Copie, e no n8n cole no canvas (Ctrl+V ou Cmd+V) ou use **Import from File**. Depois troque os três valores `PASTE_...`: o segredo no nó Code, a chave de API e o número no HTTP Request. ```json { "name": "Luna: responder mensagem recebida", "nodes": [ { "parameters": { "httpMethod": "POST", "path": "luna", "responseMode": "responseNode", "options": { "rawBody": true } }, "id": "5b0c1c1e-2f3a-4b5c-8d6e-7f8091a2b3c1", "name": "Webhook da Luna", "type": "n8n-nodes-base.webhook", "typeVersion": 2, "position": [ 0, 300 ], "webhookId": "9d8c7b6a-5e4f-4a3b-9c2d-1e0f9a8b7c6d" }, { "parameters": { "jsCode": "const crypto = require('crypto');\n\nconst SECRET = 'whsec_PASTE_YOUR_SECRET_HERE'; // cole aqui o segredo do seu endpoint (whsec_...). Em produção, guarde-o numa credencial ou numa variável.\nconst TOLERANCE_SECONDS = 300;\n\nconst header = $input.first().json.headers['x-luna-signature'] ?? ''; // o cabeçalho da assinatura (o nó Webhook escreve os nomes dos cabeçalhos em minúsculas)\nconst raw = await this.helpers.getBinaryDataBuffer(0, 'data'); // os bytes exatos que chegaram: o nó Webhook precisa estar com a opção Raw Body ligada\n\nconst m = /^t=(\\d{1,15}),/.exec(header);\nif (!m) return [{ json: { valid: false } }];\nconst t = Number(m[1]);\n\n// recuse o que é velho demais (uma entrega capturada e repetida depois)\nif (Math.abs(Math.floor(Date.now() / 1000) - t) > TOLERANCE_SECONDS) {\n return [{ json: { valid: false } }];\n}\n\n// refaça a conta com o seu segredo e compare com cada v1\nconst expected = crypto.createHmac('sha256', SECRET).update(t + '.').update(raw).digest();\nlet valid = false;\n// na troca do segredo o cabeçalho traz dois valores v1: confira todos\nfor (const [, hex] of header.matchAll(/v1=([0-9a-fA-F]{64})/g)) {\n if (crypto.timingSafeEqual(Buffer.from(hex, 'hex'), expected)) valid = true;\n}\n\n// o próximo nó lê valid e, se for verdadeiro, o evento\nreturn [{ json: { valid, event: valid ? JSON.parse(raw.toString('utf8')) : null } }];" }, "id": "6c1d2d2f-3a4b-4c5d-9e7f-8a9102b3c4d2", "name": "Verificar a assinatura", "type": "n8n-nodes-base.code", "typeVersion": 2, "position": [ 240, 300 ] }, { "parameters": { "conditions": { "options": { "caseSensitive": true, "leftValue": "", "typeValidation": "strict", "version": 2 }, "conditions": [ { "id": "a1b2c3d4-0001-4000-8000-000000000001", "leftValue": "={{ $json.valid }}", "rightValue": "", "operator": { "type": "boolean", "operation": "true", "singleValue": true } } ], "combinator": "and" }, "options": {} }, "id": "7d2e3e30-4b5c-4d6e-8f80-9b0213c4d5e3", "name": "Assinatura válida?", "type": "n8n-nodes-base.if", "typeVersion": 2.2, "position": [ 480, 300 ] }, { "parameters": { "respondWith": "noData", "options": { "responseCode": 200 } }, "id": "8e3f4f41-5c6d-4e7f-9091-ac1324d5e6f4", "name": "Responder 200", "type": "n8n-nodes-base.respondToWebhook", "typeVersion": 1.1, "position": [ 720, 200 ] }, { "parameters": { "respondWith": "noData", "options": { "responseCode": 401 } }, "id": "9f405052-6d7e-4f80-a1a2-bd2435e6f705", "name": "Responder 401", "type": "n8n-nodes-base.respondToWebhook", "typeVersion": 1.1, "position": [ 720, 420 ] }, { "parameters": { "conditions": { "options": { "caseSensitive": true, "leftValue": "", "typeValidation": "strict", "version": 2 }, "conditions": [ { "id": "a1b2c3d4-0002-4000-8000-000000000002", "leftValue": "={{ $('Verificar a assinatura').item.json.event.event_type === 'message.received' }}", "rightValue": "", "operator": { "type": "boolean", "operation": "true", "singleValue": true } } ], "combinator": "and" }, "options": {} }, "id": "a0516163-7e8f-4091-b2b3-ce3546f70816", "name": "É mensagem recebida?", "type": "n8n-nodes-base.if", "typeVersion": 2.2, "position": [ 960, 200 ] }, { "parameters": { "method": "POST", "url": "https://api.lunahia.com.br/v1/messages", "sendHeaders": true, "headerParameters": { "parameters": [ { "name": "Authorization", "value": "Bearer hlsn_PASTE_YOUR_KEY_HERE" }, { "name": "Idempotency-Key", "value": "=resp-{{ $('Verificar a assinatura').item.json.event.message.id }}" } ] }, "sendBody": true, "specifyBody": "json", "jsonBody": "={{ JSON.stringify({ from: 'PASTE_YOUR_NUMBER_ID_HERE', to: $('Verificar a assinatura').item.json.event.message.wa_id, text: { body: 'Recebi: ' + $('Verificar a assinatura').item.json.event.message.text } }) }}", "options": {} }, "id": "b1627274-8f90-4102-83c4-df4657081927", "name": "Enviar a resposta", "type": "n8n-nodes-base.httpRequest", "typeVersion": 4.2, "position": [ 1200, 100 ] } ], "connections": { "Webhook da Luna": { "main": [ [ { "node": "Verificar a assinatura", "type": "main", "index": 0 } ] ] }, "Verificar a assinatura": { "main": [ [ { "node": "Assinatura válida?", "type": "main", "index": 0 } ] ] }, "Assinatura válida?": { "main": [ [ { "node": "Responder 200", "type": "main", "index": 0 } ], [ { "node": "Responder 401", "type": "main", "index": 0 } ] ] }, "Responder 200": { "main": [ [ { "node": "É mensagem recebida?", "type": "main", "index": 0 } ] ] }, "É mensagem recebida?": { "main": [ [ { "node": "Enviar a resposta", "type": "main", "index": 0 } ] ] } }, "pinData": {}, "settings": { "executionOrder": "v1" } } ``` > **O que foi conferido, e o que não foi.** O código do nó Code é executado nos testes da documentação contra a assinatura de verdade da Luna. O fluxo em JSON foi escrito a partir da documentação dos nós padrão do n8n, e a Helsen ainda não o importou num n8n real: se a sua versão nomear alguma opção de outro jeito, o que muda é a tela, e não a lógica. Para conferir de ponta a ponta, mande o evento de teste (`POST /v1/webhooks/endpoints/{id}/test`, veja [Receber eventos](https://lunahia.com.br/docs/receber-eventos#gerir)): se o nó Code responder `valid` verdadeiro, a conta bate. Para montar e testar o fluxo sem mandar mensagem de verdade, use uma chave de teste no HTTP Request: o envio não vai à Meta, e a Luna entrega ao seu webhook os estados `sent`, `delivered` e `read` com `test: true`. Veja [Modo de teste](https://lunahia.com.br/docs/modo-de-teste). Um agente de IA que responde com um modelo no meio do fluxo segue o laço de [Agente de IA](https://lunahia.com.br/docs/agente-de-ia). ## Em breve: o SDK e o nó próprio > **O SDK Node/TypeScript e o nó do n8n da Luna ainda não estão publicados** (nem no npm, nem no diretório de nós do n8n), e não há data. Eles vivem no repositório da Luna, em `packages/sdk` e `packages/n8n-nodes-luna`. O n8n de hoje é o fluxo acima, e o Node de hoje é o `fetch` (veja [Agente de IA](https://lunahia.com.br/docs/agente-de-ia)). ## SDK Node/TypeScript O SDK é o cliente tipado gerado da especificação, com três acréscimos: a URL de produção como padrão (`criarLuna`), o tratamento de erro (`exigir` devolve o corpo de uma resposta boa e lança `LunaErro` na recusa, com `status`, `codigo` e `docsUrl`) e a verificação da assinatura do webhook. Cada caminho e cada verbo vêm da especificação, então uma rota que a API não serve é erro de compilação. Criar o cliente e enviar ```js import { criarLuna, exigir } from '@helsen/sdk'; const luna = criarLuna({ apiKey: process.env.LUNA_API_KEY }); const envio = exigir( await luna.POST('/v1/messages', { body: { from: '1000000000000001', to: '5511900000000', type: 'text', text: { body: 'Olá!' } }, }), ); console.log(envio.id, envio.status); ``` ### Conferir a assinatura do webhook `lerEvento` confere a assinatura (`x-luna-signature`) sobre os **bytes exatos** do corpo e só então lê o JSON, devolvendo o evento tipado por `event_type`. Com assinatura que não confere, lança `AssinaturaInvalida`, e o corpo não é lido. `verificarAssinatura` só devolve `true` ou `false`. Durante a rotação do segredo, passe uma lista com o novo e o antigo. É o mesmo código que a Luna usa para assinar, então o resultado concorda com o do verificador de referência em [Receber eventos](https://lunahia.com.br/docs/receber-eventos). Um servidor de webhook com o SDK ```js import express from 'express'; import { lerEvento, AssinaturaInvalida, CABECALHO_DA_ASSINATURA } from '@helsen/sdk'; const app = express(); // O corpo precisa chegar como bytes, sem passar por express.json() antes. app.post('/luna', express.raw({ type: 'application/json' }), (req, res) => { try { const evento = lerEvento(req.body, req.headers[CABECALHO_DA_ASSINATURA], process.env.LUNA_WEBHOOK_SECRET); if (evento.event_type === 'message.received') console.log(evento.message.text); res.sendStatus(200); } catch (erro) { if (erro instanceof AssinaturaInvalida) return res.sendStatus(401); throw erro; } }); ``` Um evento com `test: true` é de teste. Veja [Modo de teste](https://lunahia.com.br/docs/modo-de-teste). ## Nó do n8n O pacote traz uma credencial e dois nós. A **credencial Luna API** guarda a chave (`hlsn_...`) e a URL da API, e o botão de teste dela lê `GET /v1/numbers`, então a chave precisa do escopo `numbers:read`. O nó **Luna** envia texto, envia template e lista os números. O gatilho **Luna Trigger** inicia o fluxo quando a Luna entrega um evento. ### Enviar uma mensagem 1. Crie a credencial com a sua chave de API. 2. No nó Luna, escolha Mensagem e Enviar Texto, ou Enviar Template. Preencha o número de origem (o `metaPhoneNumberId` que Listar Números devolve), o telefone do destinatário (só dígitos) e o conteúdo. 3. A saída é o `202` da API, com o `id` da mensagem. Se a API recusar (por exemplo `409`, texto fora da janela de 24 horas), o nó falha com a resposta dela; com "Continuar em caso de erro" ligado, o erro vira um item. ### Receber eventos no n8n 1. Ative o fluxo e copie a URL de produção do webhook do nó Luna Trigger. 2. Cadastre essa URL como endpoint da Luna (`POST /v1/webhooks/endpoints`). A resposta traz o segredo uma única vez. 3. Cole o segredo no campo "Segredo de Assinatura" do nó. O nó confere a assinatura sobre os bytes exatos do corpo e responde `401`, sem rodar o fluxo, quando ela não confere. Ele **não cadastra o endpoint sozinho**. Dá para filtrar por tipo de evento (separados por vírgula, vazio quer dizer todos) e descartar os eventos com `test: true`. > **O nó do n8n nunca foi carregado num n8n de verdade.** Ele foi escrito e testado com um duplo do contexto do n8n. O comportamento do corpo bruto e da resposta `401` no gatilho está a confirmar num n8n real, antes de qualquer publicação. ## Montar o fluxo sem mandar mensagem de verdade Use uma chave de teste na credencial do n8n, ou no SDK. Enviar não vai à Meta, e a Luna entrega ao seu webhook os estados `sent`, `delivered` e `read`, com `test: true`. O botão de teste da credencial do n8n lê `GET /v1/numbers` e uma chave de teste não passa nele, mas as operações de enviar funcionam. O guia [Modo de teste](https://lunahia.com.br/docs/modo-de-teste) explica tudo. --- # Use a documentação no seu editor (MCP) Fonte: https://lunahia.com.br/docs/mcp A documentação da Luna tem um servidor MCP público. Ligado ao seu editor ou assistente, a IA busca nos guias e na referência por conta própria, e lê o contrato exato de cada rota antes de escrever o código da integração. O endereço é `https://lunahia.com.br/mcp`. O servidor é só de leitura, não pede chave e não guarda nada sobre você. Ele lê do mesmo conteúdo que gera esta documentação, os arquivos `.md` de cada página e o `llms-full.txt`: quando um guia ou a [referência da API](https://lunahia.com.br/docs/referencia) muda, o MCP muda junto, sem você atualizar nada. Ele não chama a API da Luna e não envia mensagem; para isso use a [chave de API](https://lunahia.com.br/docs/conta-e-chaves) e a referência. ## As quatro ferramentas | Ferramenta | O que faz | | --- | --- | | `list_pages` | Lista as páginas (guias e referência) com o identificador (`slug`), o título e uma linha de resumo. | | `read_page` | Devolve o Markdown de uma página, idêntico ao do arquivo `.md` dela. Páginas longas vêm em pedaços; a resposta diz qual `offset` pedir para continuar. | | `search_docs` | Busca nos guias, nas rotas, nos eventos de webhook e nos códigos de erro, e devolve as melhores seções com `slug`, âncora, link e um trecho. | | `get_endpoint` | Devolve a operação OpenAPI de uma rota (`method` e `path`), com os esquemas já resolvidos: é o contrato exato para gerar o código do cliente. Rotas grandes aceitam `part` (`request` ou `responses`) para trazer só metade. | Todas aceitam `lang`: `pt` (padrão) ou `en`. Cada resposta tem no máximo 24 000 caracteres; passando disso o texto é cortado com um aviso, e `read_page` e `get_endpoint` aceitam `offset` para pedir o resto. ## Conectar o seu cliente Em todos, o nome `luna-docs` é só um rótulo; troque se quiser. Não há cabeçalho de autenticação para configurar. ### Claude Code Uma linha no terminal: ```bash claude mcp add --transport http luna-docs https://lunahia.com.br/mcp ``` Por padrão a configuração vale só para você, no projeto atual. Com `--scope user` ela vale em todos os seus projetos, e com `--scope project` o comando grava o `.mcp.json` abaixo na raiz do repositório, para o time inteiro usar. Confira com `claude mcp list` ou, dentro do Claude Code, com `/mcp`. .mcp.json ```json { "mcpServers": { "luna-docs": { "type": "http", "url": "https://lunahia.com.br/mcp" } } } ``` ### Cursor Crie `.cursor/mcp.json` no projeto, ou `~/.cursor/mcp.json` para valer em todos: .cursor/mcp.json ```json { "mcpServers": { "luna-docs": { "url": "https://lunahia.com.br/mcp" } } } ``` ### VS Code Crie `.vscode/mcp.json`. Atenção: o VS Code usa a chave `servers`, e não `mcpServers`. Também dá para usar o comando **MCP: Add Server** da paleta de comandos, escolher **HTTP** e colar o endereço. .vscode/mcp.json ```json { "servers": { "luna-docs": { "type": "http", "url": "https://lunahia.com.br/mcp" } } } ``` ### Claude (conector remoto) No claude.ai, vá em **Customize > Connectors**, clique em **Add** e em **Add custom connector**, dê um nome (por exemplo `Luna docs`) e cole `https://lunahia.com.br/mcp` como endereço. Em autenticação, escolha **No sign in**. Planos Team e Enterprise: quem adiciona é o administrador da organização, em **Organization settings > Connectors**. Depois, em cada conversa, ative o conector pelo botão **+**. ### ChatGPT O ChatGPT aceita servidor MCP remoto pelo **modo desenvolvedor**, nas configurações de apps e conectores: crie um app MCP, cole `https://lunahia.com.br/mcp` como endereço e escolha **sem autenticação**. Depois, ative-o na conversa. Esses menus mudam de lugar e de nome entre versões e planos, e a Helsen não conseguiu conferir o passo a passo na documentação da OpenAI, então siga o que o seu ChatGPT mostrar. > Outros clientes que falam MCP por HTTP funcionam do mesmo jeito: basta o endereço. O Claude e o ChatGPT se conectam da nuvem deles, então só enxergam o servidor publicado, nunca um `localhost`. ## O que pedir à IA - “Usando a documentação da Luna, escreva em Node o código que envia um template aprovado.” - “Qual o contrato exato de `POST /v1/messages`? Gere os tipos em TypeScript.” - “Como confiro a assinatura de um webhook da Luna? Mostre um exemplo em Python.” - “O que significa o erro `window_closed` e o que eu faço?” ## Detalhes técnicos - Transporte **Streamable HTTP**, sem sessão: cada chamada é um `POST` com uma mensagem JSON-RPC, e a resposta é um JSON. `GET` e `DELETE` respondem `405`. - Versões do protocolo: 2025-03-26, 2025-06-18, 2025-11-25 (com `initialize`) e 2026-07-28 (sem handshake, com `server/discover`). - CORS aberto, para clientes de navegador, e nenhuma credencial: não há cookie nem chave a proteger. Para testar sem cliente nenhum, chame uma ferramenta direto: ```bash curl -X POST https://lunahia.com.br/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":"enviar template"}}}' ``` --- # Templates Fonte: https://lunahia.com.br/docs/templates Template é uma mensagem pré-aprovada pela Meta. É o que permite iniciar conversa fora da janela de 24 horas. Dentro da janela, texto livre basta. ## Quando você precisa de um template - O contato nunca escreveu para o seu número, ou a última mensagem dele tem mais de 24 horas (a [janela de 24 horas](https://lunahia.com.br/docs/glossario#janela) fechou): só um template sai. Texto livre é recusado com `409`. - Enviar um template **não reabre a janela**. Ele é o caminho para iniciar a conversa, e a mensagem livre só volta a ser aceita quando o contato responde. - Para saber se a janela está aberta antes de tentar, leia `GET /v1/conversations`. Veja [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens#janela). ## Testar sem um template aprovado Um template novo nasce `PENDING` e só envia depois de `APPROVED`: quem decide é a Meta, e o evento `template.status` avisa quando o estado muda. Enquanto isso, dá para montar e testar o seu código de duas maneiras: - **Com uma chave de teste** ([Modo de teste](https://lunahia.com.br/docs/modo-de-teste)). `POST /v1/messages` com `type: "template"` e a chave de teste devolve o `202` e entrega ao seu webhook os estados simulados, **sem conferir** se o template existe, se está aprovado nem as variáveis dele. Serve para testar o seu código (o corpo, o webhook, o tratamento dos estados), e não o template em si. - **Com a chave de verdade**, um template que a Luna conhece e ainda não está aprovado responde `409` com `error: "template_not_approved"` e o `templateStatus` (`PENDING`, `REJECTED`, `PAUSED`...), sem enviar nada. Isso também mostra, sem gastar envio, o ponto exato em que o seu código precisa esperar. Um template criado direto no painel da Meta, que a Luna não conhece, passa, e quem decide é a Meta. Criar e editar template consome um orçamento de operações de gestão da conta, e passar dele responde `429` com `error: "management_busy"`. Os números estão em [Limites e ritmo](https://lunahia.com.br/docs/limites-e-ritmo). ## Crie um template `POST /v1/templates` cria o template na conta de WhatsApp Business do cliente e o submete à Meta para aprovação. Escopo `templates:write`. O `wabaId` é o identificador da conta na Meta, e vem de `GET /v1/business-accounts` (escopo `numbers:read`): **Quanto demora a aprovação.** A Meta diz que a análise de um template pode levar até 24 horas ([documentação da Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/overview)). O estado começa em `PENDING` e muda sozinho: não consulte de tempos em tempos, espere o evento `template.status` (`APPROVED`, `REJECTED`, `PAUSED`, `DISABLED`). Planeje a criação dos templates de um cliente novo antes do primeiro envio fora da janela de atendimento. ```bash curl -X GET "https://api.lunahia.com.br/v1/business-accounts" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/business-accounts', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/business-accounts", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` ```bash curl -X POST "https://api.lunahia.com.br/v1/templates" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "wabaId": "YOUR_WABA_ID", "name": "confirmacao_de_pedido", "language": "pt_BR", "category": "UTILITY", "bodyText": "Olá {{nome}}, recebemos o seu pedido e já estamos preparando.", "examples": { "nome": "Ana" }, "footer": "Obrigado por comprar com a gente.", "buttons": [ { "type": "QUICK_REPLY", "text": "Falar com atendente" } ] }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/templates', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "wabaId": "YOUR_WABA_ID", "name": "confirmacao_de_pedido", "language": "pt_BR", "category": "UTILITY", "bodyText": "Olá {{nome}}, recebemos o seu pedido e já estamos preparando.", "examples": { "nome": "Ana" }, "footer": "Obrigado por comprar com a gente.", "buttons": [ { "type": "QUICK_REPLY", "text": "Falar com atendente" } ] }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/templates", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "wabaId": "YOUR_WABA_ID", "name": "confirmacao_de_pedido", "language": "pt_BR", "category": "UTILITY", "bodyText": "Olá {{nome}}, recebemos o seu pedido e já estamos preparando.", "examples": { "nome": "Ana", }, "footer": "Obrigado por comprar com a gente.", "buttons": [ { "type": "QUICK_REPLY", "text": "Falar com atendente", }, ], }, timeout=10, ) print(res.status_code, res.json()) ``` Resposta `201` ```json { "id": "ae60f288-7565-4315-a440-3663e9c231e1", "metaTemplateId": "1259544702043801", "name": "confirmacao_de_pedido", "language": "pt_BR", "category": "UTILITY", "status": "PENDING", "createdAt": "2026-10-06T14:00:00.000Z", "updatedAt": "2026-10-06T14:00:00.000Z" } ``` | Campo | Regra | | --- | --- | | `name` | Minúsculas, números e sublinhado: `^[a-z0-9_]{1,512}$`. Não muda depois. | | `language` | Na grafia da Meta, com sublinhado e não hífen: `pt_BR`, `pt_PT`, `en_US`, `es_MX`, `fr`. Não muda depois. | | `category` | `MARKETING` ou `UTILITY`. Ausente vale `UTILITY`. Para código de verificação existe uma rota própria (veja abaixo). | | `bodyText` | Até 1024 caracteres. Aceita variáveis na forma `{{nome_da_variavel}}`, em minúsculas e sublinhado. O corpo não pode começar nem terminar com variável, e pontuação na ponta não conta: um corpo que termina em `{{nome}}.` é recusado. Escreva texto antes da primeira variável e depois da última. | | `examples` | Um objeto `{ "primeiro_nome": "Maria" }`, nunca uma lista: um valor de amostra por variável do corpo, obrigatório quando há variável. A Meta recusa parâmetro sem exemplo, e a recusa custa uma unidade do orçamento de gestão da conta. | | `header`, `footer` | Texto de até 60 caracteres. O rodapé não aceita variável. Para cabeçalho de imagem, vídeo ou documento, use `headerMedia`. | | `buttons` | Até 10 no total, somando os tipos `QUICK_REPLY`, `URL`, `PHONE_NUMBER` e `COPY_CODE`. Se houver respostas rápidas junto de outros botões, os dois conjuntos precisam ficar agrupados. | - A categoria que volta na resposta é a que a **Meta atribuiu**, e pode não ser a que você pediu, porque ela reclassifica na criação. A Luna guarda o que a Meta respondeu e a atualiza quando a Meta avisa uma mudança de categoria (evento `template.category`, veja Categoria e qualidade mudam depois de aprovado): `GET /v1/templates` mostra a corrente. Uma mudança que a Meta não avisou não chega à Luna; na dúvida, confira no painel da Meta. - Cada idioma é um template **separado** para a Meta. Dez templates em nove idiomas são noventa templates, e o teto é de 250 por conta de WhatsApp Business. O teto é da Meta e é o mesmo para todos os clientes. - Acima de três botões, apenas dois aparecem na mensagem entregue. A Meta aceita o template com mais e entrega dois, então decida o arranjo antes de desenhar o fluxo. ## Acompanhe o estado `GET /v1/templates/{id}` devolve o estado atual do template na Meta. Escopo `templates:read`: ```bash curl -X GET "https://api.lunahia.com.br/v1/templates/YOUR_TEMPLATE_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/templates/YOUR_TEMPLATE_ID', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/templates/YOUR_TEMPLATE_ID", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` - O `status` é texto livre, e não um conjunto fechado, de propósito: a Meta acrescenta valor novo sem aviso. Os comuns são `APPROVED`, `PENDING`, `REJECTED`, `PAUSED` e `DISABLED`. - **A Luna manda o evento `template.status` para o seu endpoint quando o estado de um template muda**: aprovado, rejeitado, pausado ou desativado. O evento traz o `id` do template na Luna, o `name`, o `language`, o `waba_id` (a conta de negócio, o `wabaId` das leituras de template), a `category`, o `status` novo e, na rejeição ou na pausa, o `reason` que a Meta informou. Espere o evento em vez de consultar de tempos em tempos. Veja [Receber eventos](https://lunahia.com.br/docs/receber-eventos#eventos). - A consulta continua valendo como reserva. Se o seu endpoint ficou fora do ar, ou você perdeu um evento, `GET /v1/templates/{id}` devolve o estado atual, e `GET /v1/templates` o último que a Luna observou de cada template. `GET /v1/templates` lista os templates do cliente, do mais recente ao mais antigo. O `status` que volta na lista é o **último que a Luna observou**, e não uma leitura ao vivo na Meta. Use `?status=` para filtrar. A comparação é literal e sensível a maiúsculas. ```bash curl -X GET "https://api.lunahia.com.br/v1/templates?status=APPROVED" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/templates?status=APPROVED', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.get( "https://api.lunahia.com.br/v1/templates?status=APPROVED", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code, res.json()) ``` ## Categoria e qualidade mudam depois de aprovado A categoria do template (`UTILITY`, `MARKETING`, `AUTHENTICATION`) define o preço que a Meta cobra do negócio pelo envio. A Meta pode mudar a categoria **depois de aprovado**, quando o conteúdo indica outra: um template de `UTILITY` que passa a `MARKETING` continua `APPROVED`, e o preço dele sobe. Quem paga é o dono da conta, direto à Meta; a Luna não cobra nem intermedeia esse valor. Hoje o negócio costuma descobrir pela fatura da Meta. Com a Luna você descobre antes, por evento. - **`template.category`** chega de duas formas: o aviso prévio, com `correct_category` (a categoria para a qual a Meta vai mudar) e `scheduled_for` (quando), e a mudança feita, com `previous_category` e `new_category`. Quando a mudança é feita, o campo `category` do template, em `GET /v1/templates`, passa a mostrar a categoria nova. - **`template.quality`** avisa que a nota de qualidade do template mudou (`previous_quality_score` e `new_quality_score`: `GREEN`, `YELLOW`, `RED`). Nota baixa antecede a pausa do template pela Meta, que chega como `template.status` com `PAUSED`. - **O que fazer.** No aviso prévio, revise o conteúdo se a intenção era utilidade e avise o dono da conta de que o preço vai mudar. A Meta permite pedir a revisão da categoria no WhatsApp Manager, por um prazo que ela define. Na qualidade baixa, revise o conteúdo ou o público antes da pausa. > O formato completo dos dois eventos, com exemplos, está em [Receber eventos](https://lunahia.com.br/docs/receber-eventos). ## Aprovado não é liberado Um template `APPROVED` não está necessariamente liberado para sair. A Meta aplica um ritmo próprio de liberação sobre os primeiros envios de um template recém-aprovado. Ela chama isso de template pacing, e o define como um processo que dá tempo aos usuários do WhatsApp de reagirem à mensagem: se as primeiras entregas forem mal recebidas, o template é pausado antes de alcançar muita gente. > **A Meta não publica prazo nem mecânica, e a Luna não inventa nenhum.** Não existe campo nesta API dizendo quando o ritmo termina, e não existe estado dizendo que ele está em curso, porque essa informação não é emitida por quem a controla. Procurar um aqui é procurar o que não pode existir. - **Escalone o primeiro disparo** em vez de programá-lo para uma data. - Comece por um volume pequeno e cresça conforme as entregas confirmarem. - Acompanhe o estado do template: ele vai para `PAUSED` se a reação for negativa. Você pode filtrar a lista com `?status=PAUSED`. ## Cabeçalho de mídia Para um cabeçalho de imagem, vídeo ou documento, são dois passos. Primeiro suba o arquivo de exemplo em `POST /v1/template-assets`, em `multipart/form-data`, no campo `file` (escopo `templates:write`): ```bash curl -X POST "https://api.lunahia.com.br/v1/template-assets" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -F "file=@./exemplo.png;type=image/png" ``` ```js import { readFile } from 'node:fs/promises'; const form = new FormData(); form.append( 'file', new Blob([await readFile('./exemplo.png')], { type: 'image/png' }), 'exemplo.png', ); const res = await fetch('https://api.lunahia.com.br/v1/template-assets', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, body: form, }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/template-assets", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, files={"file": ("exemplo.png", open("exemplo.png", "rb"), "image/png")}, timeout=10, ) print(res.status_code, res.json()) ``` Resposta `200` ```json { "handle": "4:EXAMPLE_HANDLE_NOT_REAL:ARb0Xk:e:1790451084:0" } ``` Depois use o `handle` em `headerMedia`, com o `format` `IMAGE`, `VIDEO` ou `DOCUMENT`: ```bash curl -X POST "https://api.lunahia.com.br/v1/templates" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "wabaId": "YOUR_WABA_ID", "name": "pedido_a_caminho", "language": "pt_BR", "category": "UTILITY", "bodyText": "Olá {{nome}}, o seu pedido saiu para entrega.", "examples": { "nome": "Ana" }, "headerMedia": { "format": "IMAGE", "handle": "YOUR_HANDLE_FROM_TEMPLATE_ASSETS" } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/templates', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "wabaId": "YOUR_WABA_ID", "name": "pedido_a_caminho", "language": "pt_BR", "category": "UTILITY", "bodyText": "Olá {{nome}}, o seu pedido saiu para entrega.", "examples": { "nome": "Ana" }, "headerMedia": { "format": "IMAGE", "handle": "YOUR_HANDLE_FROM_TEMPLATE_ASSETS" } }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/templates", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "wabaId": "YOUR_WABA_ID", "name": "pedido_a_caminho", "language": "pt_BR", "category": "UTILITY", "bodyText": "Olá {{nome}}, o seu pedido saiu para entrega.", "examples": { "nome": "Ana", }, "headerMedia": { "format": "IMAGE", "handle": "YOUR_HANDLE_FROM_TEMPLATE_ASSETS", }, }, timeout=10, ) print(res.status_code, res.json()) ``` - **O `handle` não é o identificador de mídia** que `POST /v1/numbers/{id}/media` devolve. São dois endpoints da Meta com propósitos diferentes, e um identificador de mídia no lugar do `handle` faz a criação ser recusada. O identificador de mídia é um número decimal longo, e o `handle` não é numérico. - Os tipos aceitos no upload são `application/pdf`, `image/jpeg`, `image/jpg`, `image/png` e `video/mp4`. Para documento a Meta aceita apenas PDF. Nem GIF nem localização são aceitos. - O conteúdo do arquivo é conferido contra o tipo declarado antes de qualquer ida à Meta. Um arquivo declarado como `image/png` cujos bytes são de outra coisa é recusado com `400`. Acima do teto, `413`. - A Meta não publica por quanto tempo o `handle` vale, e a Luna não guarda o valor. Use-o na criação do template logo em seguida, e suba de novo se ele deixar de servir. - `header` (texto) e `headerMedia` são exclusivos: a Meta aceita um só cabeçalho por template. > **O arquivo do `headerMedia` é o exemplo que a Meta revisa, e não o conteúdo entregue.** Cada mensagem que você enviar com o template fornece a própria mídia, no componente de cabeçalho do envio. Quem cria o template achando que a imagem do exemplo é a imagem enviada manda mensagem sem cabeçalho. ## Envie o template Com o template `APPROVED`, envie por `POST /v1/messages` com `type: "template"`. O `language.code` precisa bater com o idioma aprovado, e os `components` preenchem as variáveis. Para variável nomeada, use `parameter_name`: ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "template", "template": { "name": "confirmacao_de_pedido", "language": { "code": "pt_BR" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "parameter_name": "nome", "text": "Ana" } ] } ] } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID(), }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "template", "template": { "name": "confirmacao_de_pedido", "language": { "code": "pt_BR" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "parameter_name": "nome", "text": "Ana" } ] } ] } }), }); console.log(res.status, await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "template", "template": { "name": "confirmacao_de_pedido", "language": { "code": "pt_BR", }, "components": [ { "type": "body", "parameters": [ { "type": "text", "parameter_name": "nome", "text": "Ana", }, ], }, ], }, }, timeout=10, ) print(res.status_code, res.json()) ``` Com cabeçalho de mídia, a mídia vai no componente `header` **de cada envio**. O `parameters` aceita os valores na forma que a Cloud API define, e aqui a imagem vai por `link`: ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "template", "template": { "name": "pedido_a_caminho", "language": { "code": "pt_BR" }, "components": [ { "type": "header", "parameters": [ { "type": "image", "image": { "link": "https://example.com/pedido.jpg" } } ] }, { "type": "body", "parameters": [ { "type": "text", "parameter_name": "nome", "text": "Ana" } ] } ] } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "template", "template": { "name": "pedido_a_caminho", "language": { "code": "pt_BR" }, "components": [ { "type": "header", "parameters": [ { "type": "image", "image": { "link": "https://example.com/pedido.jpg" } } ] }, { "type": "body", "parameters": [ { "type": "text", "parameter_name": "nome", "text": "Ana" } ] } ] } }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "template", "template": { "name": "pedido_a_caminho", "language": { "code": "pt_BR", }, "components": [ { "type": "header", "parameters": [ { "type": "image", "image": { "link": "https://example.com/pedido.jpg", }, }, ], }, { "type": "body", "parameters": [ { "type": "text", "parameter_name": "nome", "text": "Ana", }, ], }, ], }, }, timeout=10, ) print(res.status_code, res.json()) ``` Para um template que a Luna conhece (criado por ela, ou que ela viu pelo evento `template.status`), a recusa vem na resposta do envio, e não depois por webhook: `409 template_not_approved` quando o estado não é `APPROVED` (o corpo traz `templateStatus`), e `400` com `campos` quando falta uma variável do corpo ou do cabeçalho, quando vem uma que o template não tem, ou quando o código de um template de autenticação passa de 15 caracteres. A conferência das variáveis vale para o template que a Luna tem o conteúdo (`bodyText` diferente de `null`). Um template criado direto no painel da Meta não está nesse catálogo e passa: quem decide é a Meta, e a recusa dela chega pelo evento `message.status`. O `handle` usado na criação não vira o conteúdo entregue, e não há nada a reaproveitar dele no envio. Para escolher entre `link` e identificador de mídia, vale a recomendação de [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens#midia). ## Editar e remover `PATCH /v1/templates/{id}` altera os componentes de um template existente. A atualização é **parcial**: o que você não informar permanece como está. Por isso o verbo é `PATCH`, e não `PUT`. ```bash curl -X PATCH "https://api.lunahia.com.br/v1/templates/YOUR_TEMPLATE_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "bodyText": "Olá {{nome}}, recebemos o seu pedido e já estamos separando os itens.", "examples": { "nome": "Ana" } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/templates/YOUR_TEMPLATE_ID', { method: 'PATCH', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "bodyText": "Olá {{nome}}, recebemos o seu pedido e já estamos separando os itens.", "examples": { "nome": "Ana" } }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.patch( "https://api.lunahia.com.br/v1/templates/YOUR_TEMPLATE_ID", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "bodyText": "Olá {{nome}}, recebemos o seu pedido e já estamos separando os itens.", "examples": { "nome": "Ana", }, }, timeout=10, ) print(res.status_code, res.json()) ``` Para montar o formulário de criação sem copiar limite nenhum, leia `GET /v1/templates/rules` (escopo `templates:read`): as `categories` (cada uma com `value`, `label` e `summary`), os `languages` sugeridos, o `namePattern` e um `nameExample`, os tamanhos `bodyMaxLength`, `headerMaxLength` e `footerMaxLength`, e os `buttonLimits` (`total` e `byType`). Os idiomas são sugestões: vale qualquer código que a Meta publique. É o mesmo número que `POST /v1/templates` cobra. Para preencher um formulário de edição, leia o conteúdo atual em `GET /v1/templates/{id}` ou em `GET /v1/templates`: `bodyText`, `header`, `headerMedia` (só o formato), `footer`, `buttons` (na mesma forma em que você os mandou) e `variables`, a lista das variáveis do corpo na ordem em que aparecem, cada uma com o `example`. A leitura traz também `rejectedReason`, o motivo que a Meta deu enquanto o template está `REJECTED`, `qualityScore`, a última nota de qualidade que ela avisou, `previousCategory`, a categoria que o template tinha antes de a Meta mudá-la, e `allowedActions`, o que a conta pode fazer agora (`edit` e `delete`, e nada com a conta suspensa). O conteúdo é nulo (`bodyText: null`) num template criado antes de a Luna guardá-lo ou direto no painel da Meta. - Nome, idioma e conta de negócio **não** podem ser alterados. Para um nome diferente, crie outro template. - Se você informar qualquer componente, informe também `bodyText`: a Meta recusa template sem corpo. - A edição volta a submeter o template à aprovação, e o estado muda. Consulte o estado depois. `DELETE /v1/templates/{id}` responde `204`. ```bash curl -X DELETE "https://api.lunahia.com.br/v1/templates/YOUR_TEMPLATE_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/templates/YOUR_TEMPLATE_ID', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, }, }); console.log(res.status); ``` ```python import os import requests res = requests.delete( "https://api.lunahia.com.br/v1/templates/YOUR_TEMPLATE_ID", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, timeout=10, ) print(res.status_code) ``` > **A Meta remove template pelo NOME, e isso apaga todas as versões de idioma daquele nome.** Se você mantém o mesmo template em três idiomas, esta chamada apaga os três de uma vez do lado da Meta. A Luna remove da sua listagem só o que você pediu, e as outras versões de idioma continuam aparecendo aqui e já não existem lá. A remoção é definitiva, e criar outro com o mesmo nome recomeça a aprovação do zero. Remover duas vezes é seguro: a segunda chamada devolve `404`. ## Copiar para outros clientes A Meta cria template por conta de negócio, então quem opera muitos clientes repetia a criação conta a conta. `POST /v1/templates/{id}/copy` (escopo `templates:write`) faz o laço: recebe `targets`, de 1 a 50 destinos, cada um `{ "wabaId": "..." }` (a conta, pelo id dela na Meta) ou `{ "externalId": "..." }` (um cliente seu, e a cópia vai para cada conta de WhatsApp Business dos números dele). A Luna monta o corpo do conteúdo que ela guardou do template de origem e cria a cópia pelo mesmo caminho de `POST /v1/templates`, com as mesmas regras; a cópia nasce em análise na Meta, como qualquer template novo, com o mesmo nome e idioma. ```bash curl -X POST "https://api.lunahia.com.br/v1/templates/YOUR_TEMPLATE_ID/copy" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "targets": [ { "wabaId": "102290129340398" }, { "externalId": "cliente-43" } ] }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/templates/YOUR_TEMPLATE_ID/copy', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "targets": [ { "wabaId": "102290129340398" }, { "externalId": "cliente-43" } ] }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/templates/YOUR_TEMPLATE_ID/copy", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "targets": [ { "wabaId": "102290129340398", }, { "externalId": "cliente-43", }, ], }, timeout=10, ) print(res.status_code, res.json()) ``` A resposta é sempre `200` com `results`, **um resultado por destino** (por conta, quando um `externalId` tem mais de uma). Cada resultado traz `target` (o destino pedido), `wabaId`, `status` e, conforme o caso, `template` (o template criado, no mesmo formato de `POST /v1/templates`) ou `error` (o mesmo corpo de erro que a rota daria sozinha). `status` é `201` quando a cópia foi criada, ou o status do erro daquele destino: `404` para uma conta que não é sua ou um cliente que não existe, `422` quando a Meta recusou (já existe um template com esse nome, por exemplo). **Um destino que falha não derruba os outros**, e por isso o status da resposta não conta o que aconteceu com cada um: leia `results[].status`. Cada destino gasta uma unidade do limite de gestão da conta dele. - Template criado direto no painel da Meta, ou antes de a Luna guardar o conteúdo, responde `409` com `template_content_unknown`: sem o conteúdo não há o que copiar. Crie-o de novo por `POST /v1/templates` e copie o novo. - Com cabeçalho de mídia, mande `headerMediaHandle`: a Luna guarda só o formato do cabeçalho, não o arquivo de exemplo. Sem ele, `400` com `campos`. - Template de autenticação usa o caminho de autenticação e pede `authentication` (`codeExpirationMinutes`, e se quiser `addSecurityRecommendation`, `buttonText` e `messageSendTtlSeconds`): a Luna não guarda esses parâmetros. ## Template de autenticação Código de verificação tem uma rota de criação própria, `POST /v1/templates/authentication` (escopo `templates:write`), e não é uma categoria a mais em `POST /v1/templates`. O conteúdo não é seu: o corpo é fixo pela Meta, com o texto "{{1}} is your verification code." traduzido para o idioma do template. Por isso a rota não recebe corpo, exemplos, cabeçalho, rodapé nem botões. ```bash curl -X POST "https://api.lunahia.com.br/v1/templates/authentication" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "wabaId": "YOUR_WABA_ID", "name": "codigo_de_verificacao", "language": "pt_BR", "addSecurityRecommendation": true, "codeExpirationMinutes": 10 }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/templates/authentication', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "wabaId": "YOUR_WABA_ID", "name": "codigo_de_verificacao", "language": "pt_BR", "addSecurityRecommendation": true, "codeExpirationMinutes": 10 }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/templates/authentication", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "wabaId": "YOUR_WABA_ID", "name": "codigo_de_verificacao", "language": "pt_BR", "addSecurityRecommendation": True, "codeExpirationMinutes": 10, }, timeout=10, ) print(res.status_code, res.json()) ``` - Você escolhe o `name`, o `language`, se o aviso de segurança aparece (`addSecurityRecommendation`), em quantos minutos o código expira (`codeExpirationMinutes`, obrigatório) e, se quiser, o `buttonText` e o `messageSendTtlSeconds`. - Omitir `buttonText` é o recomendado: sem ele a Meta usa o rótulo padrão do idioma, que já vem traduzido. - No envio, o código de uso único vai **duas vezes** no corpo da mensagem: uma no componente de corpo e outra no componente de botão. É o formato, e não redundância a ser otimizada. A senha aceita no máximo 15 caracteres. O envio do código é um envio de template comum, com dois componentes: o código no corpo e o mesmo código no botão. O corpo abaixo segue o exemplo da página de copiar código da Meta, e a Luna o repassa sem mexer. O `index` vai como texto (`"0"`), que é como a Luna o lê, e o `sub_type` é `url`, que é o valor que a Meta mostra nesse exemplo mesmo para o botão de copiar código. ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "template", "template": { "name": "codigo_de_verificacao", "language": { "code": "pt_BR" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "482913" } ] }, { "type": "button", "sub_type": "url", "index": "0", "parameters": [ { "type": "text", "text": "482913" } ] } ] } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID(), }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "template", "template": { "name": "codigo_de_verificacao", "language": { "code": "pt_BR" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "482913" } ] }, { "type": "button", "sub_type": "url", "index": "0", "parameters": [ { "type": "text", "text": "482913" } ] } ] } }), }); console.log(res.status, await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "type": "template", "template": { "name": "codigo_de_verificacao", "language": { "code": "pt_BR", }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "482913", }, ], }, { "type": "button", "sub_type": "url", "index": "0", "parameters": [ { "type": "text", "text": "482913", }, ], }, ], }, }, timeout=10, ) print(res.status_code, res.json()) ``` - O código tem no máximo 15 caracteres. Acima disso a Luna responde `400` com `campos` antes de enfileirar, e o valor não volta no erro. - Mande para o telefone (`to`). Template de autenticação não vai para quem escreveu sem telefone visível (`recipient`): a Meta exige o telefone nele. - A Luna só cria o template de copiar código. Os de um toque e de zero toque dependem de um app Android seu e ficam fora por enquanto. > **O que ainda não foi conferido:** a Helsen ainda não rodou este envio contra a Meta com um template aprovado. Se a Meta recusar a forma do botão, a recusa chega como `message.status` com `failed` e o código do erro, e vale a página de copiar código da Meta. Gerar, guardar, expirar e conferir o código é do seu sistema: a Luna entrega a mensagem. > O contrato completo de cada rota está na [referência da API](https://lunahia.com.br/docs/referencia), na seção Templates. ## Detalhes das rotas deste guia A [referência da API](https://lunahia.com.br/docs/referencia) diz como chamar cada rota, em poucas linhas. O que explica o motivo de cada decisão, os casos de borda e os avisos está aqui, na ordem da referência. ### GET /v1/templates O status que volta aqui é o último que a Luna observou, e não uma leitura ao vivo na Meta. Para o estado atual de um template específico, use a consulta por identificador. Use ?wabaId= para ver só os templates de uma conta de negócio, ou ?phoneNumberId= (o UUID da Luna ou o id da Meta) para ver os da conta a que um número pertence: com um cliente seu por conta, é o jeito de separar os templates por cliente. Template é da conta, e não do número. Use ?status= para filtrar por estado, por exemplo ?status=PAUSED. A comparação é literal e sensível a maiúsculas, e o campo aceita qualquer texto: a Meta acrescenta estado sem aviso, e uma lista fechada impediria você de filtrar pelo estado novo no dia em que ele aparecesse. A categoria devolvida é a que a Meta atribuiu NA CRIAÇÃO, e pode não ser a que foi pedida, porque ela reclassifica. A Luna não a mantém depois disso: se a Meta reclassificar um template já aprovado, o valor que você lê aqui continua sendo o da criação. Para a categoria corrente, consulte o painel da Meta. Aprovado não significa liberado para disparo em massa. A Meta aplica um ritmo próprio de liberação nos primeiros envios. ### POST /v1/templates Template é o que permite iniciar conversa fora da janela de 24 horas. Dentro da janela, texto livre basta. O corpo aceita variável na forma {{nome_da_variavel}}: minúsculas e sublinhado. Toda variável exige um valor de amostra em examples, porque a Meta recusa parâmetro sem exemplo, e a recusa custa uma unidade do orçamento de gestão da conta. A categoria que volta na resposta é a que a Meta atribuiu, e pode não ser a que você pediu, porque ela reclassifica na criação. O que a Luna guarda é o que a Meta respondeu, nunca o que foi pedido. E ela é a categoria atribuída NA CRIAÇÃO: a Luna não a mantém depois disso. Para a categoria corrente de um template antigo, consulte o painel da Meta. Cada idioma é um template SEPARADO para a Meta. Dez templates em nove idiomas são noventa templates, e o teto é de 250 por conta de WhatsApp Business. O teto é da Meta, é o mesmo para todos os clientes: ele existe por capacidade da plataforma dela, e não varia. Aprovado não significa liberado para disparo em massa. A Meta aplica um ritmo próprio de liberação nos primeiros envios. Cabeçalho de mídia: use headerMedia com format IMAGE, VIDEO ou DOCUMENT e o handle devolvido por POST /v1/template-assets. Esse handle não é o identificador de mídia que POST /v1/numbers/{id}/media devolve: são dois endpoints da Meta com propósitos diferentes, e um identificador de mídia no lugar do handle faz a criação ser recusada. Para documento a Meta aceita apenas PDF. Nem GIF nem localização são aceitos, e isso é decisão e não esquecimento. O arquivo do headerMedia é o EXEMPLO que a Meta revisa, e não o conteúdo entregue. Cada mensagem que você enviar com este template fornece a própria mídia, no componente de cabeçalho do envio. Quem criar o template achando que a imagem do exemplo é a imagem enviada vai mandar mensagem sem cabeçalho. Os dois cabeçalhos são exclusivos: header é o de texto, headerMedia é o de mídia, e a Meta aceita um só por template. ### GET /v1/templates/{id} O estado é texto livre e não um conjunto fechado, de propósito: a Meta acrescenta valor novo sem aviso, e um conjunto fechado transformaria isso em erro da Luna. ### PATCH /v1/templates/{id} A atualização é PARCIAL: o que você não informar permanece como está. É por isso que o verbo é PATCH e não PUT: PUT prometeria substituir o template inteiro, e não é isso que acontece. Nome, idioma e conta de negócio NÃO podem ser alterados: a Meta não aceita mudá-los depois de o template criado. Para um nome diferente, crie outro template. Se você informar qualquer componente, informe também bodyText: a Meta recusa template sem corpo. A edição volta a submeter o template à aprovação, e o estado muda. Espere o evento template.status no seu endpoint de webhook, ou consulte o estado depois. ### DELETE /v1/templates/{id} ATENÇÃO: a Meta remove template pelo NOME, e isso apaga TODAS as versões de idioma daquele nome, e não apenas a que você está removendo. Se você mantém o mesmo template em três idiomas, esta chamada apaga os três de uma vez do lado da Meta. A Luna remove da sua listagem apenas o que você pediu: as outras versões de idioma continuam aparecendo aqui e já não existem lá. A consequência é da Meta, é destrutiva e não muda. A remoção é definitiva. Um template removido não volta, e criar outro com o mesmo nome recomeça a aprovação do zero. Remover duas vezes é seguro: a segunda chamada devolve 404, o mesmo 404 de um identificador que nunca existiu. ### POST /v1/templates/authentication Este é um caminho de criação separado, e não uma categoria a mais em POST /v1/templates. A razão é que o conteúdo não é seu: o corpo é fixo pela Meta e não é customizável, com o texto "{{1}} is your verification code." traduzido para o idioma do template, e a propriedade de texto não é aceita. Por isso esta rota não recebe corpo, exemplos, cabeçalho, rodapé nem botões. O que você escolhe é o nome, o idioma, se o aviso de segurança aparece, em quantos minutos o código expira e, se quiser, o rótulo do botão. O aviso de segurança e o aviso de expiração também são textos da Meta, gerados no idioma do template. O rótulo do botão, quando omitido, vem no idioma do template já traduzido, e omitir é o recomendado. A categoria que volta na resposta é a que a Meta atribuiu, como em toda criação, e a Luna guarda o que ela respondeu. Cada idioma é um template SEPARADO para a Meta, e o teto de 250 por conta de WhatsApp Business vale igual aqui. O teto é da Meta, é o mesmo para todos os clientes: ele existe por capacidade da plataforma dela, e não varia. Sobre o ENVIO, três coisas que valem saber antes de integrar. Primeira: o código de uso único vai DUAS VEZES no corpo da mensagem enviada, uma no componente de corpo e outra no componente de botão. Isso é o formato, e não redundância a ser otimizada. Segunda: a senha aceita no máximo 15 caracteres. Terceira, e esta é uma lacuna que preferimos declarar a preencher com chute: a forma exata do componente de botão no envio ainda não é publicada aqui, porque a documentação da Meta tem duas páginas em desacordo sobre ela e ninguém desta casa executou um envio para decidir. Ela será publicada quando houver essa execução. ### POST /v1/template-assets Este handle NÃO é o identificador de mídia que POST /v1/numbers/{id}/media devolve. São dois endpoints da Meta com propósitos diferentes: aquele serve para enviar mensagem, e este serve para o exemplo que a Meta revisa ao aprovar o template. Um identificador de mídia no lugar do handle faz a criação ser recusada. Na prática você reconhece a troca de longe: o identificador de mídia é um número decimal longo, e o handle não é numérico. O arquivo aqui é o EXEMPLO, e não o conteúdo entregue. Ele existe para que a Meta veja como o template fica. Cada mensagem que você enviar depois fornece a própria mídia. Quem criar o template achando que esta imagem é a que chega ao destinatário vai mandar mensagem sem cabeçalho. Os tipos aceitos são application/pdf, image/jpeg, image/jpg, image/png e video/mp4. A lista é mais estreita que a do upload de mídia de mensagem porque é a do endpoint que esta rota chama, e para documento ela aceita apenas PDF. Nem GIF nem localização entram, e isso é decisão e não esquecimento: o requisito nomeia imagem, vídeo e documento. O conteúdo do arquivo é conferido contra o tipo declarado antes de qualquer ida à Meta. Um arquivo declarado como image/png cujos bytes são de outra coisa é recusado com 400 aqui, para não gastar chamada sua. Um arquivo acima do teto é recusado com 413 antes de qualquer ida à Meta. O teto é o mesmo para todos os clientes: ele existe por capacidade de infraestrutura, e não varia. Quanto tempo o handle vale: a Meta não publica prazo de validade, e a Luna não guarda o valor. Obtenha o handle e use-o na criação do template em seguida. Se ele deixar de servir, suba o arquivo de novo. --- # Erros Fonte: https://lunahia.com.br/docs/erros Todo erro da API devolve um corpo JSON com `error` e `message`. O `error` é um código estável, pensado para o seu código decidir o que fazer. O `message` é texto para uma pessoa ler, em português. ## O formato do erro `400` ```json { "error": "invalid_request", "message": "Requisição inválida.", "campos": [{ "campo": "text.body", "motivo": "Não pode ficar vazio." }] } ``` - Decida pelo `error` e pelo status, nunca pelo texto do `message`. - Todo erro traz `docsUrl`, o endereço do guia do site que explica aquele `error` (os que não têm guia próprio apontam para esta página). Use-o no link "Saiba mais" da sua tela em vez de montar o endereço. - Alguns erros acrescentam campos que dizem o que fazer: `campos`, `fechadaEm`, `acaoRecomendada`, `estado`, `faltando`, `tentativasRestantes`, `janelaVira`, `reenfileiradoEm` e `credentialStatus`. Eles estão na tabela abaixo. - Nenhum erro repete de volta o valor que você mandou. Num `400`, o que sai é o caminho do campo recusado e o motivo, em uma frase curta, e nunca o conteúdo. - `404` vale também para um recurso que existe e não é seu. A API não confirma a existência de recurso de outro cliente, nem pelo status. ## Os códigos principais | Status | `error` | O que quer dizer, e o que fazer | | --- | --- | --- | | 400 | `invalid_request` | O corpo ou a query não bate com o contrato. O campo `campos` lista cada campo recusado em `campo` e o motivo em `motivo`, por exemplo "Curto demais: no mínimo 3 caracteres.", "Valor não aceito. Valores aceitos: text, image." ou, num campo de formato fixo como o telefone, o formato esperado ("Só dígitos, com o código do país e sem o sinal de mais"). O `motivo` é texto para ler, em português: decida pelo `campo`. Um parâmetro de query que a rota não conhece também é recusado, em toda rota `GET`, para um filtro escrito errado não devolver a lista inteira em silêncio. Corrija e envie de novo. Repetir o mesmo pedido repete a recusa. | | 401 | `unauthorized` | A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. Confira o cabeçalho `Authorization: Bearer hlsn_...` e se a chave não foi revogada. | | 403 | `forbidden` | A chave não tem o escopo da rota. O campo `requiredScope` diz qual escopo falta (por exemplo `numbers:read`), e a `message` o cita. Crie uma chave com esse escopo, e dê a cada chave só o que ela precisa. A resposta fala do verbo, e nunca do recurso. | | 403 | `test_key_not_allowed` | A chave é de teste e a rota não é do modo de teste. A chave de teste só usa `POST /v1/messages` e `POST /v1/test-mode/inbound-messages`. Para esta operação, use uma chave de produção. Veja [Modo de teste](https://lunahia.com.br/docs/modo-de-teste). | | 403 | `connection_not_released` | A conta ainda não pode abrir conexão de número. O campo `faltando` lista a condição (`email_confirmado`). Confirme o e-mail da conta. | | 403 | `trial_expired` | O teste grátis terminou. O envio e as demais escritas estão pausados, e a leitura e o recebimento continuam. Veja [Plano e números](https://lunahia.com.br/docs/plano-e-numeros#fim-do-teste). | | 403 | `account_blocked` | A Helsen bloqueou a conta. O efeito é o mesmo do teste terminado. Escreva para o comercial para saber o motivo. | | 404 | `not_found` | O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. Confira o identificador, e se ele é o da Luna ou o da Meta para esta rota. Quando o recurso que falta é apontado pelo corpo (o `from` de `POST /v1/messages`, por exemplo), `campos` diz qual campo foi, e a `message` diz onde achar o id certo (`GET /v1/numbers`). | | 409 | `number_capacity_reached` | A conta já tem tantos números ativos quanto a capacidade do plano. Desconecte um número com `DELETE /v1/numbers/{id}` ou amplie a capacidade com o comercial. Veja [Plano e números](https://lunahia.com.br/docs/plano-e-numeros#capacidade-atingida). | | 409 | `window_closed` | A [janela de 24 horas](https://lunahia.com.br/docs/glossario#janela) está fechada. `fechadaEm` diz quando fechou, e `acaoRecomendada` diz o caminho: enviar um template, e a mensagem livre volta quando o contato responder. Se o contato escreveu há pouco, confira que o `to` é o telefone do evento (`wa_id`). O `detalheTecnico` traz o resto, para quem já conferiu isso: a Luna acha o celular brasileiro com e sem o nono dígito, e nenhuma outra diferença, e quem escreveu só com BSUID leva `recipient`. Não há `Retry-After`, e repetir não adianta. Veja [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens#janela). | | 409 | `template_not_approved` | O template existe na sua conta, mas a Meta ainda não o aprovou, ou o rejeitou ou pausou. `templateStatus` traz o estado. Espere o evento `template.status` (ou leia `GET /v1/templates/{id}`), ou corrija o template. Template criado direto no painel da Meta não passa por esta conferência. | | 409 | `template_content_unknown` | A Luna não conhece o conteúdo do template que você pediu para copiar: ele foi criado direto no painel da Meta, ou antes de a Luna guardar o conteúdo. Crie o template de novo por `POST /v1/templates` e copie o novo. Veja [Templates](https://lunahia.com.br/docs/templates#copiar). | | 409 | `link_not_open` | Você pediu para gerar de novo a `url` de um link que não está aberto: `status` diz se ele foi usado, venceu ou foi revogado. Só um link aberto pode ser reemitido. Crie um link novo com `POST /v1/onboarding/links`. Veja [Conectar um número](https://lunahia.com.br/docs/conectar-numero). | | 409 | `message_not_cancelable` | Você pediu para cancelar uma mensagem que já não está na fila: `status` diz o estado atual (`sent`, `failed`, `canceled`, ou `accepted` quando o envio já foi reservado e está saindo). Só uma mensagem em `accepted` e ainda não reservada pode ser cancelada. Confira o resultado com `GET /v1/messages/{id}`. Veja [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens). | | 409 | `idempotency_key_reused` | A `Idempotency-Key` já foi usada com outro corpo, e nada foi enviado. Para repetir a mensagem original, reenvie o mesmo corpo com a mesma chave. Para uma mensagem nova, use uma chave nova. | | 409 | `media_not_ready` | A mídia ainda não foi obtida. O `estado` diz onde ela está: `pendente` e `falhou` voltam sozinhos, `expirado` é definitivo. Tente de novo mais tarde. No link do aviso (`GET /v1/media/{token}`), o `pendente` traz `Retry-After`: espere esse tempo. | | 409 | `no_webhook_endpoint` | Você pediu o reenvio de um webhook e não tem endpoint ativo. Cadastre um em `POST /v1/webhooks/endpoints`, ou retome um pausado com `PATCH /v1/webhooks/endpoints/{id}`, e peça de novo. | | 409 | `webhook_endpoint_limit` | O cliente já tem o máximo de endpoints de webhook (`limit`, hoje 25), igual para todos. Remova um com `DELETE /v1/webhooks/endpoints/{id}` para liberar a vaga. Veja [Receber eventos](https://lunahia.com.br/docs/receber-eventos#gerir). | | 409 | `already_requeued` | Este item da fila de rejeitados já foi re-enfileirado. `reenfileiradoEm` diz quando. Nada a fazer. | | 409 | `pin_not_applicable` | O número não está aguardando o PIN. O `state` diz em que ponto ele está. Veja [Conectar um número](https://lunahia.com.br/docs/conectar-numero#outro-provedor). | | 409 | `not_available_in_coexistence` | O número está em coexistência e a Meta não aceita esta operação por API nesse caso (hoje, o perfil do negócio). Faça a mudança no aplicativo WhatsApp Business do celular do negócio. Veja [O que o número faz na Meta](https://lunahia.com.br/docs/numero-na-meta#perfil). | | 422 | `meta_rejected` | A Meta recusou uma operação de gestão do número (perfil, bloqueio ou QR code). O campo `meta` traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa. Veja [O que o número faz na Meta](https://lunahia.com.br/docs/numero-na-meta). | | 409 | `register_budget_reserved` | As tentativas de registro que a Meta concede ao número em 72 horas estão perto do fim. `tentativasRestantes` e `janelaVira` dizem quantas sobram e quando a janela vira. Confirme o PIN com o negócio final antes de tentar de novo. | | 409 | `reconnect_not_applicable` | A autorização deste número não admite reconexão. `credentialStatus` diz o estado. | | 413 | `file_too_large` | O arquivo passa do teto de upload, que é o mesmo para todos os clientes. A recusa acontece antes de qualquer ida à Meta. Mande um arquivo menor. | | 429 | `rate_limited` | Você passou do limite de requisições da chave. Espere o tempo do `Retry-After`. Veja a [próxima seção](#limite). | | 429 | `queue_full` | A fila de envio deste número está cheia. Espere o tempo do `Retry-After` e tente de novo. | | 429 | `number_rate_limited` | Este número está no limite de chamadas por segundo. Espere o tempo do `Retry-After`. | | 429 | `management_busy` | As operações de gestão da conexão (criar e editar template, por exemplo) atingiram o limite momentâneo. Espere o tempo do `Retry-After`. | | 500 | `internal` | Falha inesperada do lado da Luna. O corpo não traz detalhe, e o detalhe fica no log interno. Tente de novo, e se persistir, peça ajuda com o horário e o identificador da mensagem. | | 503 | `unavailable` | A plataforma não pode atender agora. Tente de novo com espera crescente. Este mesmo corpo também aparece, de propósito, quando você tenta conectar uma conta ou número que já pertence a outro cliente: a API não confirma a existência de recurso alheio. Por isso, ao conectar, um `503` que se repete igual depois de três tentativas espaçadas não é indisponibilidade: pare de tentar e peça ao dono do número que o desconecte de onde ele está conectado, ou fale com o suporte. Na indisponibilidade de verdade, a espera passa e o mesmo pedido volta a funcionar. | Os quatro códigos `429` têm origem diferente, e a resposta traz o `Retry-After`, em segundos. Se ele faltar, espere com recuo crescente, como o código abaixo faz. O `429` da Luna **nunca** é o limite de ritmo da Meta devolvido a você: esse limite é resolvido por fila, e por isso o envio responde `202`. ## O limite de requisições Cada chave de API pode fazer **600 requisições por minuto**. O limite é técnico e idêntico para todos os clientes. Nenhum limite desta plataforma varia por preço. Requisição sem chave é contada pelo endereço de origem. Todos os limites juntos, com o que cada um faz quando você passa, estão em [Limites e ritmo](https://lunahia.com.br/docs/limites-e-ritmo). | Cabeçalho | O que traz | | --- | --- | | `X-RateLimit-Limit` | O teto da janela. | | `X-RateLimit-Remaining` | Quantas requisições ainda cabem na janela. | | `X-RateLimit-Reset` | Em quantos segundos a janela recomeça. | | `Retry-After` | Em respostas `429`: quantos segundos esperar antes de tentar de novo. | - Os três `X-RateLimit-*` acompanham as respostas bem-sucedidas. Leia `X-RateLimit-Remaining` e desacelere antes de chegar a zero. - Num `429`, espere o `Retry-After`. Retentar na hora só é recusado de novo. - O cadastro de conta tem um teto próprio: 5 por hora por endereço de origem. ### Retentar com segurança Repita só `429` e `503`, e espere o `Retry-After`. Para `POST /v1/messages`, mande sempre o `Idempotency-Key`, e **o mesmo** em todas as tentativas: sem ele, uma retentativa depois de um tempo esgotado pode enviar a mensagem duas vezes. Não repita `400`, `401`, `403`, `404` nem `409`: a resposta não muda. ```js const BASE = 'https://api.lunahia.com.br'; async function lunaFetch(path, options = {}, attempts = 5) { for (let attempt = 1; ; attempt++) { const res = await fetch(`${BASE}${path}`, { ...options, headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', ...options.headers, }, }); const retryable = res.status === 429 || res.status === 503; if (!retryable || attempt === attempts) return res; // Retry-After is in seconds. Without it, back off 2, 4, 8... seconds. const wait = Number(res.headers.get('retry-after')) || 2 ** attempt; await new Promise((resolve) => setTimeout(resolve, wait * 1000)); } } // One Idempotency-Key for all attempts, so a retry never sends twice. const res = await lunaFetch('/v1/messages', { method: 'POST', headers: { 'Idempotency-Key': crypto.randomUUID() }, body: JSON.stringify({ from: 'YOUR_PHONE_NUMBER_ID', to: '5511999990000', text: { body: 'Olá!' }, }), }); const body = await res.json(); if (!res.ok) { console.error(res.status, body.error, body.message); } else { console.log(res.status, body); } ``` ```python import os import time import uuid import requests BASE = "https://api.lunahia.com.br" def luna_request(method, path, attempts=5, **kwargs): headers = { "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", **kwargs.pop("headers", {}), } for attempt in range(1, attempts + 1): res = requests.request( method, BASE + path, headers=headers, timeout=10, **kwargs ) if res.status_code not in (429, 503) or attempt == attempts: return res # Retry-After is in seconds. Without it, back off 2, 4, 8... seconds. time.sleep(int(res.headers.get("Retry-After", 2**attempt))) # One Idempotency-Key for all attempts, so a retry never sends twice. res = luna_request( "POST", "/v1/messages", headers={"Idempotency-Key": str(uuid.uuid4())}, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511999990000", "text": {"body": "Olá!"}, }, ) body = res.json() if not res.ok: print(res.status_code, body["error"], body["message"]) else: print(res.status_code, body) ``` ## Quando a mensagem é aceita e depois falha O `202` do envio quer dizer que a Luna aceitou a mensagem, e não que ela foi entregue. A falha pode vir depois, da Meta, e você a vê de duas formas: no webhook, com um `message.status` de `status: "failed"`, o `error_code` e o objeto `error`, e em `GET /v1/messages/{id}`, no campo `erros`. Isso vale também quando a Meta recusa o envio na própria resposta (token revogado, número sem WhatsApp, parâmetro de template errado, janela fechada do lado dela, método de pagamento): a Luna dá a mensagem por falhada na hora, não tenta de novo, e o mesmo evento chega ao seu endpoint, com `wamid` nulo, porque a Meta nunca aceitou a mensagem. Correlacione pelo `id`. Uma falha passageira da Meta, como um tempo esgotado, não é falha: a Luna tenta de novo sozinha e nenhum `failed` é emitido. ```json { "codigo": 131026, "categoria": "nao_entregavel", "mensagem": "O destinatário não pode receber esta mensagem: o número não tem WhatsApp, ou não existe.", "acaoRecomendada": "Confira o número do destinatário e reenvie para o número correto. Repetir o envio para o mesmo número não muda o resultado.", "original": { "error": { "message": "Message undeliverable", "type": "OAuthException", "code": 131026, "fbtrace_id": "EXAMPLE_TRACE_ID" } } } ``` | Campo de `erros` | O que é | | --- | --- | | `codigo` | O código de erro da Meta, íntegro. Nulo quando não houve resposta da Meta: um tempo esgotado, por exemplo, não tem código. | | `categoria` | A natureza do erro, no vocabulário da Luna. Os valores são `parametro_invalido`, `reauth_required`, `recurso_inacessivel`, `orcamento_management`, `throughput_excedido`, `estado_de_produto`, `janela_de_atendimento`, `midia_indisponivel`, `nao_entregavel`, `template_invalido`, `ritmo_por_destinatario`, `terminal`, `transporte`, `contrato` e `desconhecido`. | | `mensagem` | O que aconteceu, em português. É texto da Helsen, e não a tradução da mensagem da Meta. | | `acaoRecomendada` | O que fazer, em uma frase acionável. | | `original` | O corpo de erro da Meta, sem reescrita e sem filtro. É o que o suporte da Meta reconhece. | - `desconhecido` é literal e deliberado: a Meta acrescenta códigos sem aviso, e um código ainda não mapeado chega com essa categoria em vez de ser escondido. Leia o `codigo` e o `original`. - `erros` reúne o que a Meta recusou na hora do envio e o que ela informou depois, por evento de status. Você não precisa saber de qual dos dois veio cada item: a `acaoRecomendada` é a que resolve. - **Cuidado ao repassar `original`.** Ele pode conter o telefone do consumidor final e trechos da conversa. Trate-o com o cuidado do restante do conteúdo das mensagens antes de mandá-lo a terceiros. - Ao pedir ajuda à Meta, o `fbtrace_id` dentro de `original` é o que faz um chamado avançar. > A referência da API traz o contrato de cada rota e os exemplos de corpo, na [referência da API](https://lunahia.com.br/docs/referencia). --- # Limites e ritmo Fonte: https://lunahia.com.br/docs/limites-e-ritmo A regra de todo limite da Luna cabe numa frase: ele existe por capacidade de infraestrutura e é igual para todos os clientes. Nenhum varia por preço. Esta página junta os que importam a quem envia muito, por exemplo um agente de IA, com o que cada um faz quando você passa dele. A lista viva, com o valor e o motivo de cada limite, está em `GET /v1/limits` (escopo `numbers:read`). O contrato de cada rota está na [referência da API](https://lunahia.com.br/docs/referencia). ## Os limites, numa tabela | Limite | Valor | O que acontece quando você passa | | --- | --- | --- | | Requisições por chave | 600 por minuto | `429` com `error: "rate_limited"` e `Retry-After`. Espere o tempo indicado. Veja [Erros](https://lunahia.com.br/docs/erros#limite). | | Rajada de cada conversa (o mesmo número de origem e o mesmo destinatário) | 30 mensagens de uma vez, depois uma a cada 7 segundos | Nada falha: a mensagem espera na fila e sai na ordem. O `202` volta igual, e esse limite nunca vira `429`. | | Envios por número | 55 por segundo (20 por segundo num número em coexistência) | O que passa do ritmo espera na fila e sai na ordem. O valor vivo está em `GET /v1/limits`. | | Fila de envio por número | 5.000 mensagens pendentes | `429` com `error: "queue_full"` e `Retry-After`, o tempo que a fila leva para escoar. Nada foi aceito: repita depois, com a mesma `Idempotency-Key`. | | `/read` e `/typing` | Dividem o ritmo por segundo do número | `429` com `error: "number_rate_limited"` e `Retry-After`. São síncronas e perdem o valor com o tempo: se passar, espere e tente, ou deixe para a resposta. | | Conversas novas por dia (da Meta) | A faixa de `limiteDiarioDeConversas` | A Meta recusa o envio e o motivo chega em `message.status` com `failed`. Veja a seção abaixo. | | Operações de gestão da conta de negócio (criar e editar template, por exemplo) | 150 por hora numa conta sem número registrado, e 3.750 por hora com número | `429` com `error: "management_busy"` e `Retry-After`. O teto é compartilhado com a conexão do número, então um laço que cria muitos templates pode atrasar uma conexão. | | Texto de uma mensagem | 4096 caracteres | `400` com `campos`. Veja [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens#basico). | | `typingMs` | De 1 a 25000 milissegundos | `400` com `campos`. Veja [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens#lida-e-digitando). | | Arquivo enviado à Luna | 100 MB | `413` com `error: "file_too_large"`, antes de qualquer chamada à Meta. | | Endpoints de webhook por conta | 25 | `409` com `error: "webhook_endpoint_limit"`. Remover um libera a vaga. | | Tempo que o seu endpoint tem para responder | 10 segundos | A entrega conta como falha e é retentada. Veja [Receber eventos](https://lunahia.com.br/docs/receber-eventos#entrega). | > Por que a rajada é de 30 e uma a cada 7 segundos, e não os números da Meta? A Luna opera com folga sobre o que a Meta publica, porque a contagem dela não é visível de fora. Você não precisa se ajustar a isso: a Luna aceita, enfileira e entrega no ritmo certo. ## O que espera e o que falha Há duas famílias de limite, e a diferença decide o seu código. Os de **ritmo** (a rajada de cada conversa e os envios por número) nunca falham: a mensagem é aceita com `202` e a Luna a entrega quando o ritmo permite, na ordem. Os de **recusa** (requisições por chave, fila cheia, `/read` e `/typing`) respondem `429` com `Retry-After`, e nada foi aceito. - Num `429`, espere o `Retry-After` e repita **com a mesma `Idempotency-Key`**: se a primeira tentativa chegou, a repetição devolve a mensagem original em vez de enviar duas vezes. - Um agente que responde em rajada não precisa de `sleep` entre as mensagens: a espera acontece na fila da Luna. - A rajada vale **dentro de cada conversa**: uma conversa lenta não atrasa as outras do mesmo número. - O estado de uma mensagem que espera é `queued`, e o `sent` chega quando ela sai. Veja [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens#estados). - O código de repetição pronto, em Node e Python, está em [Erros](https://lunahia.com.br/docs/erros#limite). ## O limite diário de conversas Este é um limite **da Meta**, e a Luna só o mostra. `GET /v1/numbers` devolve, em cada número, `limiteDiarioDeConversas`: o nome da faixa em que a Meta colocou o portfólio empresarial (`TIER_250`, `TIER_2K`, `TIER_10K`, `TIER_100K` ou `TIER_UNLIMITED`; a Meta pode acrescentar outras). Ele conta pessoas únicas a quem o negócio **começa** conversa fora da janela de atendimento, num período de 24 horas, e não mensagens, e é o mesmo para todos os números do portfólio. Conversar com quem escreveu primeiro, dentro da [janela de 24 horas](https://lunahia.com.br/docs/glossario#janela), não conta. - O campo diz o teto que a Meta concedeu, e **nunca** quanto você já usou. Não há rota que devolva o consumo. - **O limite inicial.** Um portfólio empresarial novo começa em `TIER_250`: 250 pessoas únicas a quem você começa conversa por período de 24 horas ([documentação da Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/messaging-limits)). Quem **escreveu primeiro** dentro da janela de atendimento não conta. Para subir, a Meta pede a verificação do negócio (ou do parceiro que o conectou), ou o envio de 2.000 mensagens entregues fora da janela, a pessoas únicas e com templates de boa qualidade, em 30 dias; depois disso a subida é automática (10 mil, 100 mil, sem limite) com qualidade alta e uso de metade do limite atual em 7 dias. Para um cliente novo, planeje o primeiro envio em massa abaixo de 250 pessoas por dia. - Quando a Meta muda a faixa, o evento `account.limit_changed` avisa. Veja [Saúde da conta](https://lunahia.com.br/docs/saude-da-conta). - Passou do teto: a Meta recusa o envio e o motivo chega em `message.status` (`failed`), no campo `error`. Veja [Erros](https://lunahia.com.br/docs/erros#envio). - Não confunda com `throughputLevel`, que é a **velocidade** (mensagens por segundo) e não a quantidade de conversas. ## O que nenhum limite é Nenhum limite desta página é uma cota por plano. O plano da Luna define uma coisa só: quantos números a conta mantém ativos ([Plano e números](https://lunahia.com.br/docs/plano-e-numeros)). O teto de requisições, o ritmo e a fila são os mesmos para todos, e existem por capacidade. --- # Saúde da conta Fonte: https://lunahia.com.br/docs/saude-da-conta Quando a Meta restringe, desativa ou desconecta a conta do seu cliente, o envio para de funcionar e o agente dele fica mudo. A Luna repassa esses avisos como eventos e guarda o último estado, para o seu sistema agir na hora em vez de descobrir pelo cliente final. ## Um aviso da conta, um evento por número A Meta avisa a **conta de negócio** (a WABA), e não um número. O envelope da Luna é por número, então cada aviso sai **uma vez para cada número conectado da conta**, todos com o mesmo `waba_id` dentro do objeto `waba`. Para tratar o aviso uma só vez, junte pelo `waba_id`. Conta sem nenhum número conectado não gera evento; o estado dela continua em `GET /v1/business-accounts`. | Evento | Quando sai | O que o seu sistema faz | | --- | --- | --- | | `account.restricted` | A Meta restringiu a conta. | Ler o tipo e o prazo, avisar o cliente, ajustar o que a restrição impede. | | `account.violation` | A Meta registrou uma violação de política. | Tratar a causa antes que vire restrição. | | `account.disabled` | A Meta desativou a conta. | Parar de tentar enviar e pedir revisão à Meta. | | `account.reinstated` | A Meta reativou a conta. | Voltar a enviar. | | `number.disconnected` | O número deixou de estar conectado à Luna. | Abrir um novo link de conexão. | | `account.limit_changed` | A Meta mudou o limite da conta. | Ajustar o ritmo de envio ao novo teto. | | `number.quality_changed` | A qualidade do número mudou. | Reduzir o que gera reclamação. | | `account.alert` | A Meta mandou um alerta sobre a conta (`account_alerts`). | Ler o `alert_type` e a descrição, e avisar o cliente. | | `number.credential_expiring` | A autorização que o cliente deu à Luna vence em até 14 dias. | Abrir um link de reconexão do número e mandar ao cliente. | | `account.update` | Outro aviso de conta que a Luna não traduz. | Ler o `event` cru e decidir, ou ignorar. | ## Onde ler o estado, sem webhook A Meta não oferece consulta desse estado. A Luna guarda o último aviso que recebeu e o devolve em dois lugares. Em `GET /v1/business-accounts`, cada conta traz `status`, com `restricted`, `restrictions`, `disabled`, `violationType` e `reportedAt`. Em `GET /v1/numbers` e `GET /v1/numbers/{id}`, cada número traz `waba`, com `id`, `restricted` e `disabled`, pronto para uma tela mostrar sem calcular nada. Os dois lugares também trazem a validade da autorização do cliente (`credentialExpiresAt` e `credentialNeverExpires`) e a forma de pagamento na Meta (`paymentMethodOnMeta` e `currency`), descritas nas seções abaixo. Uma conta restrita, em GET /v1/business-accounts ```json { "id": "ed404df1-b420-4ed6-8743-ba1609892e0a", "wabaId": "102290129340398", "numbers": ["+55 11 90000-0000"], "status": { "restricted": true, "restrictions": [ { "restrictionType": "RESTRICTED_ADD_PHONE_NUMBER_ACTION", "expiration": "2026-11-13T12:00:00Z", "remediation": null } ], "disabled": false, "violationType": null, "reportedAt": "2026-10-13T12:00:00.000Z" }, "createdAt": "2026-08-07T11:27:41.208Z" } ``` > `restricted` só vale enquanto o prazo da restrição não passou, porque a Meta não avisa o fim de uma restrição por prazo. Se o prazo não puder ser lido como data, a restrição conta como ativa até um novo aviso, e `restrictions` devolve o valor como a Meta mandou para você conferir. ## Conta restrita: `account.restricted` **O que significa.** A Meta impôs uma restrição à conta. O que ela impede depende do tipo, em `restrictions[].restriction_type` (por exemplo, adicionar números ou iniciar conversas). `expiration` traz o prazo como a Meta informou e `remediation` traz a orientação dela, quando há. ```json { "version": "2026-11-10", "event_id": "d3b1b97cb8b69ac0bf9db087b5200febbea3dcbcc8d0a4108913592b51fdaf29", "event_type": "account.restricted", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "waba": { "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "restrictions": [ { "restriction_type": "RESTRICTED_ADD_PHONE_NUMBER_ACTION", "expiration": "2026-11-13T12:00:00Z", "remediation": null } ] } } ``` - **Causa.** Costuma vir de reclamações, de bloqueios pelos contatos ou de uso fora da política da Meta. A restrição por abuso de template de utilidade, por exemplo, segue uma escada de avisos da Meta antes de chegar aqui. - **Solução.** Leia o tipo e o prazo, e avise o seu cliente. Quem trata a causa é o dono da conta, no WhatsApp Manager da Meta, pelo caminho que a própria Meta indica no aviso. Enquanto durar, não insista no que a restrição impede. - **Como saber que acabou.** A Meta não avisa o fim de uma restrição por prazo. Confira `expiration`, ou leia `status.restricted` em `GET /v1/business-accounts`, que deixa de valer quando o prazo passa. ## Violação de política: `account.violation` **O que significa.** A Meta registrou uma violação de política na conta, com o tipo em `violation_type`. É um aviso: a conta pode ser restringida ou desativada se a violação não for tratada. ```json { "version": "2026-11-10", "event_id": "a2fa828795bf24fd8e7460738c1a1e11a1bcd278fc09a0d238f92ba8c5994441", "event_type": "account.violation", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "waba": { "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "violation_type": "ALCOHOL_VIOLATION" } } ``` - **Causa.** Conteúdo ou comportamento que a política da Meta não permite, indicado pelo tipo. - **Solução.** Descubra qual conteúdo ou fluxo gerou a violação, corrija e avise o dono da conta. Violação não expira sozinha: `status.violationType` guarda o último tipo avisado. ## Conta desativada e reativada: `account.disabled` e `account.reinstated` **O que significa.** `account.disabled` diz que a Meta desativou a conta: os envios deixam de ser aceitos. `account.reinstated` diz que ela voltou. A Meta também avisa uma desativação **agendada**, e esse aviso chega como `account.update` com `event` igual a `DISABLED_UPDATE`, porque a conta ainda não está desativada. Desativada ```json { "version": "2026-11-10", "event_id": "b0308dcc1ab6324eaea0474f1bcdec28146d3a6eb62668a1425fb3a7d6aad778", "event_type": "account.disabled", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "waba": { "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "ban_date": "2026-10-13" } } ``` Reativada ```json { "version": "2026-11-10", "event_id": "135a9c7b3f192a7cab5ea55f68e0a8113e8d8e80acaa0ae8dad7f20aaf61f2db", "event_type": "account.reinstated", "occurred_at": "2026-10-14T09:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "waba": { "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "ban_date": null } } ``` - **Causa.** Violação grave ou repetida da política da Meta, ou uma restrição que não foi resolvida. - **Solução.** O dono da conta pede a revisão à Meta. A Luna não reativa conta e não tem como pedir isso por ele. Enquanto estiver desativada, pare de enviar: cada tentativa só falha. - **Como saber que voltou.** Pelo `account.reinstated`, ou por `status.disabled` igual a `false` em `GET /v1/business-accounts`. ## Número desconectado: `number.disconnected` **O que significa.** O número deixou de estar conectado à Luna. É o par de `number.connected`. O campo `reason` diz o aviso da Meta que causou a desconexão: `PARTNER_APP_UNINSTALLED` (o cliente removeu o aplicativo), `PARTNER_REMOVED` (a Luna foi removida como parceira da conta) ou `ACCOUNT_OFFBOARDED` (o vínculo da conta com a Luna foi encerrado). `disconnection_reason` e `initiated_by` trazem o que a Meta informou, quando informa. ```json { "version": "2026-11-10", "event_id": "0dfe4e31d4e40e4a5da6d3f42f0d44b660f67ce551b2a43966e5fb0390fcd741", "event_type": "number.disconnected", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "waba_id": "102290129340398", "reason": "PARTNER_APP_UNINSTALLED", "disconnection_reason": null, "initiated_by": null } } ``` - **Causa.** Quase sempre, o próprio cliente removeu o aplicativo no Business Manager dele. - **Em que estado o número fica.** Depende da causa, e o nome do evento não é o nome do estado. Quando o cliente remove o aplicativo (`PARTNER_APP_UNINSTALLED`), a autorização dele deixa de valer: o número fica com `connection.status: "action_required"`, `canSend: false` e o motivo `credential_invalid` em `connection.reasons`, e a reconexão é pelo link (`POST /v1/onboarding/links` com `numberId`). Quando **você** desconecta com `DELETE /v1/numbers/{id}` (`reason: "requested_by_tenant"`), o número fica `connection.status: "disconnected"`, `canSend: false` e `reasons` vazio. Para `PARTNER_REMOVED` e `ACCOUNT_OFFBOARDED` o evento é entregue, mas hoje só a desinstalação muda o estado do número sozinha: confira `connection` antes de concluir que ele parou. Então decida pelo `reason` do evento, ou leia `connection` em `GET /v1/numbers/{id}`, e não espere sempre `disconnected`. - **Solução.** Os envios deste número não funcionam mais. Para voltar, o seu cliente precisa conectar de novo: abra um novo link de conexão (veja [Conectar um número](https://lunahia.com.br/docs/conectar-numero)) e peça a ele para concluir. O histórico de mensagens continua em `GET /v1/messages`. ## Limite da conta: `account.limit_changed` **O que significa.** A Meta mudou o limite da conta. `daily_conversation_limit` é o limite de mensagens da Meta, no nome de faixa dela: `TIER_250`, `TIER_2K`, `TIER_10K`, `TIER_100K` ou `TIER_UNLIMITED` (250, 2.000, 10.000 e 100.000 pessoas por período de 24 horas, ou sem teto). Ele conta pessoas únicas a quem o negócio escreve fora da janela de atendimento, e não mensagens, e é do **portfólio empresarial** (business portfolio), compartilhado por todos os números dele. E `max_phone_numbers_per_waba` é o de números da conta. Um dos dois vem `null` quando o aviso mudou só o outro. É o teto concedido pela Meta, e nunca quanto foi usado. O limite é do portfólio de negócio, então vale para todos os números da conta. ```json { "version": "2026-11-10", "event_id": "a3bddf693de91539edaebb432d0d4f936b40822085cafa5c7864ae149756dbff", "event_type": "account.limit_changed", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "waba": { "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "daily_conversation_limit": "TIER_2K", "max_phone_numbers_per_waba": null } } ``` - **Causa.** A Meta sobe o limite quando a qualidade é boa e o volume pede, e baixa quando a qualidade cai. - **Solução.** Ajuste o ritmo de envio ao novo teto. O valor corrente de cada número está em `limiteDiarioDeConversas`, em `GET /v1/numbers`. ## Qualidade do número: `number.quality_changed` **O que significa.** A avaliação de qualidade do número mudou, de `previous_quality_rating` para `quality_rating` (`GREEN`, `YELLOW`, `RED`). A Meta não tem webhook para isso: a Luna confere a qualidade de cada número periodicamente, e o evento sai quando a conferência vê a mudança. Ele chega com atraso de até cerca de uma hora. ```json { "version": "2026-11-10", "event_id": "cc81de4eb28ad6a80e39c6cca13eb4b6db12f223f3c1346552cbc24795bcdbbe", "event_type": "number.quality_changed", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "waba_id": "102290129340398", "previous_quality_rating": "GREEN", "quality_rating": "YELLOW" } } ``` - **Causa.** Os contatos bloqueiam ou denunciam o número, ou reclamam das mensagens. - **Solução.** Reduza o que gera reclamação: mensagens que o contato não pediu, frequência alta, conteúdo fora do esperado. Qualidade baixa leva à queda de limite e, depois, à restrição. O histórico está em `GET /v1/numbers/{id}/health`. ## Autorização perto de vencer: `number.credential_expiring` **O que significa.** A autorização que o seu cliente deu à Luna para operar o número vence em até 14 dias (`credential_expires_at`). Essa autorização pode ter prazo (a configuração de conexão atual a emite com validade de 60 dias); quando ela vence, a Meta recusa as chamadas da Luna nessa conta e o número para de enviar e de receber. Este é o único aviso da família que **vem antes** do problema. A Luna lê a validade na conexão e confere de hora em hora, e o aviso sai **uma vez por vencimento e por número da conta**: renovar a autorização muda o vencimento e permite um aviso novo. Autorização emitida sem prazo nunca gera o evento. ```json { "version": "2026-11-10", "event_id": "33b03111fe7f1f225626ece55b50955389e78742a6b99059f05be056ce2b2260", "event_type": "number.credential_expiring", "occurred_at": "2026-11-21T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "waba_id": "102290129340398", "credential_expires_at": "2026-12-05T12:00:00.000Z" } } ``` - **Causa.** O prazo da própria autorização. Nada deu errado do lado do seu cliente. - **Solução.** Crie um link de reconexão com `POST /v1/onboarding/links` informando `numberId`, e mande ao seu cliente. A página abre direto a renovação daquele número, não conta um número novo e mantém o seu `externalId`. O mesmo vale se `credentialStatus` já for `reauth_required`. A decisão de que a renovação cabe é da API: o campo `podeReconectar` de `GET /v1/numbers/{id}` passa a `true` a 14 dias do vencimento. - **Onde ler sem webhook.** `credentialExpiresAt` (a data) e `credentialNeverExpires` (`true` quando a Meta informou que não vence, nulo enquanto a Luna não leu) em `GET /v1/business-accounts` e no objeto `waba` de cada número. ## Alerta da Meta: `account.alert` **O que significa.** A Meta mandou um alerta sobre a conta (o campo `account_alerts`), por exemplo a negativa de um aumento de limite (`INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED`, `INCREASED_CAPABILITIES_ELIGIBILITY_FAILED` ou `INCREASED_CAPABILITIES_ELIGIBILITY_NEED_MORE_INFO`) ou a perda da foto de perfil (`PROFILE_PICTURE_LOST`). Os campos chegam como a Meta mandou, sem tradução e sem lista fechada de valores: `entity_type`, `entity_id`, `alert_severity`, `alert_status`, `alert_type` e `alert_description`. O que a Luna ainda não nomeia vai em `details`. Como os outros avisos de conta, sai um evento por número conectado, todos com o mesmo `waba_id`. ```json { "version": "2026-11-10", "event_id": "fb613a0660724669d9251d4185488ec26409b34345c592b908ce9747b8430f99", "event_type": "account.alert", "occurred_at": "2026-10-19T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "waba": { "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "entity_type": "WABA", "entity_id": "102290129340398", "alert_severity": "INFORMATIONAL", "alert_status": "ACTIVE", "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED", "alert_description": "Messaging limit increase deferred.", "details": {} } } ``` - **Causa.** Depende do `alert_type`. O texto em `alert_description` é o da Meta. - **Solução.** Mostre o alerta ao dono da conta e deixe que ele trate no WhatsApp Manager da Meta. Trate valores novos de `alert_type` como informação, e não como erro: a Meta acrescenta tipos sem aviso. ## Outros avisos: `account.update` Todo aviso de conta da Meta que não tem tipo próprio chega como `account.update`, com o campo `event` cru dela e o restante em `details`: `ACCOUNT_DELETED`, `ACCOUNT_RECONNECTED`, `VOLUME_BASED_PRICING_TIER_UPDATE`, a desativação agendada e o que a Meta acrescentar. A Luna não inventa um significado para eles. Se o seu sistema não usa, ignore. ```json { "version": "2026-11-10", "event_id": "f663ad9f077e865db5d29245db96fe579e9aaa487bdf2f9d91a6e535af3d7949", "event_type": "account.update", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "waba": { "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "event": "ACCOUNT_DELETED", "details": {} } } ``` ## O que a Luna não faz - Não levanta restrição, não reativa conta e não pede revisão à Meta. Isso é do dono da conta. - Não consulta o estado na Meta: ela não oferece essa consulta. O estado que a Luna devolve é o do último aviso que recebeu. - Não bloqueia o seu envio por causa de uma restrição. Quem recusa é a Meta, e a recusa chega como erro na mensagem. - Não cobra nada por esses avisos. A falta de método de pagamento na Meta tem guia próprio: [Pagamento na Meta](https://lunahia.com.br/docs/pagamento-na-meta). Os eventos têm o formato completo em [Receber eventos](https://lunahia.com.br/docs/receber-eventos), e os campos estão na [referência da API](https://lunahia.com.br/docs/referencia). A mudança de categoria e de qualidade de **template** está em [Templates](https://lunahia.com.br/docs/templates). ## Detalhes das rotas deste guia A [referência da API](https://lunahia.com.br/docs/referencia) diz como chamar cada rota, em poucas linhas. O que explica o motivo de cada decisão, os casos de borda e os avisos está aqui, na ordem da referência. ### GET /v1/numbers/{id}/health limiteDiarioDeConversas é o LIMITE DE MENSAGENS da Meta, do portfólio empresarial (business portfolio) e não de cada número: conta pessoas únicas a quem a empresa escreve fora da janela de atendimento, nas faixas TIER_250, TIER_2K, TIER_10K, TIER_100K e TIER_UNLIMITED. throughputLevel é VELOCIDADE, quantas mensagens por segundo a Meta processa. Cada transição carrega o valor vigente naquele ponto, e é assim que se descobre quando o limite subiu ou desceu. Nenhum dos dois conta o que já foi usado. E há teto que sobe e teto que não sobe. throughputLevel descreve uma progressão que a Meta sobe sozinha conforme a qualidade do número. Um número conectado em coexistência, que continua funcionando no aplicativo de celular do negócio, tem teto FIXO e não entra nessa progressão. Quem separa os dois casos é tetoDeVazaoPorSegundo, logo ao lado: com valor, ele diz o teto fixo em mensagens por segundo; nulo, a progressão vale para este número. O valor vem do que a plataforma observou no tráfego, e não do rótulo que a Meta devolveu. sincronizacaoDoHistorico conta a importação das conversas anteriores do aparelho, num número conectado em coexistência, e são QUATRO situações e não três. Nulo significa que não há importação para este número. em_curso significa que ela está acontecendo, e sincronizacaoPrazo diz até quando: passado esse instante sem concluir, a plataforma da Meta desconecta o negócio final. concluida significa que terminou, e as conversas antigas já aparecem em GET /v1/messages. recusada significa que o dono do negócio recusou compartilhar no aparelho dele, e aí não vai concluir e pedir de novo não muda isso. Não leia o percentual sozinho. sincronizacaoProgresso é um rótulo que a plataforma da Meta atribui, e cem por cento NÃO significa sucesso: a recusa chega com o progresso que já havia sido registrado. Quem diz o desfecho é sincronizacaoDoHistorico, e só ele. E ausência não é progresso zero: nulo é não haver importação, e zero é uma importação que começou e ainda não andou. A lista de transições traz uma entrada por MUDANÇA, e não uma por verificação. Um número cuja avaliação nunca mudou desde a conexão devolve a lista vazia, e isso significa estabilidade: não trate lista vazia como ausência de dado. Quem separa os dois casos é checkedAt. Com instante, a plataforma perguntou à Meta e não encontrou mudança. Nulo, a verificação ainda não aconteceu para este número. As transições vêm da mais recente para a mais antiga. --- # Pagamento na Meta Fonte: https://lunahia.com.br/docs/pagamento-na-meta A Meta cobra o uso do WhatsApp do negócio dono do número, no método de pagamento dele. Quando esse método falta ou tem problema, a Meta recusa os envios com o erro 131042. A Luna marca o número, avisa por evento e diz o que fazer. Quem resolve é o dono da conta, na Meta. ## O que acontece quando falta A Meta recusa o envio com o erro `131042`. O número continua conectado e registrado, e a Luna não o desliga. Nada disso é falha da plataforma: falta algo do lado do negócio dono da conta. | O quê | Com o número em espera | | --- | --- | | Mensagem livre ou template | A Meta recusa com `131042`. A mensagem vira `failed`, e o erro chega em `message.status` e em `GET /v1/messages/{id}`. | | Mensagem recusada | A Luna não tenta de novo e não a reenvia sozinha. Quem reenvia é o seu sistema, depois que o pagamento for regularizado. | | O que a Meta enviar para o número | A Luna entrega como sempre. A espera não desliga o número nem a assinatura de eventos do lado da Luna. | | O estado do número | `state` continua `REGISTERED`. O que muda é `awaitingPaymentSince`, que passa a ter a data. | | A assinatura da Luna | Não muda. A Luna cobra a capacidade de números do plano, e o número em espera continua sendo capacidade configurada. | ## Saber antes da primeira falha Desde 1º de outubro de 2026 a Meta entrega as mensagens de serviço de cada número até a franquia gratuita de 1.000 por mês, e, se a conta de WhatsApp do negócio **não tem forma de pagamento**, deixa de entregar as seguintes. Descobrir isso pelo erro `131042` é descobrir com o agente já mudo. Por isso a Luna lê, da conta de negócio, o `primary_funding_id` e a `currency`: na conexão e depois de hora em hora, dentro do limite de chamadas da Meta. Ausência de `primary_funding_id` é a regra da própria Meta para "a conta não tem forma de pagamento". O resultado está em `GET /v1/business-accounts` e no objeto `waba` de cada número (`GET /v1/numbers` e `GET /v1/numbers/{id}`): `paymentMethodOnMeta` é `true`, `false` ou `null` enquanto a Luna ainda não leu, e `currency` é a moeda que a Meta informou para a conta. Com `false`, peça ao dono da conta que cadastre a forma de pagamento no WhatsApp Manager da Meta, como em [Como resolver](#solucao). O console mostra o aviso "Sem forma de pagamento na Meta" a partir desse campo. > `true` quer dizer que há uma forma de pagamento ligada à conta, e não que ela está em dia: linha de crédito acima do limite e conta de pagamento sem moeda ainda causam o `131042`. A Luna não vê o cartão, não vê saldo e não intermedeia esse pagamento. O pagamento é do negócio com a Meta. **O aviso por webhook, sem esperar a recusa.** Quando a leitura acha a conta sem forma de pagamento, a Luna publica `number.action_required` para cada número da conta, com o motivo `payment_method_missing` na lista `reasons`; quando a forma de pagamento aparece, publica `number.action_resolved`. O evento sai em até alguns minutos da leitura, uma vez por passagem. Não é o `number.payment_required`: este só sai quando a Meta **recusa um envio** (`131042`, abaixo). Se as duas coisas acontecem, `reasons` traz só `payment_required`, o motivo mais forte, e você não recebe dois avisos pelo mesmo fato. **Conferir agora.** O seu cliente disse que cadastrou o cartão? `POST /v1/business-accounts/{id}/payment-method/check` lê na Meta na hora, sem esperar a próxima leitura (o `id` é o de `GET /v1/business-accounts`; a chave precisa do escopo `numbers:read`). A resposta traz `paymentMethodOnMeta`, `currency`, `checkedAt` e `reason`: `checked` (leu agora), `recent` (a última leitura tem menos de 60 segundos e foi devolvida sem chamar a Meta), `busy` (o orçamento de chamadas da Meta para esta conta está no limite; tente de novo em alguns minutos) ou `failed` (a Meta não respondeu; o valor é o anterior). O limite existe porque estas leituras saem do mesmo orçamento de chamadas da conta que a conexão usa. O console tem o botão "Conferir agora" no cartão "Pagamento na Meta" e no detalhe do número. O evento sai pelo caminho de sempre, na leitura seguinte do laço de avisos. ## Como detectar A Meta não tem campo nem webhook de pagamento, e a Luna não consulta o estado dele: o único sinal é o erro na resposta a um envio. A Luna transforma esse sinal em três coisas que você pode ler. 1. **O campo do número.** `awaitingPaymentSince` em `GET /v1/numbers` e em `GET /v1/numbers/{id}` traz o instante da primeira recusa, ou `null` quando não há espera. 2. **O evento `number.payment_required`.** Sai uma vez, quando o número entra na espera, e não a cada mensagem recusada. Veja [Receber eventos](https://lunahia.com.br/docs/receber-eventos). 3. **O erro na mensagem.** Cada mensagem recusada chega em `message.status` com `status: "failed"` e `error_code: 131042`, e `GET /v1/messages/{id}` devolve o erro com a explicação e a `acaoRecomendada`. Veja [Erros](https://lunahia.com.br/docs/erros#envio). O evento de entrada na espera ```json { "version": "2026-11-10", "event_id": "50a49cee4b216c529e3f7cdd0be525f8902ff6aff66439e004dfe34a0c979fcf", "event_type": "number.payment_required", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "awaiting_payment_since": "2026-10-13T12:00:00.000Z" } } ``` O campo no número ```json { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "metaPhoneNumberId": "123456789012345", "state": "REGISTERED", "ready": true, "awaitingPaymentSince": "2026-10-13T12:00:00.000Z" } ``` O erro na mensagem ```json { "id": "ae60f288-7565-4315-a440-3663e9c231e1", "status": "failed", "erros": [ { "codigo": 131042, "categoria": "estado_de_produto", "mensagem": "Há um problema com o método de pagamento da conta comercial do negócio final na Meta. O número segue configurado; o que falta é do lado do negócio final.", "acaoRecomendada": "O negócio dono da conta de WhatsApp precisa cadastrar ou regularizar o método de pagamento no WhatsApp Manager da Meta (Billing Hub). A Luna não intermedeia esse pagamento e não consulta a situação dele: a Meta não oferece essa consulta. Depois que ele regularizar, envie de novo: a mensagem recusada não é reenviada sozinha, e o número volta ao normal quando um envio for aceito.", "original": { "error": { "code": 131042, "type": "OAuthException", "fbtrace_id": "AbCdEfGhIjK" } } } ] } ``` > `ready` não leva o pagamento em conta: ele diz que o número está registrado e com a inscrição confirmada. Um número com `ready: true` pode estar em espera por pagamento, e quem diz isso é `awaitingPaymentSince`. ## Causas O erro `131042` da Meta cobre mais de uma situação, e a Meta não diz qual delas é a do seu cliente. As causas que ela lista: - Não há método de pagamento ligado à conta de WhatsApp do negócio. - A conta de pagamento existe, mas não está ligada à conta de WhatsApp. - A linha de crédito da conta está inativa ou acima do limite. - A conta de WhatsApp foi apagada ou suspensa. - Fuso horário ou moeda da conta de pagamento não estão definidos. - Um pedido de pagamento em nome de outra empresa está pendente ou foi negado. ## Como resolver Quem resolve é o negócio dono da conta de WhatsApp, e ninguém mais: o pagamento é entre ele e a Meta. Peça ao seu cliente para entrar no WhatsApp Manager da Meta, abrir o Billing Hub da conta de WhatsApp dele e cadastrar ou regularizar o método de pagamento, conferindo as causas acima. Um texto que você pode mandar a ele: Sugestão de mensagem ao cliente final ```text O envio de mensagens do seu WhatsApp foi pausado pela Meta porque a conta não tem um método de pagamento válido. Entre no WhatsApp Manager da Meta, abra o Billing Hub da sua conta de WhatsApp e cadastre ou regularize o cartão ou a forma de pagamento. Avise a gente quando terminar. ``` Depois que ele regularizar, envie de novo. As mensagens recusadas durante a espera não são reenviadas sozinhas: reenvie as que ainda interessam. ## Como saber que voltou A Meta não avisa quando o pagamento é regularizado, e não existe consulta. O único sinal é um envio que volta a ser aceito. Quando isso acontece, `awaitingPaymentSince` volta a `null` e a Luna publica `number.payment_resolved`, uma vez. O evento de volta ao normal ```json { "version": "2026-11-10", "event_id": "6a956161dd17bb975533e63286e811ae62b77b3350107945952b2e53f0a9d1e2", "event_type": "number.payment_resolved", "occurred_at": "2026-10-13T15:30:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841" } } ``` > **Não conte como resolvido antes de um envio passar.** Enquanto `awaitingPaymentSince` tiver data, o número segue em espera, mesmo que o seu cliente diga que já cadastrou. Para testar, envie uma mensagem: se a Meta aceitar, o evento sai. Se recusar de novo, o número continua em espera e nada novo é publicado. ## O que a Luna não faz - Não cobra esse pagamento, não o adianta e não o intermedeia. A Luna é Tech Provider e não tem linha de crédito: essa linha é requisito de Solution Partner da Meta, e não é o caso. - Não consulta o estado do pagamento: a Meta não oferece essa consulta. - Não marca o número como resolvido por conta própria. A marca só sai quando um envio é aceito. - Não reenvia as mensagens recusadas. - Não tem rota de crédito, recarga nem pagamento. O que a Meta cobra está em [Custos da Meta](https://lunahia.com.br/docs/custos-da-meta). Os campos e os eventos citados estão na [referência da API](https://lunahia.com.br/docs/referencia). --- # Custos da Meta Fonte: https://lunahia.com.br/docs/custos-da-meta A Luna cobra só a capacidade de números do plano. O uso do WhatsApp é cobrado pela Meta, direto do negócio dono do número. Este guia resume as regras de cobrança da Meta em vigor e o que elas mudam para quem integra. ## Quem cobra o quê A Luna cobra apenas pela capacidade de números conectados do plano. Nunca cobra por mensagem enviada ou recebida, e nenhum limite da API varia com o plano. Os limites técnicos que a API aplica (requisições por minuto, endpoints de webhook, validade do link de conexão, tamanho de arquivo, envios por segundo) vêm de `GET /v1/limits`, cada um com `key`, `label`, `value`, `unit` e `reason`. São iguais para todos os clientes e existem por capacidade ou porque a Meta os impõe. Pede `numbers:read`. A Meta cobra o uso do WhatsApp diretamente do negócio que é dono do número, na forma de pagamento cadastrada na conta de WhatsApp desse negócio na Meta. Por isso cada negócio precisa de uma conta própria na Meta, com forma de pagamento própria. A Luna não intermedeia, não adianta e não repassa esse pagamento. ## O que a Meta cobra desde 1º de outubro de 2026 As regras abaixo foram lidas na página de preços da Meta em 07/10/2026. Os valores não estão aqui: variam por categoria de mensagem e pelo país do destinatário, e a Meta os atualiza no primeiro dia de cada trimestre. A [tabela de tarifas da Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing) é a referência. Quem precisa mostrar estas regras no próprio produto lê `GET /v1/meta-pricing`: a lista `rules` (cada regra com `key`, `title` e `text`), o dia em que a Luna as leu em `readAt`, e os endereços da tabela de tarifas (`sourceUrl`) e da política dos Provedores de IA (`aiProvidersUrl`). Não traz valor em moeda. Pede `numbers:read`. - **Respostas dentro da janela de 24 horas**, que a Meta chama de mensagens de serviço: cada número tem 1.000 mensagens de serviço gratuitas por mês, e o saldo não acumula para o mês seguinte. A partir da 1.001ª, a Meta cobra cada mensagem entregue. A virada do mês é à meia-noite, no fuso da conta de mensagens. - **Template de utilidade dentro de uma janela aberta** deixou de ser gratuito. A Meta passou a cobrá-lo mesmo com a janela de 24 horas aberta. - **Template de marketing** é sempre cobrado, dentro ou fora da janela. - **Conversa iniciada por anúncio de clique para o WhatsApp**: responder dentro da janela de atendimento abre um período gratuito de até 7 dias, para marketing, utilidade, autenticação e serviço. - **Autenticação e utilidade** têm faixas de volume: a tarifa da faixa seguinte é menor. A contagem é da Meta, feita sobre o portfólio empresarial inteiro, e recomeça todo mês. > **Sem forma de pagamento, as respostas param.** Se a conta de WhatsApp do negócio não tem forma de pagamento na Meta, a Meta entrega as mensagens de serviço enquanto a franquia gratuita do mês não acaba, e depois disso deixa de entregá-las. Peça ao negócio que cadastre uma forma de pagamento no Billing Hub da Meta antes que isso aconteça. Para quem integra, a consequência prática é planejar o primeiro disparo e as respostas em volume com a forma de pagamento já cadastrada. A janela de 24 horas continua sendo o que decide se uma mensagem livre pode sair: veja [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens). ## Assistentes de IA de uso geral A Meta chama de Provedores de IA os assistentes de IA de uso geral, e os trata numa política própria. A regra de mensagens de serviço acima não se aplica a eles. Leia a [política da Meta para Provedores de IA](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing/ai-providers) antes de decidir se o seu produto se enquadra. Quando a Meta classifica uma mensagem enviada nessa cobrança, o `pricing.category` dela chega como `general_purpose_ai`, em `GET /v1/messages/{id}`, em `GET /v1/messages` e no evento `message.status`, e o console mostra o rótulo "IA de uso geral". É a cobrança de Provedor de IA, que a Meta faz ao negócio dono da conta, por mensagem de serviço, e vale para o Brasil. A Luna só exibe a classificação: não soma, não converte em valor e não cobra nada sobre ela. Um agente de atendimento de um negócio, que responde sobre o próprio serviço dele, paga como mensagem de serviço comum; a categoria `general_purpose_ai` aparece quando o produto principal é um assistente de uso geral. ## Como conferir o que a Meta cobrou A Luna devolve a classificação de custo que a Meta aplicou a cada mensagem enviada, com os nomes dela, e não devolve preço. O objeto `pricing` vem em `GET /v1/messages/{id}` e no evento `message.status`, com `billable`, `pricing_model`, `type` e `category`. A Meta o informa só em `sent` e em um entre `delivered` e `read`: enquanto ela não o informa, o campo é nulo. A Meta vai descontinuar `billable`, então leia `type` e `category` juntos. Os valores são os da Meta e podem ganhar valores novos: não trate como lista fechada. O que a Luna devolve é o que ajuda a prever a categoria. A categoria do template vem no campo `category` de `GET /v1/templates`. O estado da janela de atendimento de cada contato vem em `GET /v1/conversations`, nos campos `windowOpen`, `windowExpiresAt` e `windowSource`. Os dois estão na [referência da API](https://lunahia.com.br/docs/referencia). Para ver o consumo que a Meta mede para um número no período, use `GET /v1/usage?numberId=`. A Luna lê o `pricing_analytics` da Meta com o token do negócio e repassa os pontos como ela os informa: categoria e tipo de cobrança, a faixa, o país, o volume e o custo aproximado, na moeda da conta do negócio na Meta. Cada ponto vem de um número só e traz `numberId`, `phoneNumberId` e `currency`, a moeda da conta dele; a resposta não tem total, e `notice` traz o aviso de que o valor é aproximação e de que a Meta cobra direto do negócio. Cada leitura gasta uma unidade do limite de gestão da Meta, então a leitura de cada número fica guardada por cinco minutos (`readAt` diz de quando é a leitura). Nada disso entra na assinatura da Luna. Para repassar o consumo a um cliente seu, mande `externalId` no lugar de `numberId` (exatamente um dos dois; os dois, ou nenhum, voltam `400` com `campos`): `GET /v1/usage?externalId=cliente-42&start=2026-11-01&end=2026-12-01&granularity=MONTHLY`. A Luna lê cada número daquele cliente e devolve os pontos de todos em `data`, cada um com o seu `numberId` e a sua `currency`. Um cliente com contas em moedas diferentes recebe pontos em moedas diferentes, e a Luna **nunca soma moedas**: agrupe por `numberId` e por `currency` no seu lado. `numbers` lista os números cobertos, inclusive os que não tiveram ponto nenhum e os que ficaram de fora (`read: false`, com `reason`: `number_disconnected` ou `phone_not_read_yet`). `granularity` é `DAILY` (o padrão), `MONTHLY` ou `HALF_HOUR`, e a Meta limita o período de cada uma. Com `format=csv` a resposta vem em `text/csv`, uma linha por ponto, para a planilha do seu financeiro; o aviso de aproximação vai no cabeçalho `X-Luna-Notice`. Continua só exibição: nada disso entra na assinatura da Luna. O `pricing` é para você exibir, não é a fatura. Para ver o que a Meta de fato cobrou, consulte o Billing Hub da conta de WhatsApp do negócio, e a fatura que a Meta emite para ele. É lá que o valor aparece. A Luna não calcula valor em dinheiro, não soma e não cobra sobre isso. --- # Vindo da Z-API ou da Evolution API Fonte: https://lunahia.com.br/docs/migrar-de-api-nao-oficial A Z-API e a Evolution API conectam um número como um aparelho; a Luna fala só com a WhatsApp Cloud API oficial da Meta. Este guia traduz o que você fazia lá para o que se faz aqui: como autenticar, enviar, receber, e o que cada estado e cada evento vira. Termina com a lista do que não existe na API oficial, para você não procurar o que não está aqui. A [referência da API](https://lunahia.com.br/docs/referencia) traz o contrato de cada rota. Antes das tabelas, leia [a diferença de modelo](https://lunahia.com.br/migrar-da-evolution-api): a janela de 24 horas, o `202` sem `wamid` e a ausência de QR code são o que quebra uma migração no meio. As colunas da Z-API e da Evolution descrevem, com palavras nossas, o que a documentação pública de cada uma mostra. ## O que muda antes de tocar no código - **Instância vira número.** Em vez de criar uma instância e ler um QR code, você manda ao seu cliente um link de conexão (`POST /v1/onboarding/links`) e o dono do número entra com a conta dele na Meta. O número fica na conta do seu cliente, e é isso que evita o banimento por sessão. Veja [Conectar um número](https://lunahia.com.br/docs/conectar-numero). - **Texto livre só dentro de 24 horas.** Depois que o contato para de escrever por 24 horas, o caminho é um template aprovado. A Luna recusa o texto fora da janela com `409 window_closed` antes de gastar a chamada. Veja [a janela](https://lunahia.com.br/docs/enviar-mensagens#janela). - **O envio responde `202`.** A resposta traz o `id` da Luna e `status: "queued"`. O `wamid` e o estado de entrega chegam depois, pelo evento `message.status`. Os estados estão em [Os estados da mensagem](https://lunahia.com.br/docs/enviar-mensagens#estados). - **Só celulares do Brasil.** `to` é o telefone com DDI e DDD, só dígitos, começando por `55`. Outro formato responde `400` com `campos: [{campo: "to"}]`, salvo para quem já escreveu para o seu número. O nono dígito não é problema: a Luna acha a conversa com e sem ele, e o texto vai para o `wa_id` que a Meta usou. Quem nunca escreveu recebe o telefone como você o escreveu. - **A fila tem ritmo.** Para o mesmo contato, saem 30 mensagens de uma vez e depois uma a cada 7 segundos. Você não configura isso, e o limite nunca volta como `429`. Não há como cancelar uma mensagem que já está na fila, nem estimar a hora em que ela sai. - **Template não é recusado em silêncio.** Um template que a Luna conhece e que não está `APPROVED` responde `409 template_not_approved`, e variável faltando ou sobrando responde `400` com `campos`. Um número que não consegue enviar agora (`connection.canSend: false` em `GET /v1/numbers`) ainda aceita o pedido com `202` e a falha chega em `message.status`: leia `canSend` antes de enviar. ## Autenticar e enviar | O que você fazia | Z-API | Evolution API | Luna | | --- | --- | --- | --- | | Autenticar | O identificador da instância e um token, mais um token de segurança da conta. | Uma chave da instalação. | `Authorization: Bearer hlsn_...` com escopos. Uma chave por cliente, com `externalId`. | | Criar a instância de um cliente | Criar uma instância pelo parceiro. | Criar uma instância. | Link de conexão por cliente: `POST /v1/onboarding/links`. | | Enviar texto | Uma chamada com o telefone e a mensagem; devolve dois identificadores na hora. | Uma chamada por instância com o número e o texto. | `POST /v1/messages` com `from`, `to` e `text.body`. Devolve `id` e `status: "queued"`; o `wamid` vem depois. | | Pausa entre mensagens | Um atraso por mensagem, de 1 a 15 segundos. | Um atraso por mensagem. | Fila automática: rajada de 30, depois uma a cada 7 segundos por contato. | | Mostrar “digitando” | Um atraso de digitação no envio. | Uma chamada de presença. | `POST /v1/messages/{id}/typing`, com o `id` da mensagem **recebida**. Também a marca como lida e some em cerca de 25 segundos. | | Enviar mídia | A URL ou o arquivo em base64 no próprio envio. | O arquivo no próprio envio. | `POST /v1/numbers/{id}/media` e depois `image.id`, ou `image.link` com uma URL pública. Dois passos, porque a Meta trabalha com identificador de mídia. | | Botões e lista | Botões de ação e lista de opções. | Enviar botões e enviar lista. | `interactive.type`: `button`, `list` ou `cta_url`. A resposta volta em `message.interactive.id`, no evento `message.received`. | | Reação | Enviar reação. | Enviar reação. | `type: "reaction"`, com `reaction.message_id` (o `wamid`) e `reaction.emoji`. | | Responder citando | Responder uma mensagem. | Um campo de citação no envio. | `context.message_id`, com o `id` da Luna ou o `wamid`. | | Marcar como lida | Ler mensagens. | Marcar mensagem como lida. | `POST /v1/messages/{id}/read`, por mensagem. | | Apagar a instância | Apagar a instância. | Apagar a instância. | `DELETE /v1/numbers/{id}`. Libera a vaga na Luna e não derruba o número na Meta. | O telefone vai como o cliente o escreveu, com ou sem o nono dígito. O corpo mínimo de um envio de texto: ```json { "from": "YOUR_PHONE_NUMBER_ID", "to": "5531990009991", "text": { "body": "Olá! Sua consulta está confirmada." } } ``` Campos que pertencem ao tipo vão dentro do objeto do tipo, e não no topo do corpo: `image.caption`, `location.latitude`. Um campo desconhecido responde `400` com o nome dele. Mande sempre o `Idempotency-Key`: veja [Idempotência](https://lunahia.com.br/docs/enviar-mensagens#idempotencia). ## Eventos e estados Na Luna há um endpoint de webhook para a conta inteira, ou um por cliente com `externalIds`. Todo evento traz o objeto `number`, com o `external_id` do cliente dono do número, então um endpoint só atende todos os seus clientes. A entrega é assinada e pode repetir: deduplique pelo `event_id`. Veja [Receber eventos](https://lunahia.com.br/docs/receber-eventos). ### Webhook por número (como a “instância”) Lá cada instância tinha a sua URL de webhook. Aqui o número é a instância e o endpoint aceita `phoneNumberIds`: ele recebe só os eventos desses números (o UUID da Luna, o `id` de `GET /v1/numbers`, ou o `metaPhoneNumberId`). ```bash curl -X POST "https://api.lunahia.com.br/v1/webhooks/endpoints" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks/numero-1", "phoneNumberIds": [ "YOUR_PHONE_NUMBER_ID" ] }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "url": "https://example.com/webhooks/numero-1", "phoneNumberIds": [ "YOUR_PHONE_NUMBER_ID" ] }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.post( "https://api.lunahia.com.br/v1/webhooks/endpoints", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "url": "https://example.com/webhooks/numero-1", "phoneNumberIds": [ "YOUR_PHONE_NUMBER_ID", ], }, timeout=10, ) print(res.status_code, res.json()) ``` Para trocar a URL só desse número, use `PATCH /v1/webhooks/endpoints/{id}` com o novo `url`. Para números que ainda vão ser conectados, cadastre o endpoint com `externalIds` (o `externalId` que você dá ao cliente): ele recebe de todo número com esse `externalId`, inclusive os conectados depois. Detalhes na seção “Webhook por número” de [Receber eventos](https://lunahia.com.br/docs/receber-eventos). ```bash curl -X PATCH "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks/numero-1-novo" }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID', { method: 'PATCH', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "url": "https://example.com/webhooks/numero-1-novo" }), }); console.log(res.status, await res.json()); ``` ```python import os import requests res = requests.patch( "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", }, json={ "url": "https://example.com/webhooks/numero-1-novo", }, timeout=10, ) print(res.status_code, res.json()) ``` | O que você ouvia | Z-API | Evolution API | Luna | | --- | --- | --- | --- | | Mensagem recebida | Webhook “ao receber”. | `MESSAGES_UPSERT` | `message.received` | | Mensagem que o dono mandou pelo celular | “Ao receber”, com as enviadas por mim. | `SEND_MESSAGE` | `message.echo`, só em número em coexistência. | | Estado da mensagem | Webhook de status, com os estados de envio, recebimento, leitura e reprodução. | `MESSAGES_UPDATE` | `message.status`: `sent`, `delivered`, `read`, `played` e `failed`. A Meta não manda `delivered` quando entrega e leitura coincidem. | | Conectou | Webhook “ao conectar”. | `QRCODE_UPDATED` e `CONNECTION_UPDATE`. | `onboarding.link.completed` quando o cliente termina o link, e `number.connected` quando o número fica pronto. | | Desconectou | Webhook “ao desconectar”. | `CONNECTION_UPDATE` | `number.disconnected`, `number.action_required` e `number.credential_expiring`. O estado fica em `connection` de `GET /v1/numbers/{id}`. | | Aprovação de template | - | - | `template.status` | > **`number.disconnected` não quer dizer sempre `disconnected`.** Quando o cliente remove o aplicativo, o número fica em `connection.status: "action_required"` com o motivo `credential_invalid`, e se reconecta pelo link. Só o `DELETE /v1/numbers/{id}` deixa `disconnected`. Veja [Número desconectado](https://lunahia.com.br/docs/saude-da-conta#desconectado). Não existe evento de ligação recebida, e não existe configuração de rejeitar chamada. Se o seu agente depende de uma delas, trate no seu lado. A leitura automática existe: ligue `autoRead` no número, com `PATCH /v1/numbers/{id}`, e a Luna marca como lida cada mensagem que o número recebe, sem indicador de digitando. Para marcar só as que você processa, deixe `autoRead` desligado e use `POST /v1/messages/{id}/read`. ## O que não existe na API oficial Não são faltas da Luna: são recursos de quem conecta um número como aparelho. Cada linha diz o que fazer no lugar. | O que existia lá | Aqui | | --- | --- | | QR code e código de pareamento | Não há QR code. A conexão é pelo link de conexão, e o dono do número entra com a conta dele na Meta. É isso que impede o banimento. | | Conferir se um número tem WhatsApp antes de enviar | A API oficial não responde isso. Envie normalmente: se o número não tem WhatsApp, chega `message.status` com `failed` e o código 131026, e repetir o envio não muda o resultado. | | Agenda de contatos, foto e recado de quem escreve, lista de chats | O número de negócio não tem agenda nem lista de chats. Guarde os contatos no seu banco a partir de `message.received` (`wa_id` e `profile_name`). | | Mensagens antigas do aparelho | A Luna só tem o que passou por ela depois da conexão. Em número em coexistência, a Meta importa o histórico dentro de um prazo: veja [Conectar um número](https://lunahia.com.br/docs/conectar-numero#coexistencia). | | Status e stories | A API oficial não publica nem responde status. | | Enquetes, eventos e fixar mensagem | Use botões ou lista, que o contato responde e volta em `message.received`, em `message.interactive`. | | Editar, apagar e encaminhar mensagem enviada | A API de mensagens da Meta não oferece essas operações ao negócio. Corrija mandando outra mensagem; `context.message_id` cita a original. | | Etiquetas e anotações do aplicativo Business | Etiqueta é do aplicativo no celular e não existe na API. Marque a conversa no seu sistema, pelo `conversationId` ou pelo `wa_id`. | | Presença do contato: online, “digitando”, visto por último | A Meta não entrega a presença do contato. O “digitando” do seu agente sai por `POST /v1/messages/{id}/typing`. | | Privacidade da conta e bloqueio de contato | Bloquear existe, em `POST /v1/numbers/{id}/blocked-users`. O resto das configurações de privacidade é do aplicativo. | | Listas de transmissão, canais, comunidades | A API oficial não tem. Para falar com muita gente, use template, e respeite o limite de qualidade e a preferência de marketing do contato (`contact.preferences_changed`). | | Grupos | Grupo comum de WhatsApp não existe na API oficial. A Meta tem uma API de grupos própria, com limites e requisitos, que a Luna ainda não expõe. | | Proxy por instância, IP dedicado, desbanimento | Não há sessão para proteger: o número é registrado na Meta, e o risco é de qualidade, não de IP. Veja `GET /v1/numbers/{id}/health` e [Saúde da conta](https://lunahia.com.br/docs/saude-da-conta). | | Texto livre a qualquer hora | Fora de 24 horas, só template. É a regra da Meta, e a Luna a aplica antes de gastar a chamada (`409 window_closed`). | | Áudio em MP3 como mensagem de voz | A Meta exige OGG com OPUS e a Luna não converte. Converta antes: `ffmpeg -i entrada.mp3 -c:a libopus -b:a 32k -ar 48000 -ac 1 saida.ogg`. | ## Por onde começar 1. Crie a conta e uma chave por cliente: [Conta e chaves](https://lunahia.com.br/docs/conta-e-chaves). 2. Troque a criação da instância pelo link de conexão: [SaaS com N clientes](https://lunahia.com.br/docs/saas-com-n-clientes). 3. Cadastre o webhook e troque o seu tratamento de eventos pela tabela acima: [Receber eventos](https://lunahia.com.br/docs/receber-eventos). 4. Teste o envio sem ir à Meta, com a chave de teste: [Modo de teste](https://lunahia.com.br/docs/modo-de-teste). > A Helsen cobra pela capacidade de números ativos do seu plano, e por nada além disso. O uso da plataforma WhatsApp é cobrado pela Meta, do seu cliente final, no método de pagamento dele. Z-API e Evolution API são projetos de terceiros, sem relação com a Helsen; este guia descreve o modelo de cada plataforma para quem migra e não é uma comparação comercial. --- # Vindo da Twilio Fonte: https://lunahia.com.br/docs/migrar-da-twilio A Twilio e a Luna entregam mensagem pela WhatsApp Cloud API da Meta, mas com contratos diferentes: aqui o envio é assíncrono, a janela de 24 horas é aplicada pela API, o webhook é um só e assinado de outro jeito. Este guia faz o de-para do que você usa, para trocar o código sem reaprender o produto. A [referência da API](https://lunahia.com.br/docs/referencia) traz o contrato de cada rota. A coluna da Twilio descreve, com palavras nossas, o que a documentação pública dela mostra; se algo mudou por lá, vale a documentação dela. ## O que muda antes de tocar no código - **O número é do seu cliente, na conta dele na Meta.** Não há subconta: o cliente do seu produto é o `externalId` de uma chave, de um link de conexão e de um endpoint. Veja [SaaS com N clientes](https://lunahia.com.br/docs/saas-com-n-clientes). - **O envio responde `202`.** O `id` da Luna volta na hora com `status: "queued"`, e o `wamid` e o estado de entrega chegam em `message.status`. Veja [Os estados da mensagem](https://lunahia.com.br/docs/enviar-mensagens#estados). - **Fora da janela de 24 horas a recusa é na hora.** Texto livre para quem não escreveu nas últimas 24 horas responde `409 window_closed` na própria chamada, com `fechadaEm` e `acaoRecomendada`. Você não descobre depois, por um código de erro. Template e reação passam. - **Template inválido também é recusado na hora, quando a Luna o conhece.** `409 template_not_approved` se o estado não é `APPROVED`, e `400` com `campos` se falta uma variável, sobra uma, ou o código de autenticação passa de 15 caracteres. Um template criado direto no painel da Meta não está no catálogo da Luna e passa: quem decide é a Meta. - **Só destinatários do Brasil.** `to` começa por `55`. Outro formato responde `400` com `campos: [{campo: "to"}]`, salvo para quem já escreveu para o seu número. ## De-para do que você usa | Twilio | Luna | | --- | --- | | Criar mensagem na API de mensagens | `POST /v1/messages` | | Origem no formato `whatsapp:+5531...` | `from`: o UUID do número (`GET /v1/numbers`) ou o `metaPhoneNumberId`. | | Destino no formato `whatsapp:+5511900000001` | `to: "5511900000001"`: só dígitos, sem `+` e sem prefixo. | | Corpo de texto | `text.body`, até 4096 caracteres. | | Identificador de conteúdo e variáveis numeradas `{"1":"Ana"}` | `type: "template"`, com `template.name`, `template.language.code` e `template.components[].parameters`. A variável é nomeada, com `parameter_name`. | | Construtor de conteúdo e pedido de aprovação | `POST /v1/templates`: o corpo não começa nem termina com variável, e cada variável precisa de um exemplo. A aprovação chega no evento `template.status`. Veja [Templates](https://lunahia.com.br/docs/templates). | | Retorno de chamada de estado de cada mensagem | Um endpoint (`POST /v1/webhooks/endpoints`) recebe o evento `message.status` de todas as mensagens. | | Estados `queued`, `sent`, `delivered`, `read`, `failed`, `undelivered` | `queued` (só no `202`), `accepted`, `sent`, `delivered`, `read`, `played` e `failed`. Não existe `undelivered`: a falha é `failed`. Veja [Os estados da mensagem](https://lunahia.com.br/docs/enviar-mensagens#estados). | | Código de erro da mensagem | `error_code` no evento `message.status` (o código da Meta, 131xxx) e, em `GET /v1/messages/{id}`, `erros[]` com `codigo`, `categoria`, `mensagem` e `acaoRecomendada`. | | Mensagem recebida: texto, remetente, identificador do WhatsApp, carga do botão | Evento `message.received`: `message.text`, `wa_id`, `message.button.payload` e `message.interactive`. | | Chave de idempotência do envio | Cabeçalho `Idempotency-Key`, de 1 a 255 caracteres visíveis. Mesma chave e mesmo corpo devolvem o mesmo `id`; corpo diferente responde `409 idempotency_key_reused`. Veja [Idempotência](https://lunahia.com.br/docs/enviar-mensagens#idempotencia). | | SID da conta e token, ou uma chave de API | `Authorization: Bearer hlsn_...`, com escopos (`messages:write`, `messages:read`, `templates:read`...). Veja [Conta e chaves](https://lunahia.com.br/docs/conta-e-chaves). | | Subconta por cliente | Chave com `externalId`, link de conexão e endpoint com `externalIds`. | | Listar mensagens por destinatário, data e tamanho de página | `GET /v1/messages` com `waId` (o celular do Brasil vale com e sem o nono dígito), `since`, `until` e `limit` de 1 a 100. Para a página seguinte, mande o `nextCursor` em `cursor`. Parâmetro desconhecido responde `400`. | | Ver o texto e as variáveis do que foi enviado | `content` de `GET /v1/messages`: em `template`, o `name`, o `language` e as `variables`. | | Sandbox com `join` | Uma chave com `mode: "test"`: o envio não vai à Meta e o seu webhook recebe os estados simulados. Veja [Modo de teste](https://lunahia.com.br/docs/modo-de-teste). | ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511900000001", "type": "template", "template": { "name": "lembrete_consulta", "language": { "code": "pt_BR" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "parameter_name": "nome", "text": "Ana" }, { "type": "text", "parameter_name": "medico", "text": "Dra. Lima" } ] } ] } }' ``` ```js const res = await fetch('https://api.lunahia.com.br/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID(), }, body: JSON.stringify({ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511900000001", "type": "template", "template": { "name": "lembrete_consulta", "language": { "code": "pt_BR" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "parameter_name": "nome", "text": "Ana" }, { "type": "text", "parameter_name": "medico", "text": "Dra. Lima" } ] } ] } }), }); console.log(res.status, await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api.lunahia.com.br/v1/messages", headers={ "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "from": "YOUR_PHONE_NUMBER_ID", "to": "5511900000001", "type": "template", "template": { "name": "lembrete_consulta", "language": { "code": "pt_BR", }, "components": [ { "type": "body", "parameters": [ { "type": "text", "parameter_name": "nome", "text": "Ana", }, { "type": "text", "parameter_name": "medico", "text": "Dra. Lima", }, ], }, ], }, }, timeout=10, ) print(res.status_code, res.json()) ``` ## A assinatura do webhook A Twilio assina a URL mais os parâmetros do formulário. A Luna assina o **corpo bruto**: o cabeçalho `X-Luna-Signature` traz `t=...,v1=...`, e o `v1` é o HMAC-SHA256 do texto `t` + `.` + corpo bruto, com o segredo do endpoint (`whsec_...`) como chave. Recuse uma entrega cujo `t` esteja a mais de 300 segundos do seu relógio. Durante a rotação do segredo o cabeçalho traz dois `v1`, e basta um conferir. - Não reserialize o JSON antes de conferir: use os bytes exatos que chegaram. O código de verificação, em Node e em Python, está em [Verifique a assinatura](https://lunahia.com.br/docs/receber-eventos#assinatura). - Responda `2xx` para aceitar e `401` a uma assinatura inválida. Só `2xx` conta como entregue, e a entrega pode repetir: deduplique pelo `event_id`. - O SDK em TypeScript tem `lerEvento`, que confere a assinatura e devolve o evento tipado. Veja [SDK e n8n](https://lunahia.com.br/docs/sdk-e-n8n). ## Códigos de erro Na Twilio, o código de erro vem no retorno de chamada ou na página do depurador. Na Luna há dois momentos: a recusa na hora, que é um status HTTP com um `error` estável, e a falha que a Meta informa depois, em `message.status`. | Na Twilio | Na Luna | | --- | --- | | 21211, destino inválido | `400` com `campos: [{campo: "to"}]`, na hora. | | 63016, fora da janela de resposta | `409 window_closed`, na hora e antes de ir à Meta. Envie um template. | | Conteúdo ou variáveis do template inválidos | `409 template_not_approved` ou `400` com `campos`, na hora, quando a Luna conhece o template. | | Número sem WhatsApp, pagamento, restrição da conta e os demais códigos da Meta | `message.status` com `failed` e `error_code` (131026, 131042...), e o `erros[]` completo em `GET /v1/messages/{id}`. A `acaoRecomendada` diz o que fazer. Veja [Erros](https://lunahia.com.br/docs/erros#envio). | ## O que não existe aqui | Na Twilio | Na Luna | | --- | --- | | Verificação de código por WhatsApp, SMS, voz e e-mail | A Luna entrega o template de autenticação da Meta. Gerar, guardar, expirar e conferir o código é do seu sistema, e os outros canais continuam no seu provedor. O corpo do envio está em [Template de autenticação](https://lunahia.com.br/docs/templates#autenticacao). | | Troca automática para SMS | A Luna envia só por WhatsApp. Se você precisa de SMS como reserva, escute `message.status` com `failed` e envie o SMS pelo seu provedor. | | Saber se um número tem WhatsApp antes de enviar | A API oficial não responde isso. Trate o código 131026 como “número sem WhatsApp” e pare de repetir para esse número. | | Pool de remetentes e serviço de mensagens | Cada número da Meta é independente, e `from` é um número. Escolher o remetente é decisão do seu código. | | Envio em lote, agendamento e validade do envio | Um `POST /v1/messages` por destinatário, com `Idempotency-Key`. Não há envio agendado: o seu job escolhe a hora. Os limites estão em `GET /v1/limits`. | | Apagar ou anonimizar uma mensagem | Não há rota para apagar uma mensagem. Para pedir a exclusão de dados, veja a política de privacidade. | | Lista de quem pediu para parar | A Meta avisa a preferência de marketing em `contact.preferences_changed`. Guardar a lista e respeitá-la antes de enviar é do seu sistema. | | Fluxos visuais e conversas com temporizador | A Luna entrega a mensageria; a lógica é sua. Para fluxos sem código, há o nó do n8n em [SDK e n8n](https://lunahia.com.br/docs/sdk-e-n8n). | > A Helsen cobra pela capacidade de números ativos do seu plano, e por nada além disso. O uso da plataforma WhatsApp é cobrado pela Meta, do seu cliente final, no método de pagamento dele. A Twilio é uma empresa independente, sem relação com a Helsen; este guia descreve o modelo de cada plataforma para quem migra e não é uma comparação comercial. --- # Vindo de outro parceiro oficial (360dialog, Gupshup) Fonte: https://lunahia.com.br/docs/migrar-de-outro-parceiro Se você já opera clientes por outro parceiro oficial, o modelo é familiar: o negócio é dono da conta de WhatsApp Business, o número está na Cloud API da Meta e você conecta um cliente por um fluxo da Meta. O que muda são os nomes das coisas, o webhook e a forma de pagar a Meta. Este guia faz o de-para e diz o que fazer com um número que já está no outro parceiro. A [referência da API](https://lunahia.com.br/docs/referencia) traz o contrato de cada rota. As colunas dos outros parceiros descrevem, com palavras nossas, o que a documentação pública de cada um mostra; se algo mudou por lá, vale a documentação deles. ## O que muda e o que fica igual - **Fica igual:** o seu cliente continua dono da conta de WhatsApp Business (a WABA) e da forma de pagamento dele na Meta. A Luna não é dona de nada disso. - **Muda a forma de pagar a Meta.** A Luna é Tech Provider e não tem linha de crédito com a Meta, então não existe carteira, saldo nem recarga. Cada negócio paga a Meta direto, e a Luna só **exibe** o consumo de cada número em `GET /v1/usage`. Você repassa esse valor ao seu cliente como achar melhor, fora da Luna. - **Não há objeto “cliente” nem “aplicativo”.** O seu cliente é o `externalId`, um rótulo que você põe na chave, no link de conexão, no endpoint e que volta em todo evento. A instância é o número. - **Muda o webhook.** Um endpoint para a conta inteira (ou um por cliente com `externalIds`), entrega assinada, ordem preservada dentro de cada conversa e `event_id` para deduplicar. Não há cabeçalhos próprios na chamada: a autenticação da entrega é a assinatura. Veja [Receber eventos](https://lunahia.com.br/docs/receber-eventos). ## De-para por parceiro ### Para quem vem da 360dialog | 360dialog | Luna | | --- | --- | | Cabeçalho de chave, uma chave por canal | `Authorization: Bearer hlsn_...`. Uma chave por cliente, com `externalId` e `profile: "agent"`. | | Enviar mensagem | `POST /v1/messages`: `202` assíncrono e `Idempotency-Key`. | | Cadastrar a URL do webhook por canal, com cabeçalhos | `POST /v1/webhooks/endpoints` com `url`, `eventTypes` e `externalIds`. Sem cabeçalhos próprios; a assinatura é `X-Luna-Signature`. | | Listar clientes | Não há objeto “cliente”: o `externalId` é o seu cliente. | | Listar canais | `GET /v1/numbers`, com os filtros `externalId`, `state` e `canSend`. | | Criar chave de um canal | `POST /v1/api-keys` com `externalId`. | | Endereço de integração e retorno com o cliente e os canais | `POST /v1/onboarding/links` com `redirectUrl`, que recebe `status` e `numberId` na query. O link vale 72 horas. Veja [Conectar um número](https://lunahia.com.br/docs/conectar-numero). | | Evento de canal criado | `onboarding.link.completed` | | Evento de canal em execução | `number.connected` | | Evento de qualidade do número | `number.quality_changed` | | Estado de saúde: disponível, limitado, bloqueado | `connection.status` e `connection.reasons` em `GET /v1/numbers/{id}`, e `GET /v1/numbers/{id}/health`. Veja [Saúde da conta](https://lunahia.com.br/docs/saude-da-conta). | | Listar, criar e apagar templates | `GET /v1/templates?wabaId=`, `POST /v1/templates` e `DELETE /v1/templates/{id}`. Veja [Templates](https://lunahia.com.br/docs/templates). | | Replicar um template para outro cliente | Não há. Crie o template em cada WABA com `POST /v1/templates`. `GET /v1/templates/{id}` traz o conteúdo e o `wabaId`, o que ajuda a copiar à mão. | | Saldo do cliente | `GET /v1/usage?numberId=`, só para exibir. Não há saldo nem recarga. | | Limite de canais | `GET /v1/subscription`: `capacity` e `capacityLeft`. Veja [Plano e números](https://lunahia.com.br/docs/plano-e-numeros). | | Pedido de cancelamento do canal | `DELETE /v1/numbers/{id}`, que dispara `number.disconnected`. Não desregistra o número na Meta. | ### Para quem vem da Gupshup | Gupshup | Luna | | --- | --- | | Criar um aplicativo por cliente | Não há aplicativo: a instância é o número. Crie um link de conexão com `POST /v1/onboarding/links`. | | Link de incorporação assinado | O link de conexão: uma `url` com token, válida por 72 horas. | | Assinaturas de callback por aplicativo | `POST /v1/webhooks/endpoints`. | | Templates por aplicativo | `/v1/templates`, por WABA. | | Carteira e saldo | Não existe, por desenho: cada negócio paga a Meta direto. `GET /v1/usage` só exibe o consumo. | | Uso diário por aplicativo | `GET /v1/usage`, por número. | | Perfil comercial e nome de exibição | `GET` e `PATCH /v1/numbers/{id}/profile`, sem o nome de exibição. Esse nome o negócio vê e pede no WhatsApp Manager, da Meta. Veja [Perfil do negócio](https://lunahia.com.br/docs/numero-na-meta#perfil). | ## O que muda no webhook - **Assinatura.** Cada entrega traz `X-Luna-Signature: t=...,v1=...`, o HMAC-SHA256 de `t` + `.` + corpo bruto. Veja [Verifique a assinatura](https://lunahia.com.br/docs/receber-eventos#assinatura). - **Ordem e repetição.** A ordem vale dentro de uma conversa, e a entrega pode repetir. Deduplique pelo `event_id`, que é estável. - **Qual conta e qual cliente.** Os eventos de conexão e de template trazem o `waba_id`, e todo evento traz o objeto `number` com o `external_id` do seu cliente. Você não precisa cruzar listas para saber de quem é o evento. - **Link abandonado.** Um cliente que fecha a janela da Meta deixa o link `open`, com `lastFailure` e `reason: "abandoned"`. O evento `onboarding.link.failed` chega depois. ## Mover um número que já está no outro parceiro 1. O negócio precisa ser dono da conta de WhatsApp Business e ter o número liberado no parceiro anterior. Os pré-requisitos e o PIN da verificação em duas etapas estão em [Número que vem de outro provedor](https://lunahia.com.br/docs/conectar-numero#outro-provedor). 2. Mande o link de conexão (`POST /v1/onboarding/links`). Se o número ficar em `PIN_REQUIRED`, informe o PIN em `POST /v1/numbers/{id}/pin`. O PIN errado gasta uma das tentativas de registro que a Meta concede. 3. Espere o evento `number.connected` e confira `connection.canSend` em `GET /v1/numbers/{id}`. Só então desligue o número no parceiro anterior, para não ficar sem canal no intervalo. 4. Troque o webhook do seu sistema: os eventos e a assinatura são outros, como na tabela acima. > **O que não foi confirmado na prática:** os templates pertencem à WABA e não ao parceiro, mas a Helsen ainda não testou conectar uma WABA que já tem templates aprovados. Depois de conectar, liste `GET /v1/templates?wabaId=` e confira o que a Luna conhece. Um template que ela não conhece é aceito no envio e quem decide é a Meta. ## Capacidade e links O plano da Luna define quantos números você mantém ativos. O link de conexão **não reserva vaga**: se você mandar mais links do que há vagas, os últimos clientes ficam com o número em "conectando" até haver vaga. Antes de entregar cada link, confira as vagas, como explica [Plano e números](https://lunahia.com.br/docs/plano-e-numeros). > A Helsen cobra pela capacidade de números ativos do seu plano, e por nada além disso. O uso da plataforma WhatsApp é cobrado pela Meta, do seu cliente final, no método de pagamento dele. 360dialog e Gupshup são empresas independentes, sem relação com a Helsen; este guia descreve o modelo de cada plataforma para quem migra e não é uma comparação comercial. --- # Glossário Fonte: https://lunahia.com.br/docs/glossario Os termos que a documentação usa sem parar, explicados em um parágrafo cada, com o guia onde o assunto é tratado por inteiro. O contrato de cada rota está na [referência da API](https://lunahia.com.br/docs/referencia). ## Janela de 24 horas O período em que você pode mandar mensagem livre (texto, imagem, botões) a um contato: 24 horas depois da **última mensagem que ele mandou** para o seu número. Quem abre a janela é o contato, quando escreve; enviar um template não a abre. Com a janela fechada, só sai [template](#template), e o envio de texto livre responde `409` com `error: "window_closed"`. Mais em [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens#janela). ## Template Um modelo de mensagem que a Meta aprova antes do uso. É o único jeito de começar uma conversa, ou de falar com alguém fora da [janela de 24 horas](#janela). O estado dele (`PENDING`, `APPROVED`, `REJECTED`...) vem da Meta, e só `APPROVED` envia. Mais em [Templates](https://lunahia.com.br/docs/templates). ## Idempotência A propriedade de uma chamada que, repetida, produz o mesmo resultado de uma vez só. Na Luna, você manda o cabeçalho `Idempotency-Key` com um valor seu em `POST /v1/messages`: se a chamada se repetir (por um tempo esgotado, por exemplo), a Luna devolve a mensagem original em vez de enviar uma segunda. Mais em [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens#idempotencia) e, para agentes, em [Agente de IA](https://lunahia.com.br/docs/agente-de-ia#idempotencia). ## BSUID O identificador de usuário que a Meta dá a cada pessoa, e que não depende do telefone. Algumas pessoas escrevem sem mostrar o telefone, e nesse caso o evento chega com `wa_id` nulo e com o BSUID em `user_id`. Para responder, use `recipient` com esse valor, no lugar de `to`. Mais em [Usuários sem telefone](https://lunahia.com.br/docs/usuarios-sem-telefone). ## Webhook Um endereço HTTPS seu que a Luna chama (um `POST`) toda vez que algo acontece: uma mensagem chegou, uma mensagem mudou de estado, um número conectou. É assim que o seu sistema fica sabendo sem precisar perguntar toda hora. Mais em [Receber eventos](https://lunahia.com.br/docs/receber-eventos). ## Assinatura O carimbo que a Luna põe em cada entrega de webhook, no cabeçalho `X-Luna-Signature`, e que prova que o evento veio dela e não foi alterado. Você refaz a conta com o seu segredo e confere. Mais em [Receber eventos](https://lunahia.com.br/docs/receber-eventos#assinatura). ## wamid O identificador de uma mensagem **na Meta**. Ele chega depois do envio, pelo webhook. O `id` que o `202` devolve é outro: é o da mensagem na Luna, e é ele que as rotas da Luna pedem. Mais em [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens#basico). ## externalId O rótulo que você dá a um cliente seu (de 1 a 128 caracteres, texto livre). Ele nasce no link de conexão, vai para o número e volta nos eventos desse número, para o seu sistema saber de qual cliente é cada um. A Luna nunca o interpreta. Mais em [SaaS com N clientes](https://lunahia.com.br/docs/saas-com-n-clientes). ## event_id O identificador de um evento de webhook. É estável: a mesma entrega, repetida, traz o mesmo `event_id`, e é com ele que o seu código descarta o que já tratou. Como a entrega é pelo menos uma vez, a repetição acontece. Mais em [Receber eventos](https://lunahia.com.br/docs/receber-eventos#garantias). ## Corpo bruto Os bytes exatos que o seu servidor recebeu no `POST`, antes de qualquer leitura do JSON. A assinatura é calculada sobre eles: se você abre o JSON e o monta de novo, a ordem das chaves ou os espaços podem mudar e a conferência falha. Pegue o corpo bruto da sua biblioteca antes de interpretá-lo. Mais em [Receber eventos](https://lunahia.com.br/docs/receber-eventos#assinatura). --- # Referência da API Fonte: https://lunahia.com.br/docs/referencia ## Mensagens Enviar mensagens e consultar o que entrou e saiu. O envio é assíncrono: a resposta é 202 e a entrega acontece no ritmo que a Meta permite. ### Listar mensagens `GET /v1/messages` O registro do que entrou e saiu, do mais recente para o mais antigo. Cada mensagem traz o número, o rótulo do cliente, a conversa e, quando falhou, o resumo do erro. Filtros: phoneNumberId, externalId, conversationId, waId, userId, wamid, direction, status, since e until. Parâmetro que a rota não conhece volta 400. format=csv devolve text/csv, com os mesmos filtros. Autenticação: Chave de API. Escopo exigido: `messages:read` Guia do tema: https://lunahia.com.br/docs/enviar-mensagens#rota-get-v1-messages #### Parâmetros de consulta | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `limit` | `integer` | não | Quantas mensagens trazer. Padrão 50, máximo 100. Com format=csv o padrão e o máximo são 1000. Mais que 100 sem format=csv responde 400. | | `format` | `string` | não | json (o padrão) ou csv. O csv vem em text/csv, uma linha por mensagem, com os mesmos filtros e a mesma ordem; a próxima página vem no cabeçalho X-Luna-Next-Cursor (ausente na última) e vai em cursor. Colunas: id, direction, wamid, type, bodyText, status, waId, userId, displayNumber, numberId, externalId, conversationId, errorCode, errorMessage, createdAt. | | `phoneNumberId` | `string` | não | O número: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Os dois valem. | | `externalId` | `string` | não | O rótulo que você deu ao seu cliente (externalId): só as mensagens dos números dele. Igualdade exata; um rótulo sem número devolve lista vazia. | | `conversationId` | `string` | não | | | `waId` | `string` | não | O telefone do interlocutor (waId), só com dígitos: só as mensagens da conversa dele. Igualdade exata, e o celular do Brasil vale com e sem o nono dígito; um waId sem conversa devolve lista vazia. | | `userId` | `string` | não | O BSUID do interlocutor (userId), o identificador do usuário que não depende do telefone: só as mensagens da conversa dele. Igualdade exata; um userId sem conversa devolve lista vazia. | | `direction` | `string` | não | inbound: só o que chegou. outbound: só o que você enviou. | | `status` | `string` | não | O status da mensagem, como a Meta o informa e como o campo status o devolve (por exemplo sent, delivered, read, failed). Igualdade exata, e um valor que nenhuma mensagem tem devolve lista vazia. Vale só para mensagem enviada, que é a que tem status. | | `since` | `any` | não | Só as mensagens criadas neste instante ou depois (ISO 8601: 2026-11-03T00:00:00.000Z, 2026-11-03T00:00:00-03:00, ou a data 2026-11-03, que vale meia-noite UTC). | | `until` | `any` | não | Só as mensagens criadas antes deste instante (ISO 8601, nas mesmas formas de since). Junto de since, forma a janela [since, until). | | `wamid` | `string` | não | O identificador da mensagem na Meta, o mesmo que os eventos de webhook trazem em wamid. Devolve só a mensagem com esse wamid, e a lista vem vazia quando ele não é seu ou não existe. | | `cursor` | `string` | não | | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "data": [ { "id": "ae60f288-7565-4315-a440-3663e9c231e1", "direction": "outbound", "wamid": "wamid.HBgMNTUzMTgwMzYwMjEwFQIAERgSQjczNEE1OEVDMDgyMTJCMjA2AA==", "type": "text", "bodyText": "Olá! Recebemos seu pedido e já estamos preparando.", "content": null, "callbackData": "atendimento-8841", "status": "read", "pricing": { "billable": true, "pricing_model": "PMP", "type": "regular", "category": "utility" }, "waId": "5511900000000", "userId": "BR.13491208655302741918", "parentUserId": null, "username": null, "displayNumber": "+55 11 90000-0000", "numberId": "a3c1f5b2-7d4e-4b8a-9c21-5e6f7a8b9c0d", "externalId": "cliente-8841", "conversationId": "2d9f6a41-0c5b-4e7a-8f13-9b6c4d2e1a07", "errorSummary": null, "createdAt": "2026-08-07T12:24:02.085Z" }, { "id": "b6d84033-a8e8-4db9-aab6-565ce203cc51", "direction": "inbound", "wamid": "wamid.HBgMNTUzMTgwMzYwMjEwFQIAEhgUM0FCMEFBNDUzNzg4NzY5MUQ5MTUA", "type": "text", "bodyText": "oi", "content": null, "callbackData": null, "status": null, "pricing": null, "waId": "5511900000000", "userId": "BR.13491208655302741918", "parentUserId": null, "username": null, "displayNumber": "+55 11 90000-0000", "numberId": "a3c1f5b2-7d4e-4b8a-9c21-5e6f7a8b9c0d", "externalId": "cliente-8841", "conversationId": "2d9f6a41-0c5b-4e7a-8f13-9b6c4d2e1a07", "errorSummary": null, "createdAt": "2026-08-07T11:35:10.000Z" } ], "nextCursor": null } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Enviar mensagem `POST /v1/messages` Aceita a mensagem, devolve 202 com o identificador, e entrega à Meta de forma assíncrona. Com uma chave de teste, a mensagem NÃO vai à Meta: a Luna devolve o 202 e entrega ao seu webhook os estados simulados sent, delivered e read, com test: true. O cabeçalho opcional Idempotency-Key (de 1 a 255 caracteres visíveis, sem espaço) faz repetir o pedido devolver a mensagem original; vazio ou fora do formato volta 400. Autenticação: Chave de API. Escopo exigido: `messages:write` Guia do tema: https://lunahia.com.br/docs/enviar-mensagens#rota-post-v1-messages #### Corpo da requisição `application/json` Forma 1: `type = "text"` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `from` | `string` | sim | O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `to` | `string` | não | O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400. · /^[1-9]\d{7,14}$/ | | `recipient` | `string` | não | O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to. | | `context` | `object` | não | Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar. | | `context.message_id` | `string` | sim | A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar. · 1 a 256 caracteres | | `callbackData` | `string` | não | Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos. · 1 a 512 caracteres | | `typingMs` | `integer` | não | Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida. · mínimo 1 · máximo 25000 | | `type` | `string` | não | Sempre text. Pode ser omitido: um corpo sem type é interpretado como texto, para não quebrar quem integrou antes dos demais tipos existirem. · padrão: "text" · Valores: text | | `text` | `object` | sim | | | `text.body` | `string` | sim | O texto da mensagem. Limite de 4096 caracteres, o mesmo da Cloud API. · 1 a 4096 caracteres | | `text.preview_url` | `boolean` | não | Se a Meta deve buscar a primeira URL do texto para montar uma prévia. Desligado por padrão: ligado, ele dispara uma requisição de saída a partir de conteúdo que o negócio final escreveu, com latência e comportamento que não são da plataforma. | Forma 2: `type = "image"` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `from` | `string` | sim | O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `to` | `string` | não | O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400. · /^[1-9]\d{7,14}$/ | | `recipient` | `string` | não | O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to. | | `context` | `object` | não | Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar. | | `context.message_id` | `string` | sim | A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar. · 1 a 256 caracteres | | `callbackData` | `string` | não | Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos. · 1 a 512 caracteres | | `typingMs` | `integer` | não | Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida. · mínimo 1 · máximo 25000 | | `type` | `string` | sim | Sempre image. · Valores: image | | `image` | `object` | sim | | | `image.id` | `string` | não | O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias. · 1 a 128 caracteres | | `image.link` | `string (uri)` | não | A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação. · até 2048 caracteres | | `image.caption` | `string` | não | A legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API. · até 1024 caracteres | Forma 3: `type = "video"` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `from` | `string` | sim | O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `to` | `string` | não | O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400. · /^[1-9]\d{7,14}$/ | | `recipient` | `string` | não | O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to. | | `context` | `object` | não | Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar. | | `context.message_id` | `string` | sim | A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar. · 1 a 256 caracteres | | `callbackData` | `string` | não | Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos. · 1 a 512 caracteres | | `typingMs` | `integer` | não | Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida. · mínimo 1 · máximo 25000 | | `type` | `string` | sim | Sempre video. · Valores: video | | `video` | `object` | sim | | | `video.id` | `string` | não | O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias. · 1 a 128 caracteres | | `video.link` | `string (uri)` | não | A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação. · até 2048 caracteres | | `video.caption` | `string` | não | A legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API. · até 1024 caracteres | Forma 4: `type = "audio"` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `from` | `string` | sim | O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `to` | `string` | não | O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400. · /^[1-9]\d{7,14}$/ | | `recipient` | `string` | não | O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to. | | `context` | `object` | não | Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar. | | `context.message_id` | `string` | sim | A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar. · 1 a 256 caracteres | | `callbackData` | `string` | não | Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos. · 1 a 512 caracteres | | `typingMs` | `integer` | não | Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida. · mínimo 1 · máximo 25000 | | `type` | `string` | sim | Sempre audio. · Valores: audio | | `audio` | `object` | sim | | | `audio.id` | `string` | não | O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias. · 1 a 128 caracteres | | `audio.link` | `string (uri)` | não | A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação. · até 2048 caracteres | | `audio.voice` | `boolean` | não | true para enviar como mensagem de voz (a bolinha de áudio do WhatsApp, com a forma de onda), e não como arquivo de áudio. A Meta exige um arquivo .ogg com codec OPUS, e a Luna não converte áudio: com link, um arquivo de outro tipo reconhecido (por exemplo .mp3) é recusado com 400. Com id, a Luna não vê o tipo do arquivo, e a conferência é da Meta. | Forma 5: `type = "document"` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `from` | `string` | sim | O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `to` | `string` | não | O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400. · /^[1-9]\d{7,14}$/ | | `recipient` | `string` | não | O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to. | | `context` | `object` | não | Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar. | | `context.message_id` | `string` | sim | A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar. · 1 a 256 caracteres | | `callbackData` | `string` | não | Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos. · 1 a 512 caracteres | | `typingMs` | `integer` | não | Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida. · mínimo 1 · máximo 25000 | | `type` | `string` | sim | Sempre document. · Valores: document | | `document` | `object` | sim | | | `document.id` | `string` | não | O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias. · 1 a 128 caracteres | | `document.link` | `string (uri)` | não | A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação. · até 2048 caracteres | | `document.caption` | `string` | não | A legenda que acompanha o arquivo. Limite de 1024 caracteres, o mesmo da Cloud API. · até 1024 caracteres | | `document.filename` | `string` | não | O nome com que o arquivo aparece para quem recebe. Sem ele, quem recebe vê o nome que a Meta derivar da origem. · 1 a 240 caracteres | Forma 6: `type = "sticker"` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `from` | `string` | sim | O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `to` | `string` | não | O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400. · /^[1-9]\d{7,14}$/ | | `recipient` | `string` | não | O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to. | | `context` | `object` | não | Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar. | | `context.message_id` | `string` | sim | A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar. · 1 a 256 caracteres | | `callbackData` | `string` | não | Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos. · 1 a 512 caracteres | | `typingMs` | `integer` | não | Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida. · mínimo 1 · máximo 25000 | | `type` | `string` | sim | Sempre sticker. · Valores: sticker | | `sticker` | `object` | sim | | | `sticker.id` | `string` | não | O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias. · 1 a 128 caracteres | | `sticker.link` | `string (uri)` | não | A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação. · até 2048 caracteres | Forma 7: `type = "location"` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `from` | `string` | sim | O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `to` | `string` | não | O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400. · /^[1-9]\d{7,14}$/ | | `recipient` | `string` | não | O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to. | | `context` | `object` | não | Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar. | | `context.message_id` | `string` | sim | A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar. · 1 a 256 caracteres | | `callbackData` | `string` | não | Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos. · 1 a 512 caracteres | | `typingMs` | `integer` | não | Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida. · mínimo 1 · máximo 25000 | | `type` | `string` | sim | Sempre location. · Valores: location | | `location` | `object` | sim | | | `location.latitude` | `number` | sim | A latitude em graus decimais, entre -90 e 90. · mínimo -90 · máximo 90 | | `location.longitude` | `number` | sim | A longitude em graus decimais, entre -180 e 180. · mínimo -180 · máximo 180 | | `location.name` | `string` | não | O nome do lugar, exibido acima do endereço. · até 1000 caracteres | | `location.address` | `string` | não | O endereço do lugar, exibido abaixo do nome. · até 1000 caracteres | Forma 8: `type = "contacts"` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `from` | `string` | sim | O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `to` | `string` | não | O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400. · /^[1-9]\d{7,14}$/ | | `recipient` | `string` | não | O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to. | | `context` | `object` | não | Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar. | | `context.message_id` | `string` | sim | A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar. · 1 a 256 caracteres | | `callbackData` | `string` | não | Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos. · 1 a 512 caracteres | | `typingMs` | `integer` | não | Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida. · mínimo 1 · máximo 25000 | | `type` | `string` | sim | Sempre contacts. · Valores: contacts | | `contacts` | `array` | sim | Os cartões de contato a enviar. Ao menos um, no máximo vinte. · 1 a 20 itens | | `contacts[].name` | `object` | sim | | | `contacts[].name.formatted_name` | `string` | sim | O nome como ele aparece no cartão. · 1 a 512 caracteres | | `contacts[].name.first_name` | `string` | não | O primeiro nome. · até 256 caracteres | | `contacts[].name.last_name` | `string` | não | O sobrenome. · até 256 caracteres | | `contacts[].name.middle_name` | `string` | não | O nome do meio. · até 256 caracteres | | `contacts[].name.prefix` | `string` | não | O prefixo, como Dr. ou Sra. · até 64 caracteres | | `contacts[].name.suffix` | `string` | não | O sufixo, como Jr. ou Neto. · até 64 caracteres | | `contacts[].birthday` | `string` | não | A data de nascimento em AAAA-MM-DD. · /^\d{4}-\d{2}-\d{2}$/ | | `contacts[].org` | `object` | não | Os dados profissionais do contato. | | `contacts[].org.company` | `string` | não | A empresa. · até 256 caracteres | | `contacts[].org.department` | `string` | não | O departamento. · até 256 caracteres | | `contacts[].org.title` | `string` | não | O cargo. · até 256 caracteres | | `contacts[].phones` | `array` | não | Os telefones do contato. · até 20 itens | | `contacts[].phones[].phone` | `string` | não | O telefone, como ele deve aparecer. · até 64 caracteres | | `contacts[].phones[].type` | `string` | não | O rótulo do telefone, como CELL ou WORK. · até 64 caracteres | | `contacts[].phones[].wa_id` | `string` | não | O identificador do contato no WhatsApp, se conhecido. · até 64 caracteres | | `contacts[].emails` | `array` | não | Os e-mails do contato. · até 20 itens | | `contacts[].emails[].email` | `string` | não | O endereço de e-mail. · até 320 caracteres | | `contacts[].emails[].type` | `string` | não | O rótulo do e-mail, como HOME ou WORK. · até 64 caracteres | | `contacts[].addresses` | `array` | não | Os endereços do contato. · até 20 itens | | `contacts[].addresses[].street` | `string` | não | O logradouro e o número. · até 512 caracteres | | `contacts[].addresses[].city` | `string` | não | A cidade. · até 256 caracteres | | `contacts[].addresses[].state` | `string` | não | O estado. · até 256 caracteres | | `contacts[].addresses[].zip` | `string` | não | O CEP. · até 64 caracteres | | `contacts[].addresses[].country` | `string` | não | O país. · até 256 caracteres | | `contacts[].addresses[].country_code` | `string` | não | O código do país em duas letras. · até 8 caracteres | | `contacts[].addresses[].type` | `string` | não | O rótulo do endereço, como HOME ou WORK. · até 64 caracteres | | `contacts[].urls` | `array` | não | As páginas do contato. · até 20 itens | | `contacts[].urls[].url` | `string` | não | O endereço na web. · até 2048 caracteres | | `contacts[].urls[].type` | `string` | não | O rótulo da URL, como HOME ou WORK. · até 64 caracteres | Forma 9: `type = "reaction"` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `from` | `string` | sim | O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `to` | `string` | não | O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400. · /^[1-9]\d{7,14}$/ | | `recipient` | `string` | não | O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to. | | `context` | `object` | não | Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar. | | `context.message_id` | `string` | sim | A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar. · 1 a 256 caracteres | | `callbackData` | `string` | não | Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos. · 1 a 512 caracteres | | `typingMs` | `integer` | não | Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida. · mínimo 1 · máximo 25000 | | `type` | `string` | sim | Sempre reaction. · Valores: reaction | | `reaction` | `object` | sim | | | `reaction.message_id` | `string` | sim | A mensagem que recebe a reação: o wamid que a Meta atribuiu ou o id da Luna (UUID), que a Luna troca pelo wamid. O content da mensagem enviada mostra o wamid. · 1 a 256 caracteres | | `reaction.emoji` | `string` | sim | O emoji da reação. Mande vazio para remover uma reação que já tinha sido posta. · até 16 caracteres | Forma 10: `type = "interactive"` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `from` | `string` | sim | O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `to` | `string` | não | O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400. · /^[1-9]\d{7,14}$/ | | `recipient` | `string` | não | O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to. | | `context` | `object` | não | Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar. | | `context.message_id` | `string` | sim | A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar. · 1 a 256 caracteres | | `callbackData` | `string` | não | Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos. · 1 a 512 caracteres | | `typingMs` | `integer` | não | Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida. · mínimo 1 · máximo 25000 | | `type` | `string` | sim | Sempre interactive. · Valores: interactive | | `interactive` | `object` | sim | A mensagem interativa: botões de resposta (button), lista de opções (list), botão com URL (cta_url), pedido de localização (location_request_message), pedido de endereço (address_message), carrossel de mídia (carousel), Flow (flow), um produto do catálogo (product) ou uma lista de produtos do catálogo (product_list). | | `interactive.type` | `string` | não | Sempre button. · Valores: button | | `interactive.header` | `object` | não | O cabeçalho, exibido acima do corpo. | | `interactive.header.type` | `string` | sim | O que o cabeçalho carrega. · Valores: text, image, video, document | | `interactive.header.text` | `string` | não | O texto do cabeçalho, quando type é text. · até 60 caracteres | | `interactive.header.image` | `object` | não | A imagem do cabeçalho, quando type é image. | | `interactive.header.image.id` | `string` | não | O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias. · 1 a 128 caracteres | | `interactive.header.image.link` | `string (uri)` | não | A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação. · até 2048 caracteres | | `interactive.header.video` | `object` | não | O vídeo do cabeçalho, quando type é video. | | `interactive.header.video.id` | `string` | não | O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias. · 1 a 128 caracteres | | `interactive.header.video.link` | `string (uri)` | não | A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação. · até 2048 caracteres | | `interactive.header.document` | `object` | não | O documento do cabeçalho, quando type é document. | | `interactive.header.document.id` | `string` | não | O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias. · 1 a 128 caracteres | | `interactive.header.document.link` | `string (uri)` | não | A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação. · até 2048 caracteres | | `interactive.header.document.filename` | `string` | não | até 240 caracteres | | `interactive.body` | `object` | não | O corpo da mensagem interativa. | | `interactive.body.text` | `string` | sim | O texto do corpo. · 1 a 1024 caracteres | | `interactive.footer` | `object` | não | O rodapé, exibido abaixo dos botões. | | `interactive.footer.text` | `string` | sim | O texto do rodapé. · até 60 caracteres | | `interactive.action` | `object` | não | | | `interactive.action.buttons` | `array` | sim | Os botões de resposta. De um a três, o teto da Cloud API. · 1 a 3 itens | | `interactive.action.buttons[].type` | `string` | sim | Sempre reply. · Valores: reply | | `interactive.action.buttons[].reply` | `object` | sim | | | `interactive.action.buttons[].reply.id` | `string` | sim | O identificador que volta no webhook quando o botão é tocado. · 1 a 256 caracteres | | `interactive.action.buttons[].reply.title` | `string` | sim | O rótulo do botão. Limite de 20 caracteres. · 1 a 20 caracteres | | `interactive.action.button` | `string` | sim | O rótulo do botão que abre a lista. Limite de 20 caracteres. · 1 a 20 caracteres | | `interactive.action.sections` | `array` | sim | As seções da lista. De uma a dez, o teto da Cloud API. · 1 a 10 itens | | `interactive.action.sections[].title` | `string` | não | O título da seção. · até 24 caracteres | | `interactive.action.sections[].rows` | `array` | sim | As linhas da seção. De uma a dez. · 1 a 10 itens | | `interactive.action.sections[].rows[].id` | `string` | sim | O identificador que volta no webhook quando a linha é escolhida. · 1 a 200 caracteres | | `interactive.action.sections[].rows[].title` | `string` | sim | O título da linha. · 1 a 24 caracteres | | `interactive.action.sections[].rows[].description` | `string` | não | A descrição da linha. · até 72 caracteres | | `interactive.action.name` | `string` | não | Sempre cta_url. · padrão: "cta_url" · Valores: cta_url | | `interactive.action.parameters` | `object` | sim | | | `interactive.action.parameters.display_text` | `string` | sim | O rótulo do botão. Limite de 20 caracteres. · 1 a 20 caracteres | | `interactive.action.parameters.url` | `string (uri)` | sim | O endereço que o botão abre. · até 2048 caracteres | | `interactive.action.parameters.country` | `string` | não | O país do endereço, em duas letras (ISO 3166). O padrão é BR. · /^[A-Za-z]{2}$/ · padrão: "BR" | | `interactive.action.parameters.values` | `object` | não | Os campos do endereço já preenchidos, com os nomes que a Meta define para o país. | | `interactive.action.parameters.saved_addresses` | `array` | não | Endereços salvos que o usuário pode escolher, no máximo vinte. · até 20 itens | | `interactive.action.parameters.saved_addresses[].id` | `string` | sim | O identificador do endereço salvo. · 1 a 128 caracteres | | `interactive.action.parameters.saved_addresses[].value` | `object` | sim | Os campos do endereço salvo. | | `interactive.action.parameters.validation_errors` | `object` | não | Mensagens de erro por campo, para quando você devolve o formulário depois de uma validação. | | `interactive.action.cards` | `array` | sim | Os cartões, de dois a dez. · 2 a 10 itens | | `interactive.action.cards[].card_index` | `integer` | sim | A posição do cartão, de 0 a 9. Não repita. · mínimo 0 · máximo 9 | | `interactive.action.cards[].type` | `string` | não | Sempre cta_url. · padrão: "cta_url" · Valores: cta_url | | `interactive.action.cards[].header` | `object` | sim | A mídia do cartão. | | `interactive.action.cards[].header.type` | `string` | sim | O que o cartão mostra. · Valores: image, video | | `interactive.action.cards[].header.image` | `object` | não | A imagem do cartão, quando type é image. | | `interactive.action.cards[].header.image.id` | `string` | não | O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias. · 1 a 128 caracteres | | `interactive.action.cards[].header.image.link` | `string (uri)` | não | A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação. · até 2048 caracteres | | `interactive.action.cards[].header.video` | `object` | não | O vídeo do cartão, quando type é video. | | `interactive.action.cards[].header.video.id` | `string` | não | O identificador de um arquivo já enviado à Meta. Use este OU link, nunca os dois. A Meta retém o arquivo enviado por 30 dias. · 1 a 128 caracteres | | `interactive.action.cards[].header.video.link` | `string (uri)` | não | A URL pública do arquivo, que a Meta baixa no momento do envio. Use esta OU id, nunca os dois. Ela precisa responder sem autenticação. · até 2048 caracteres | | `interactive.action.cards[].body` | `object` | não | O texto do cartão. | | `interactive.action.cards[].body.text` | `string` | sim | O texto do cartão. Limite de 160 caracteres. · 1 a 160 caracteres | | `interactive.action.cards[].action` | `object` | sim | | | `interactive.action.cards[].action.name` | `string` | não | Sempre cta_url. · padrão: "cta_url" · Valores: cta_url | | `interactive.action.cards[].action.parameters` | `object` | sim | | | `interactive.action.cards[].action.parameters.display_text` | `string` | sim | O rótulo do botão. Limite de 20 caracteres. · 1 a 20 caracteres | | `interactive.action.cards[].action.parameters.url` | `string (uri)` | sim | O endereço que o botão abre. · até 2048 caracteres | | `interactive.action.parameters.flow_message_version` | `string` | não | A versão do formato da mensagem de Flow. O padrão é 3, a corrente na Meta. · 1 a 8 caracteres · padrão: "3" | | `interactive.action.parameters.flow_id` | `string` | não | O identificador do Flow. Use este OU flow_name. · 1 a 64 caracteres | | `interactive.action.parameters.flow_name` | `string` | não | O nome do Flow. Use este OU flow_id. · 1 a 200 caracteres | | `interactive.action.parameters.flow_cta` | `string` | sim | O rótulo do botão que abre o Flow. A Meta limita o tamanho (o limite exato está a confirmar na doc da Meta). · 1 a 40 caracteres | | `interactive.action.parameters.flow_token` | `string` | não | O que você quer receber de volta na resposta do Flow, para ligá-la a este envio. · até 256 caracteres | | `interactive.action.parameters.flow_action` | `string` | não | navigate (padrão da Meta) ou data_exchange. · 1 a 32 caracteres | | `interactive.action.parameters.flow_action_payload` | `object` | não | A tela e os dados de abertura, quando flow_action é navigate. | | `interactive.action.parameters.flow_action_payload.screen` | `string` | sim | A tela do Flow que abre primeiro. · 1 a 200 caracteres | | `interactive.action.parameters.flow_action_payload.data` | `object` | não | Os dados que o Flow recebe nessa tela. | | `interactive.action.parameters.mode` | `string` | não | draft para testar um Flow ainda não publicado, ou published (padrão da Meta). · 1 a 16 caracteres | | `interactive.action.catalog_id` | `string` | sim | O identificador do catálogo na conta de negócio do número (catalog_id da Meta). · 1 a 64 caracteres | | `interactive.action.product_retailer_id` | `string` | sim | O identificador do produto no catálogo, o ID de conteúdo ou SKU (product_retailer_id da Meta). · 1 a 256 caracteres | | `interactive.action.sections[].product_items` | `array` | sim | Os produtos da seção. · 1 a 30 itens | | `interactive.action.sections[].product_items[].product_retailer_id` | `string` | sim | O identificador do produto no catálogo, o ID de conteúdo ou SKU (product_retailer_id da Meta). · 1 a 256 caracteres | Forma 11: `type = "template"` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `from` | `string` | sim | O número de origem: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `to` | `string` | não | O telefone do destinatário com DDI e DDD, só dígitos, sem o sinal de mais. Nesta versão a Luna começa conversa só com telefones do Brasil (começam por 55 e têm 12 ou 13 dígitos); outro formato é recusado com 400, salvo para quem já escreveu para o seu número. Envie to OU recipient: um dos dois é obrigatório, e os dois juntos são recusados com 400. · /^[1-9]\d{7,14}$/ | | `recipient` | `string` | não | O BSUID do destinatário (por exemplo US.13491208655302741918), o identificador do usuário que não depende do telefone, como o evento recebido o traz em user_id. Use no lugar de to quando você só tem o BSUID. Templates de autenticação não vão para BSUID: eles precisam do telefone em to. | | `context` | `object` | não | Responder citando uma mensagem da mesma conversa. Não vale em template nem em reação: a Meta não aceita, e a Luna recusa com 400 antes de enfileirar. | | `context.message_id` | `string` | sim | A mensagem que esta responde, citada. Aceita o id da Luna (o UUID que POST /v1/messages devolveu ou que o evento traz em message.id) ou o wamid da Meta. A Luna resolve o id para o wamid antes de enviar. · 1 a 256 caracteres | | `callbackData` | `string` | não | Uma etiqueta sua, de 1 a 512 caracteres, que a Luna guarda com a mensagem e devolve em callback_data no evento message.status (todos os estados) e em callbackData em GET /v1/messages e GET /v1/messages/{id}. Serve para ligar a mensagem a algo seu, como o cliente ou o atendimento, sem manter uma tabela de ids. A Luna repassa o valor à Meta (biz_opaque_callback_data) e não o interpreta. Não ponha dado pessoal nela: ela viaja nos eventos. · 1 a 512 caracteres | | `typingMs` | `integer` | não | Mostra o indicador de digitando por este tempo, em milissegundos (de 1 a 25000), antes de a mensagem sair. A Luna liga o indicador na última mensagem que o contato mandou e envia depois da espera, sem segurar as outras conversas. Só vale dentro da janela de atendimento: se a conversa não tem mensagem recebida nas últimas 24 horas, a Luna ignora o campo e envia na hora. Ligar o indicador também marca essa mensagem recebida como lida. · mínimo 1 · máximo 25000 | | `type` | `string` | sim | Sempre template. · Valores: template | | `template` | `object` | sim | | | `template.name` | `string` | sim | O nome do template já aprovado pela Meta. · 1 a 512 caracteres | | `template.language` | `object` | sim | | | `template.language.code` | `string` | sim | O código do idioma do template, como pt_BR. Ele precisa bater com o aprovado. · 2 a 16 caracteres | | `template.components` | `array` | não | Os componentes que preenchem as variáveis do template. · até 32 itens | | `template.components[].type` | `string` | sim | Qual parte do template este componente preenche. · Valores: header, body, button | | `template.components[].sub_type` | `string` | não | O subtipo, exigido pela Cloud API quando type é button. · até 64 caracteres | | `template.components[].index` | `string` | não | A posição do botão, exigida pela Cloud API quando type é button. · até 8 caracteres | | `template.components[].parameters` | `array` | não | Os valores das variáveis desta parte, na forma que a Cloud API define. · até 64 itens | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "from": "1000000000000001", "to": "5511900000000", "text": { "body": "Olá! Recebemos seu pedido e já estamos preparando." } }' ``` #### Respostas **202**: Aceito: o pedido foi registrado e será processado. ```json { "id": "ae60f288-7565-4315-a440-3663e9c231e1", "status": "queued" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "window_closed", "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens", "message": "A janela de atendimento desta conversa está fechada. Só é possível enviar mensagem livre até 24 horas depois da última mensagem do contato.", "fechadaEm": "2026-10-06T12:00:00.000Z", "acaoRecomendada": "Para falar com este contato agora, envie um template aprovado. A mensagem livre volta a ser aceita quando o contato responder, porque é a resposta dele que abre a janela. Se este contato escreveu há pouco e a janela devia estar aberta, confira o campo to: use o telefone do evento recebido (wa_id).", "detalheTecnico": "A Luna já acha a conversa do celular brasileiro com e sem o nono dígito, mas qualquer outra diferença no telefone não encontra a conversa. Se o contato escreveu sem telefone (só com BSUID, o identificador de usuário), envie com recipient igual ao user_id do evento, e não com to." } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Marcar uma mensagem como lida `POST /v1/messages/{id}/read` Marca na Meta uma mensagem que você recebeu como lida, e responde 200 quando ela aceitou. Autenticação: Chave de API. Escopo exigido: `messages:write` Guia do tema: https://lunahia.com.br/docs/enviar-mensagens#rota-post-v1-messages-id-read #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador da mensagem na Luna, como GET /v1/messages o devolve. | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/messages/YOUR_ID/read" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: A Meta aceitou a marcação. ```json {} ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Mostrar o indicador de digitando `POST /v1/messages/{id}/typing` Mostra ao destinatário que você está escrevendo, e responde 200 quando a Meta aceitou. Autenticação: Chave de API. Escopo exigido: `messages:write` Guia do tema: https://lunahia.com.br/docs/enviar-mensagens#rota-post-v1-messages-id-typing #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador da mensagem na Luna, como GET /v1/messages o devolve. | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/messages/YOUR_ID/typing" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: A Meta aceitou o indicador. ```json {} ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Consultar o estado de uma mensagem `GET /v1/messages/{id}` Devolve o estado atual da mensagem, os instantes de cada etapa e o que a Meta disse quando recusou alguma coisa. Autenticação: Chave de API. Escopo exigido: `messages:read` Guia do tema: https://lunahia.com.br/docs/enviar-mensagens#rota-get-v1-messages-id #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador da mensagem na Luna, como GET /v1/messages o devolve. | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/messages/YOUR_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "id": "ae60f288-7565-4315-a440-3663e9c231e1", "wamid": null, "content": null, "status": "failed", "criadaEm": "2026-08-24T12:24:02.085Z", "enviadaEm": null, "entregueEm": null, "lidaEm": null, "callbackData": null, "pricing": null, "erros": [ { "codigo": 131026, "categoria": "nao_entregavel", "mensagem": "O destinatário não pode receber esta mensagem: o número não tem WhatsApp, ou não existe.", "acaoRecomendada": "Confira o número do destinatário e reenvie para o número correto. Repetir o envio para o mesmo número não muda o resultado.", "original": { "error": { "message": "Message undeliverable", "type": "OAuthException", "code": 131026, "fbtrace_id": "AbCdEfGhIjK" } } } ] } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Cancelar uma mensagem na fila `DELETE /v1/messages/{id}` Cancela uma mensagem que ainda está na fila de saída (accepted) e responde 204. Ela passa ao estado canceled, que é terminal, e o evento message.status com status canceled chega ao seu webhook. Se a mensagem já saiu para a Meta ou já tem desfecho, responde 409 message_not_cancelable com o estado atual. Autenticação: Chave de API. Escopo exigido: `messages:write` Guia do tema: https://lunahia.com.br/docs/enviar-mensagens#rota-delete-v1-messages-id #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador da mensagem na Luna, como POST /v1/messages o devolveu. | #### Exemplos de código ```bash curl -X DELETE "https://api.lunahia.com.br/v1/messages/YOUR_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo. **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "message_not_cancelable", "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens", "message": "Só uma mensagem que ainda está na fila de saída pode ser cancelada, e esta já saiu para a Meta ou já tem um desfecho. O estado atual vem em status; confira o resultado com GET /v1/messages/{id}.", "status": "sent" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Reenviar o webhook de uma mensagem `POST /v1/messages/{id}/replay` Pede que o evento desta mensagem seja entregue de novo ao seu endpoint: o message.received, se ela foi recebida, ou o último message.status, se ela foi enviada, no mesmo formato do original e assinado do mesmo jeito. A resposta é 202: o pedido foi registrado, e a entrega acontece de forma assíncrona. Mensagem enviada que ainda não tem estado, ou que ainda não foi aceita pela Meta, responde 400. Autenticação: Chave de API. Escopo exigido: `webhooks:write` Guia do tema: https://lunahia.com.br/docs/enviar-mensagens#rota-post-v1-messages-id-replay #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador da mensagem na Luna, como GET /v1/messages o devolve. | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/messages/YOUR_ID/replay" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **202**: O pedido de reenvio foi registrado. A entrega acontece de forma assíncrona, pelo mesmo caminho de sempre. ```json { "deliveryId": "9f2a1b0c-3d4e-4f5a-8b9c-0d1e2f3a4b5c", "requestedAt": "2026-08-26T18:30:00.000Z" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "no_webhook_endpoint", "docsUrl": "https://lunahia.com.br/docs/receber-eventos", "message": "Não há endpoint de webhook ativo para entregar este reenvio. Cadastre um em POST /v1/webhooks/endpoints, ou retome um pausado em PATCH /v1/webhooks/endpoints/{id}, e peça de novo." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Simular uma mensagem recebida `POST /v1/test-mode/inbound-messages` Entrega aos seus endpoints de webhook UMA message.received de exemplo, assinada e com test: true no envelope, para você exercitar o seu código sem esperar um contato escrever. A mensagem sai em cerca de meio segundo, e nada é gravado nem passa por número seu ou pela Meta. Funciona com a chave de teste e com a chave comum. Autenticação: Chave de API. Escopo exigido: `messages:write` #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `phoneNumberId` | `string` | não | O phone_number_id que aparece no evento. Texto livre: a Luna não procura o número. Ausente, 123456789012345. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `waId` | `string` | não | O telefone de quem "escreveu", só dígitos. Ausente, 5511900000000. · /^[1-9]\d{7,14}$/ | | `text` | `string` | não | O texto da mensagem recebida. Ausente, um texto de exemplo. · 1 a 4096 caracteres | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/test-mode/inbound-messages" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "phoneNumberId": "YOUR_PHONENUMBERID", "waId": "YOUR_WAID", "text": "YOUR_TEXT" }' ``` #### Respostas **202**: Aceito: o pedido foi registrado e será processado. ```json { "id": "3f6a1c52-9d4e-4b87-a1f0-5e2c7b9d8a14", "wamid": "wamid.TESTE_3f6a1c529d4e4b87a1f05e2c7b9d8a14", "endpoints": 1 } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ## Conversas Uma linha por interlocutor por número, com o estado da janela de atendimento de 24 horas. ### Listar conversas `GET /v1/conversations` Uma linha por interlocutor por número, da mais ativa para a mais parada. Autenticação: Chave de API. Escopo exigido: `messages:read` Guia do tema: https://lunahia.com.br/docs/enviar-mensagens#rota-get-v1-conversations #### Parâmetros de consulta | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `limit` | `integer` | não | | | `phoneNumberId` | `string` | não | O número: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Os dois valem. | | `externalId` | `string` | não | O rótulo que você deu ao seu cliente (externalId): só as conversas dos números dele. Igualdade exata; um rótulo sem número devolve lista vazia. | | `waId` | `string` | não | O identificador do interlocutor no WhatsApp (o waId da conversa, em geral o telefone só com dígitos): só as conversas dele, em cada número. Igualdade exata, mas o celular brasileiro vale nas duas grafias, com e sem o 9 depois do DDD (a Meta entrega alguns sem ele); um waId sem conversa devolve lista vazia. | | `userId` | `string` | não | O BSUID do interlocutor (userId), o identificador do usuário que não depende do telefone: só a conversa dele, em cada número. Igualdade exata; um userId sem conversa devolve lista vazia. | | `cursor` | `string` | não | | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/conversations" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "data": [ { "id": "0f2c8e6a-1d3b-4a5c-9e7f-2b4d6a8c0e12", "waId": "5511900000000", "userId": "BR.13491208655302741918", "parentUserId": null, "username": null, "phoneNumberId": "7a1c9d3e-5f2b-4c8a-9d6e-1b3f5a7c9e11", "numberId": "7a1c9d3e-5f2b-4c8a-9d6e-1b3f5a7c9e11", "externalId": "cliente-8841", "contactName": "Maria Souza", "displayNumber": "+55 11 90000-0000", "createdAt": "2026-08-07T11:35:10.000Z", "lastMessage": { "direction": "outbound", "type": "text", "bodyText": "Olá! Recebemos seu pedido e já estamos preparando.", "createdAt": "2026-08-07T12:24:02.085Z" }, "windowOpen": true, "windowExpiresAt": "2026-08-08T11:35:10.000Z", "windowSource": "usuario" } ], "nextCursor": null } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ## Mídia Enviar um arquivo para a Meta e baixar a mídia que chegou numa mensagem. ### Obter a mídia de uma mensagem `GET /v1/messages/{id}/media` Devolve uma URL assinada, emitida pela Luna, para baixar a mídia que já foi persistida. Autenticação: Chave de API. Escopo exigido: `messages:read` Guia do tema: https://lunahia.com.br/docs/enviar-mensagens#rota-get-v1-messages-id-media #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador da mensagem na Luna, como GET /v1/messages o devolve. | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/messages/YOUR_ID/media" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "url": "https://c1b129d42065073c6f8b203801c44b2d.r2.cloudflarestorage.com/lunabucket/midia/ae60f288-7565-4315-a440-3663e9c231e1?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=EXEMPLO", "expiraEm": "2026-08-24T12:29:02.085Z" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "media_not_ready", "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens", "message": "A mídia desta mensagem ainda não está disponível.", "estado": "pendente" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Baixar a mídia pelo link do aviso `GET /v1/media/{token}` O link que vem em media.url nos avisos message.received e message.echo. Não pede chave de API: o token no endereço é a credencial. Mídia pronta responde 302 para uma URL assinada de vida curta; ainda sendo baixada da Meta, 409 com Retry-After; token que não existe ou vencido, 404. Autenticação: Pública, sem chave Guia do tema: https://lunahia.com.br/docs/enviar-mensagens#rota-get-v1-media-token #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `token` | `string` | sim | O token do link, como veio em media.url. | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/media/YOUR_TOKEN" ``` #### Respostas **302**: Redirecionamento: siga o cabeçalho Location, que leva à URL assinada do arquivo. **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "media_not_ready", "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens", "message": "A mídia desta mensagem ainda não está disponível.", "estado": "pendente" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Subir um arquivo e obter o identificador de mídia `POST /v1/numbers/{id}/media` Recebe um arquivo em multipart/form-data no campo file, sobe para a Meta e devolve o identificador dele. Autenticação: Chave de API. Escopo exigido: `messages:write` Guia do tema: https://lunahia.com.br/docs/enviar-mensagens#rota-post-v1-numbers-id-media #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. | #### Corpo da requisição `multipart/form-data` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `file` | `string (binary)` | sim | O arquivo a enviar, no campo file. | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/numbers/YOUR_ID/media" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -F "file=@./pedido.jpg;type=image/jpeg" ``` #### Respostas **200**: Sucesso. ```json { "mediaId": "1425835918205946" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **413**: O arquivo passa do teto de tamanho, que é o mesmo para todos os clientes. ```json { "error": "file_too_large", "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens", "message": "O arquivo passa do tamanho que a plataforma aceita. O limite é o mesmo para todos os clientes: ele existe por capacidade de infraestrutura." } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ## Templates Mensagens pré-aprovadas pela Meta, necessárias para iniciar conversa fora da janela de 24 horas. Aprovado não é liberado para volume: a Meta aplica um ritmo próprio sobre os primeiros envios de um template novo, e não publica prazo nem mecânica. Escalone o primeiro disparo em vez de programá-lo para uma data, e acompanhe o estado do template. Acima de três botões, apenas dois aparecem na mensagem entregue. A Meta aceita o template com mais e entrega dois, então o arranjo precisa ser decidido antes de o fluxo ser desenhado. ### Listar templates `GET /v1/templates` Os templates deste cliente, do mais recente para o mais antigo. Autenticação: Chave de API. Escopo exigido: `templates:read` Guia do tema: https://lunahia.com.br/docs/templates#rota-get-v1-templates #### Parâmetros de consulta | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `status` | `string` | não | Devolve apenas os templates cujo último estado observado é exatamente este valor. A comparação é literal e sensível a maiúsculas. Valores comuns: APPROVED, PENDING, REJECTED, PAUSED, DISABLED, mas o campo é texto livre, porque a Meta acrescenta estado sem aviso e um conjunto fechado impediria você de filtrar pelo estado novo. | | `wabaId` | `string` | não | Devolve apenas os templates desta conta de negócio na Meta (WABA), o wabaId que GET /v1/business-accounts devolve. Com um cliente seu por conta, é o jeito de ver só os templates dele. Comparação exata. | | `phoneNumberId` | `string` | não | Devolve apenas os templates da conta de negócio a que este número pertence. Aceita o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Template é da conta, e não do número: todos os números da conta compartilham os mesmos templates. | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/templates" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "data": [ { "id": "ae60f288-7565-4315-a440-3663e9c231e1", "metaTemplateId": "1259544702043801", "wabaId": "102290129340398", "name": "numero_conectado", "language": "pt_BR", "category": "UTILITY", "status": "APPROVED", "createdAt": "2026-08-10T12:24:02.085Z", "updatedAt": "2026-08-10T12:31:47.004Z", "bodyText": "Olá {{primeiro_nome}}, o seu número foi conectado.", "header": null, "headerMedia": null, "footer": null, "buttons": [], "variables": [ { "name": "primeiro_nome", "example": "Maria" } ], "rejectedReason": null, "qualityScore": "GREEN", "previousCategory": null, "allowedActions": [ "edit", "delete" ] } ] } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Criar um template `POST /v1/templates` Cria o template na conta do cliente e o submete à Meta para aprovação. Autenticação: Chave de API. Escopo exigido: `templates:write` Guia do tema: https://lunahia.com.br/docs/templates#rota-post-v1-templates #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `wabaId` | `string` | sim | 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `name` | `string` | sim | /^[a-z0-9_]{1,512}$/ | | `bodyText` | `string` | sim | 1 a 1024 caracteres | | `examples` | `object` | não | Um valor de amostra por variável do corpo. Obrigatório quando o corpo tem `{{variavel}}`, porque a Meta recusa parâmetro sem exemplo. | | `header` | `string` | não | Cabeçalho de texto, exibido acima do corpo. Para cabeçalho de imagem, vídeo ou documento, use headerMedia. · 1 a 60 caracteres | | `headerMedia` | `object` | não | Cabeçalho de imagem, vídeo ou documento. O handle vem de POST /v1/template-assets, e não do identificador de mídia de mensagem. O arquivo é o exemplo que a Meta revisa, e não o conteúdo entregue: cada mensagem enviada fornece a própria mídia. | | `headerMedia.format` | `string` | sim | IMAGE, VIDEO ou DOCUMENT. Para documento a Meta aceita apenas PDF. · Valores: IMAGE, VIDEO, DOCUMENT | | `headerMedia.handle` | `string` | sim | O handle devolvido por POST /v1/template-assets. · 1 a 2048 caracteres | | `footer` | `string` | não | Rodapé, exibido abaixo do corpo. Não aceita variável. · 1 a 60 caracteres | | `buttons` | `array` | não | Até 10 botões no total, somando todos os tipos. Se houver respostas rápidas junto de outros botões, os dois conjuntos precisam ficar agrupados: respostas rápidas de um lado, o resto do outro. Acima de três botões, apenas dois aparecem na mensagem entregue: a Meta aceita o template e entrega dois. | | `buttons[].type` | `string` | não | Valores: QUICK_REPLY | | `buttons[].text` | `string` | não | 1 a 25 caracteres | | `buttons[].url` | `string` | não | 1 a 2000 caracteres | | `buttons[].example` | `array` | não | até 1 itens | | `buttons[].phone_number` | `string` | não | 1 a 20 caracteres | | `category` | `string` | não | A categoria do template. Ausente vale UTILITY, que é o comportamento de quem já integra e não manda o campo. A Meta pode reclassificar na criação: o template continua aprovado, com outra categoria, e a resposta traz a que ela atribuiu. Template de autenticação tem corpo próprio e ainda não é criado por esta rota. · Valores: MARKETING, UTILITY | | `language` | `string` | não | O código de idioma do template, na grafia da Meta: sublinhado e não hífen. pt_BR, pt_PT, en_US, es_MX, fr. A lista completa está em Supported Languages, na documentação da Meta, e o campo aceita qualquer código que ela publicar, porque um conjunto fechado aqui impediria você de usar o próximo. Ausente vale pt_BR. Atenção ao que o idioma custa: cada idioma é um template separado para a Meta, e o teto é de 250 templates por conta de WhatsApp Business. · /^[a-z]{2,3}(_[A-Z]{2})?$/ | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/templates" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "wabaId": "YOUR_WABAID", "name": "YOUR_NAME", "bodyText": "YOUR_BODYTEXT" }' ``` #### Respostas **201**: Criado. ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "metaTemplateId": "YOUR_METATEMPLATEID", "wabaId": "YOUR_WABAID", "name": "YOUR_NAME", "language": "YOUR_LANGUAGE", "category": "YOUR_CATEGORY", "status": "YOUR_STATUS", "createdAt": "YOUR_CREATEDAT", "updatedAt": "YOUR_UPDATEDAT" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Consultar um template `GET /v1/templates/{id}` O estado atual do template na Meta, o conteúdo que você escreveu e o que a Meta avisou sobre ele. Autenticação: Chave de API. Escopo exigido: `templates:read` Guia do tema: https://lunahia.com.br/docs/templates#rota-get-v1-templates-id #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/templates/YOUR_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "metaTemplateId": "YOUR_METATEMPLATEID", "wabaId": "YOUR_WABAID", "name": "YOUR_NAME", "language": "YOUR_LANGUAGE", "category": "YOUR_CATEGORY", "status": "YOUR_STATUS", "createdAt": "YOUR_CREATEDAT", "updatedAt": "YOUR_UPDATEDAT", "bodyText": "YOUR_BODYTEXT", "header": "YOUR_HEADER", "headerMedia": { "format": "YOUR_FORMAT" }, "footer": "YOUR_FOOTER", "buttons": [ { "type": "QUICK_REPLY", "text": "YOUR_TEXT" } ], "variables": [ { "name": "YOUR_NAME", "example": "YOUR_EXAMPLE" } ], "rejectedReason": "YOUR_REJECTEDREASON", "qualityScore": "YOUR_QUALITYSCORE", "previousCategory": "YOUR_PREVIOUSCATEGORY", "allowedActions": [ "edit" ] } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Editar um template `PATCH /v1/templates/{id}` Altera os componentes de um template existente. Autenticação: Chave de API. Escopo exigido: `templates:write` Guia do tema: https://lunahia.com.br/docs/templates#rota-patch-v1-templates-id #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | | #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `bodyText` | `string` | não | 1 a 1024 caracteres | | `examples` | `object` | não | | | `header` | `string` | não | Cabeçalho de texto, exibido acima do corpo. Para cabeçalho de imagem, vídeo ou documento, use headerMedia. · 1 a 60 caracteres | | `footer` | `string` | não | Rodapé, exibido abaixo do corpo. Não aceita variável. · 1 a 60 caracteres | | `buttons` | `array` | não | Até 10 botões no total, somando todos os tipos. Se houver respostas rápidas junto de outros botões, os dois conjuntos precisam ficar agrupados: respostas rápidas de um lado, o resto do outro. Acima de três botões, apenas dois aparecem na mensagem entregue: a Meta aceita o template e entrega dois. | | `buttons[].type` | `string` | não | Valores: QUICK_REPLY | | `buttons[].text` | `string` | não | 1 a 25 caracteres | | `buttons[].url` | `string` | não | 1 a 2000 caracteres | | `buttons[].example` | `array` | não | até 1 itens | | `buttons[].phone_number` | `string` | não | 1 a 20 caracteres | #### Exemplos de código ```bash curl -X PATCH "https://api.lunahia.com.br/v1/templates/YOUR_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "bodyText": "YOUR_BODYTEXT", "examples": {}, "header": "YOUR_HEADER" }' ``` #### Respostas **200**: Sucesso. ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "metaTemplateId": "YOUR_METATEMPLATEID", "wabaId": "YOUR_WABAID", "name": "YOUR_NAME", "language": "YOUR_LANGUAGE", "category": "YOUR_CATEGORY", "status": "YOUR_STATUS", "createdAt": "YOUR_CREATEDAT", "updatedAt": "YOUR_UPDATEDAT" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Remover um template `DELETE /v1/templates/{id}` Remove o template na Meta e da sua listagem. Autenticação: Chave de API. Escopo exigido: `templates:write` Guia do tema: https://lunahia.com.br/docs/templates#rota-delete-v1-templates-id #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | | #### Exemplos de código ```bash curl -X DELETE "https://api.lunahia.com.br/v1/templates/YOUR_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo. **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Ler as regras de um template `GET /v1/templates/rules` As categorias, os idiomas sugeridos, o formato do nome, os tamanhos máximos de corpo, cabeçalho e rodapé, e os limites de botões. É o que POST /v1/templates cobra, servido para você mostrar o mesmo limite sem copiar o número. Autenticação: Chave de API. Escopo exigido: `templates:read` #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/templates/rules" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "categories": [ { "value": "MARKETING", "label": "Marketing", "summary": "Promove, convida ou tenta reengajar: oferta, novidade, carrinho esquecido. A Meta pode reclassificar um template de utilidade para marketing." } ], "languages": [ { "code": "pt_BR", "label": "Português (Brasil)" } ], "namePattern": "^[a-z0-9_]{1,512}$", "nameExample": "confirmacao_do_pedido", "bodyMaxLength": 1024, "headerMaxLength": 60, "footerMaxLength": 60, "buttonLimits": { "total": 10, "byType": { "QUICK_REPLY": 10, "URL": 2, "PHONE_NUMBER": 1, "COPY_CODE": 1 } } } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Criar um template de autenticação `POST /v1/templates/authentication` Cria um template de autenticação com botão de copiar código, e o submete à Meta para aprovação. Autenticação: Chave de API. Escopo exigido: `templates:write` Guia do tema: https://lunahia.com.br/docs/templates#rota-post-v1-templates-authentication #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `wabaId` | `string` | sim | 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `name` | `string` | sim | /^[a-z0-9_]{1,512}$/ | | `language` | `string` | não | O código de idioma do template, na grafia da Meta: sublinhado e não hífen. pt_BR, pt_PT, en_US, es_MX, fr. A lista completa está em Supported Languages, na documentação da Meta, e o campo aceita qualquer código que ela publicar, porque um conjunto fechado aqui impediria você de usar o próximo. Ausente vale pt_BR. Atenção ao que o idioma custa: cada idioma é um template separado para a Meta, e o teto é de 250 templates por conta de WhatsApp Business. · /^[a-z]{2,3}(_[A-Z]{2})?$/ | | `addSecurityRecommendation` | `boolean` | não | Se o template deve incluir o aviso de segurança da Meta, que pede para não compartilhar o código. O texto é da Meta, é gerado no idioma do template e não é customizável. Ausente vale falso. | | `codeExpirationMinutes` | `integer` | sim | Em quantos minutos o código expira. Vai para o rodapé do template, num texto da Meta que não é customizável. O teto aceito aqui é uma guarda desta plataforma contra valor absurdo, e não uma afirmação sobre a faixa que a Meta aceita: essa faixa não está publicada na documentação dela. · mínimo 1 · máximo 1440 | | `buttonText` | `string` | não | O rótulo do botão de copiar código. Omitir é o recomendado: sem ele a Meta usa o rótulo padrão do idioma do template, que já está traduzido. Máximo de 25 caracteres. · 1 a 25 caracteres | | `messageSendTtlSeconds` | `integer` | não | Tempo de vida, em segundos, das mensagens enviadas com este template. Ausente, o campo não é enviado à Meta e vale o padrão dela. Um código de verificação que chega tarde demais já não serve, e é para isso que ele existe. · mínimo 1 | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/templates/authentication" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "wabaId": "YOUR_WABAID", "name": "YOUR_NAME", "codeExpirationMinutes": 10 }' ``` #### Respostas **201**: Criado. ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "metaTemplateId": "YOUR_METATEMPLATEID", "wabaId": "YOUR_WABAID", "name": "YOUR_NAME", "language": "YOUR_LANGUAGE", "category": "YOUR_CATEGORY", "status": "YOUR_STATUS", "createdAt": "YOUR_CREATEDAT", "updatedAt": "YOUR_UPDATEDAT" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Copiar um template para outros clientes `POST /v1/templates/{id}/copy` Cria uma cópia do template em até 50 destinos, cada um uma conta de negócio (wabaId) ou um cliente seu (externalId). Responde 200 com um resultado por destino, e um destino que falha não derruba os outros. A cópia passa pelo mesmo caminho e pelas mesmas regras de POST /v1/templates. Autenticação: Chave de API. Escopo exigido: `templates:write` #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | | #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `targets` | `array` | sim | Os destinos, de 1 a 50. Cada um é { wabaId } ou { externalId }. · 1 a 50 itens | | `targets[].wabaId` | `string` | não | A conta de negócio de destino, pelo id dela na Meta (wabaId). · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `targets[].externalId` | `string` | não | O rótulo do cliente de destino (externalId): a cópia vai para cada conta de WhatsApp Business dos números dele. · 1 a 128 caracteres | | `headerMediaHandle` | `string` | não | O handle do arquivo de exemplo do cabeçalho de mídia, para template de origem que tem um. A Luna guarda só o formato do cabeçalho, não o arquivo. · 1 a 1024 caracteres | | `authentication` | `object` | não | Os parâmetros do template de autenticação, obrigatórios quando o template de origem é de autenticação: a Luna não os guarda. | | `authentication.addSecurityRecommendation` | `boolean` | não | Se o template deve incluir o aviso de segurança da Meta, que pede para não compartilhar o código. O texto é da Meta, é gerado no idioma do template e não é customizável. Ausente vale falso. | | `authentication.codeExpirationMinutes` | `integer` | sim | Em quantos minutos o código expira. Vai para o rodapé do template, num texto da Meta que não é customizável. O teto aceito aqui é uma guarda desta plataforma contra valor absurdo, e não uma afirmação sobre a faixa que a Meta aceita: essa faixa não está publicada na documentação dela. · mínimo 1 · máximo 1440 | | `authentication.buttonText` | `string` | não | O rótulo do botão de copiar código. Omitir é o recomendado: sem ele a Meta usa o rótulo padrão do idioma do template, que já está traduzido. Máximo de 25 caracteres. · 1 a 25 caracteres | | `authentication.messageSendTtlSeconds` | `integer` | não | Tempo de vida, em segundos, das mensagens enviadas com este template. Ausente, o campo não é enviado à Meta e vale o padrão dela. Um código de verificação que chega tarde demais já não serve, e é para isso que ele existe. · mínimo 1 | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/templates/YOUR_ID/copy" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "targets": [ { "wabaId": "YOUR_WABAID", "externalId": "YOUR_EXTERNALID" } ] }' ``` #### Respostas **200**: Sucesso. ```json { "results": [ { "target": { "wabaId": "YOUR_WABAID", "externalId": "YOUR_EXTERNALID" }, "wabaId": "YOUR_WABAID", "status": 1, "template": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "metaTemplateId": "YOUR_METATEMPLATEID", "wabaId": "YOUR_WABAID", "name": "YOUR_NAME", "language": "YOUR_LANGUAGE", "category": "YOUR_CATEGORY", "status": "YOUR_STATUS", "createdAt": "YOUR_CREATEDAT", "updatedAt": "YOUR_UPDATEDAT" }, "error": { "error": "YOUR_ERROR", "message": "YOUR_MESSAGE" } } ] } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "template_content_unknown", "docsUrl": "https://lunahia.com.br/docs/templates", "message": "A Luna não conhece o conteúdo deste template: ele foi criado direto no painel da Meta, ou antes de a Luna guardar o conteúdo. Sem o conteúdo não há o que copiar. Crie o template de novo por POST /v1/templates e copie o novo." } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Subir o arquivo de exemplo de um cabeçalho de mídia `POST /v1/template-assets` Recebe um arquivo em multipart/form-data no campo file e devolve o handle que a criação de template aceita em headerMedia.handle. Autenticação: Chave de API. Escopo exigido: `templates:write` Guia do tema: https://lunahia.com.br/docs/templates#rota-post-v1-template-assets #### Corpo da requisição `multipart/form-data` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `file` | `string (binary)` | sim | O arquivo a enviar, no campo file. | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/template-assets" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -F "file=@./pedido.jpg;type=image/jpeg" ``` #### Respostas **200**: Sucesso. ```json { "handle": "4:cGVkaWRvLnBuZw==:aW1hZ2UvcG5n:ARb0Xk:e:1790451084:1269849425120687:0" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **413**: O arquivo passa do teto de tamanho, que é o mesmo para todos os clientes. ```json { "error": "file_too_large", "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens", "message": "O arquivo passa do tamanho que a plataforma aceita. O limite é o mesmo para todos os clientes: ele existe por capacidade de infraestrutura." } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ## Números Os números conectados: conectar, ver estado, qualidade e vazão, editar e desconectar. Migrar um número que já está na API de outro provedor é caminho suportado, e não exige número novo nem perda do número atual. Um número já registrado na Cloud API de outro provedor quase sempre tem verificação em duas etapas configurada lá, e a Meta exige o PIN existente para registrá-lo de novo: não há endpoint para ler nem para desligar esse PIN, então ele precisa vir do negócio final. Informe o PIN em POST /v1/numbers/{id}/pin, ou peça ao negócio final que desligue a verificação em duas etapas no WhatsApp Manager dele. Os outros pré-requisitos também são do lado dele: ser o dono da conta de WhatsApp Business e ter o número liberado no provedor anterior. Um número que hoje só existe no WhatsApp Business App, o aplicativo de celular, é o outro caso, e a Meta o chama de coexistência. Ele nunca passou por API nenhuma. A conexão parte da mesma janela da Meta, e a opção só aparece quando a conta do negócio final está habilitada para isso do lado da Meta e o aplicativo no aparelho está na versão 2.24.17 ou maior. Conectado assim, o número continua funcionando no aplicativo de celular, e as conversas anteriores do aparelho são importadas para a plataforma: elas aparecem em GET /v1/messages junto das novas. A importação tem prazo para concluir, e quem diz onde ela está é GET /v1/numbers/{id}, nos campos sincronizacaoDoHistorico e sincronizacaoPrazo. O mesmo recurso traz tetoDeVazaoPorSegundo, que é o teto fixo de vazão de um número em coexistência e não sobe com o tempo. E o que o dono do negócio responder pelo aplicativo de celular também chega, na conversa do destinatário. ### Ler o perfil do negócio `GET /v1/numbers/{id}/profile` O perfil que o contato vê no WhatsApp: recado, endereço, descrição, e-mail, sites, ramo e a foto. Não vale para número em coexistência. Autenticação: Chave de API. Escopo exigido: `numbers:read` #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/numbers/YOUR_ID/profile" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "about": "Atendimento de segunda a sexta", "address": "YOUR_ADDRESS", "description": "YOUR_DESCRIPTION", "email": "ana@suaempresa.com.br", "websites": [ "YOUR_WEBSITES" ], "vertical": "YOUR_VERTICAL", "profilePictureUrl": "YOUR_PROFILEPICTUREURL" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "not_available_in_coexistence", "docsUrl": "https://lunahia.com.br/docs/numero-na-meta", "message": "Este número está conectado em coexistência, e a Meta não aceita esta operação por API nesse caso. Faça a mudança no aplicativo WhatsApp Business do celular do negócio." } ``` **422**: O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa. ```json { "error": "meta_rejected", "docsUrl": "https://lunahia.com.br/docs/numero-na-meta", "message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.", "meta": { "codigo": 131030, "categoria": "nao_entregavel", "mensagem": "A Meta recusou o pedido.", "acaoRecomendada": "Confira os campos enviados e tente de novo.", "original": { "error": { "message": "Invalid parameter", "type": "OAuthException", "code": 131030, "fbtrace_id": "AbCdEfGhIjK" } } } } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Mudar o perfil do negócio `PATCH /v1/numbers/{id}/profile` Troca os campos que você mandar, e deixa os outros como estão. Com displayName, pede a mudança do nome de exibição e responde 202: o nome fica em revisão na Meta. Não vale para número em coexistência. Autenticação: Chave de API. Escopo exigido: `numbers:write` #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. | #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `about` | `string` | não | O recado curto. Até 139 caracteres. · 1 a 139 caracteres | | `address` | `string` | não | O endereço. Até 256 caracteres. · 1 a 256 caracteres | | `description` | `string` | não | A descrição. Até 512 caracteres. · 1 a 512 caracteres | | `email` | `string` | não | O e-mail de contato. Até 128 caracteres. · 1 a 128 caracteres | | `websites` | `array` | não | Até dois sites. A lista inteira substitui a que existe. · até 2 itens | | `vertical` | `string` | não | O ramo de atividade, no vocabulário da Meta. · 1 a 64 caracteres | | `displayName` | `string` | não | Pede à Meta a mudança do nome de exibição (o nome que o contato vê no topo da conversa). A resposta é 202: o pedido está em revisão e displayNameStatus passa a pending_review. A Meta aceita até 10 mudanças a cada 30 dias, e é ela quem julga o nome. O evento number.display_name_reviewed avisa o resultado. Um nome aprovado só passa a valer depois que o número é registrado de novo. · 1 a 512 caracteres | | `profilePictureHandle` | `string` | não | O handle de uma foto que você subiu pelo envio resumível da Meta. O mesmo handle que POST /v1/template-assets devolve serve de foto do perfil, o que está a confirmar na doc da Meta. · 1 a 1024 caracteres | #### Exemplos de código ```bash curl -X PATCH "https://api.lunahia.com.br/v1/numbers/YOUR_ID/profile" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "about": "YOUR_ABOUT", "address": "YOUR_ADDRESS", "description": "YOUR_DESCRIPTION" }' ``` #### Respostas **200**: Sucesso. ```json { "updatedFields": [ "YOUR_UPDATEDFIELDS" ] } ``` **202**: Aceito: o pedido foi registrado e será processado. ```json { "updatedFields": [ "YOUR_UPDATEDFIELDS" ], "displayNameStatus": "pending_review", "pendingDisplayName": "YOUR_PENDINGDISPLAYNAME" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "not_available_in_coexistence", "docsUrl": "https://lunahia.com.br/docs/numero-na-meta", "message": "Este número está conectado em coexistência, e a Meta não aceita esta operação por API nesse caso. Faça a mudança no aplicativo WhatsApp Business do celular do negócio." } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **422**: O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa. ```json { "error": "meta_rejected", "docsUrl": "https://lunahia.com.br/docs/numero-na-meta", "message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.", "meta": { "codigo": 131030, "categoria": "nao_entregavel", "mensagem": "A Meta recusou o pedido.", "acaoRecomendada": "Confira os campos enviados e tente de novo.", "original": { "error": { "message": "Invalid parameter", "type": "OAuthException", "code": 131030, "fbtrace_id": "AbCdEfGhIjK" } } } } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Listar os usuários bloqueados `GET /v1/numbers/{id}/blocked-users` Quem este número bloqueou, em páginas. O cursor é o da Meta, e não muda de forma. Autenticação: Chave de API. Escopo exigido: `messages:read` #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. | #### Parâmetros de consulta | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `limit` | `integer` | não | Quantos por página, de 1 a 100. | | `cursor` | `string` | não | O nextCursor da página anterior. | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/numbers/YOUR_ID/blocked-users" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "data": [ { "waId": "YOUR_WAID", "userId": "YOUR_USERID" } ], "nextCursor": "YOUR_NEXTCURSOR" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "number_disconnected", "docsUrl": "https://lunahia.com.br/docs/conectar-numero", "message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)." } ``` **422**: O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa. ```json { "error": "meta_rejected", "docsUrl": "https://lunahia.com.br/docs/numero-na-meta", "message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.", "meta": { "codigo": 131030, "categoria": "nao_entregavel", "mensagem": "A Meta recusou o pedido.", "acaoRecomendada": "Confira os campos enviados e tente de novo.", "original": { "error": { "message": "Invalid parameter", "type": "OAuthException", "code": 131030, "fbtrace_id": "AbCdEfGhIjK" } } } } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Bloquear usuários `POST /v1/numbers/{id}/blocked-users` Bloqueia quem escreveu ao número nas últimas 24 horas. Cada usuário é um telefone ou um BSUID, e a resposta separa os que a Meta aceitou dos que ela recusou, com o motivo. Autenticação: Chave de API. Escopo exigido: `messages:write` #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. | #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `users` | `array` | sim | Os usuários a bloquear, de um a cinquenta. · 1 a 50 itens | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/numbers/YOUR_ID/blocked-users" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "users": [ "YOUR_USERS" ] }' ``` #### Respostas **200**: Sucesso. ```json { "done": [ { "input": "YOUR_INPUT", "waId": "YOUR_WAID", "userId": "YOUR_USERID", "reasons": [ "YOUR_REASONS" ] } ], "failed": [ { "input": "YOUR_INPUT", "waId": "YOUR_WAID", "userId": "YOUR_USERID", "reasons": [ "YOUR_REASONS" ] } ] } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "number_disconnected", "docsUrl": "https://lunahia.com.br/docs/conectar-numero", "message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)." } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **422**: O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa. ```json { "error": "meta_rejected", "docsUrl": "https://lunahia.com.br/docs/numero-na-meta", "message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.", "meta": { "codigo": 131030, "categoria": "nao_entregavel", "mensagem": "A Meta recusou o pedido.", "acaoRecomendada": "Confira os campos enviados e tente de novo.", "original": { "error": { "message": "Invalid parameter", "type": "OAuthException", "code": 131030, "fbtrace_id": "AbCdEfGhIjK" } } } } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Desbloquear um usuário `DELETE /v1/numbers/{id}/blocked-users/{user}` Desbloqueia um usuário, pelo telefone ou pelo BSUID que está no caminho. Fica aberta na conta suspensa: desbloquear nunca é o problema. Autenticação: Chave de API. Escopo exigido: `messages:write` #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. | | `user` | `string` | sim | O telefone (só dígitos) ou o BSUID do usuário. | #### Exemplos de código ```bash curl -X DELETE "https://api.lunahia.com.br/v1/numbers/YOUR_ID/blocked-users/YOUR_USER" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "done": [ { "input": "YOUR_INPUT", "waId": "YOUR_WAID", "userId": "YOUR_USERID", "reasons": [ "YOUR_REASONS" ] } ], "failed": [ { "input": "YOUR_INPUT", "waId": "YOUR_WAID", "userId": "YOUR_USERID", "reasons": [ "YOUR_REASONS" ] } ] } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "number_disconnected", "docsUrl": "https://lunahia.com.br/docs/conectar-numero", "message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)." } ``` **422**: O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa. ```json { "error": "meta_rejected", "docsUrl": "https://lunahia.com.br/docs/numero-na-meta", "message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.", "meta": { "codigo": 131030, "categoria": "nao_entregavel", "mensagem": "A Meta recusou o pedido.", "acaoRecomendada": "Confira os campos enviados e tente de novo.", "original": { "error": { "message": "Invalid parameter", "type": "OAuthException", "code": 131030, "fbtrace_id": "AbCdEfGhIjK" } } } } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Listar os QR codes `GET /v1/numbers/{id}/qr-codes` Os códigos que existem neste número, com o link curto de cada um. Autenticação: Chave de API. Escopo exigido: `numbers:read` #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/numbers/YOUR_ID/qr-codes" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "data": [ { "code": "4O4YGZEG3RIVE1", "prefilledMessage": "YOUR_PREFILLEDMESSAGE", "link": "https://exemplo.com.br/arquivo", "imageUrl": "YOUR_IMAGEURL" } ] } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "number_disconnected", "docsUrl": "https://lunahia.com.br/docs/conectar-numero", "message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)." } ``` **422**: O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa. ```json { "error": "meta_rejected", "docsUrl": "https://lunahia.com.br/docs/numero-na-meta", "message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.", "meta": { "codigo": 131030, "categoria": "nao_entregavel", "mensagem": "A Meta recusou o pedido.", "acaoRecomendada": "Confira os campos enviados e tente de novo.", "original": { "error": { "message": "Invalid parameter", "type": "OAuthException", "code": 131030, "fbtrace_id": "AbCdEfGhIjK" } } } } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Criar um QR code e um link curto `POST /v1/numbers/{id}/qr-codes` Cria um código que abre uma conversa com o número, com a mensagem já escrita. Devolve o código, o link curto e, se você pediu, o endereço da imagem. Autenticação: Chave de API. Escopo exigido: `numbers:write` #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. | #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `prefilledMessage` | `string` | sim | A mensagem que já vem escrita. Até 140 caracteres, o limite da Meta, que está a confirmar na doc dela. · 1 a 140 caracteres | | `imageFormat` | `string` | não | Peça a imagem do QR em PNG ou SVG. Sem isto, só o código e o link voltam. · Valores: PNG, SVG | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/numbers/YOUR_ID/qr-codes" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prefilledMessage": "YOUR_PREFILLEDMESSAGE" }' ``` #### Respostas **201**: Criado. ```json { "code": "4O4YGZEG3RIVE1", "prefilledMessage": "YOUR_PREFILLEDMESSAGE", "link": "https://exemplo.com.br/arquivo", "imageUrl": "YOUR_IMAGEURL" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "number_disconnected", "docsUrl": "https://lunahia.com.br/docs/conectar-numero", "message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)." } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **422**: O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa. ```json { "error": "meta_rejected", "docsUrl": "https://lunahia.com.br/docs/numero-na-meta", "message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.", "meta": { "codigo": 131030, "categoria": "nao_entregavel", "mensagem": "A Meta recusou o pedido.", "acaoRecomendada": "Confira os campos enviados e tente de novo.", "original": { "error": { "message": "Invalid parameter", "type": "OAuthException", "code": 131030, "fbtrace_id": "AbCdEfGhIjK" } } } } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Apagar um QR code `DELETE /v1/numbers/{id}/qr-codes/{code}` Apaga o código e o link curto: quem ainda tem o QR impresso deixa de abrir a conversa. Fica aberta na conta suspensa. Autenticação: Chave de API. Escopo exigido: `numbers:write` #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. | | `code` | `string` | sim | O código do QR, como a criação o devolveu. | #### Exemplos de código ```bash curl -X DELETE "https://api.lunahia.com.br/v1/numbers/YOUR_ID/qr-codes/YOUR_CODE" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo. **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "number_disconnected", "docsUrl": "https://lunahia.com.br/docs/conectar-numero", "message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)." } ``` **422**: O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa. ```json { "error": "meta_rejected", "docsUrl": "https://lunahia.com.br/docs/numero-na-meta", "message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.", "meta": { "codigo": 131030, "categoria": "nao_entregavel", "mensagem": "A Meta recusou o pedido.", "acaoRecomendada": "Confira os campos enviados e tente de novo.", "original": { "error": { "message": "Invalid parameter", "type": "OAuthException", "code": 131030, "fbtrace_id": "AbCdEfGhIjK" } } } } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Abrir uma sessão de conexão `POST /v1/onboarding/sessions` Cria a sessão que o fluxo de conexão da Meta preenche, e devolve o sessionId e o csrfState. Autenticação: Chave de API. Escopo exigido: `onboarding:write` Guia do tema: https://lunahia.com.br/docs/conectar-numero#rota-post-v1-onboarding-sessions #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/onboarding/sessions" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **201**: Criado. ```json { "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "state": "YOUR_STATE", "configId": "YOUR_CONFIGID", "sdkVersion": "YOUR_SDKVERSION", "csrfState": "YOUR_CSRFSTATE", "expiresAt": "YOUR_EXPIRESAT" } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "number_capacity_reached", "message": "Esta conta já tem 20 números ativos, o máximo contratado (20). Para conectar outro, desconecte um número (DELETE /v1/numbers/{id}) ou escreva para contato@lunahia.com.br.", "capacity": 20, "activeNumbers": 20 } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Consultar uma sessão de conexão `GET /v1/onboarding/sessions/{id}` O estado atual da sessão e a orientação correspondente, em português, pronta para exibir. Autenticação: Chave de API. Escopo exigido: `onboarding:write` Guia do tema: https://lunahia.com.br/docs/conectar-numero#rota-get-v1-onboarding-sessions-id #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/onboarding/sessions/YOUR_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "state": "YOUR_STATE", "orientacao": "YOUR_ORIENTACAO", "terminal": true, "proximoPasso": "YOUR_PROXIMOPASSO", "attemptCount": 1, "nextAttemptAt": "YOUR_NEXTATTEMPTAT", "retryNotBefore": "YOUR_RETRYNOTBEFORE", "expiresAt": "YOUR_EXPIRESAT", "createdAt": "YOUR_CREATEDAT", "updatedAt": "YOUR_UPDATEDAT" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Registrar abandono ou erro do fluxo `POST /v1/onboarding/sessions/{id}/abandon` Telemetria do que aconteceu na janela da Meta quando o fluxo não completou: em que tela o cliente parou, ou que erro a Meta reportou. Autenticação: Chave de API. Escopo exigido: `onboarding:write` Guia do tema: https://lunahia.com.br/docs/conectar-numero#rota-post-v1-onboarding-sessions-id-abandon #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | | #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `csrfState` | `string` | sim | | | `currentStep` | `string \| null` | não | 1 a 120 caracteres | | `errorCode` | `integer \| null` | não | | | `errorMessage` | `string \| null` | não | | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/onboarding/sessions/YOUR_ID/abandon" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "csrfState": "YOUR_CSRFSTATE" }' ``` #### Respostas **200**: Sucesso. ```json { "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "state": "YOUR_STATE", "orientacao": "YOUR_ORIENTACAO", "abandonedAtStep": "YOUR_ABANDONEDATSTEP" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Concluir a conexão `POST /v1/onboarding/sessions/{id}/complete` Troca o código do fluxo embutido por acesso permanente à conta do cliente, e leva a sessão até o fim: token selado, aplicativo inscrito na conta, número registrado. Autenticação: Chave de API. Escopo exigido: `onboarding:write` Guia do tema: https://lunahia.com.br/docs/conectar-numero#rota-post-v1-onboarding-sessions-id-complete #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | | #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `code` | `string` | sim | | | `csrfState` | `string` | sim | | | `wabaId` | `string \| null` | não | | | `phoneNumberId` | `string \| null` | não | | | `businessId` | `string \| null` | não | | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/onboarding/sessions/YOUR_ID/complete" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "code": "YOUR_CODE", "csrfState": "YOUR_CSRFSTATE" }' ``` #### Respostas **200**: Sucesso. ```json { "sessionId": "77012a00-f049-4523-a658-3a3a4b105de6", "state": "APP_SUBSCRIBED", "orientacao": "O número está registrado na Meta e pronto para trocar mensagem.", "terminal": true, "proximoPasso": null, "motivo": null, "podeRetentar": false, "wabaId": "2000000000000001", "phoneNumberId": "1000000000000001" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Listar números conectados `GET /v1/numbers` Todos os números de WhatsApp conectados a este cliente, com estado, qualidade, velocidade de envio e limite diário de conversas. Filtros: externalId (igualdade exata), q (busca por prefixo em externalId, label e displayNumber), state, wabaId, qualityRating, connectionStatus, ready e canSend. Parâmetro que a rota não conhece volta 400. Autenticação: Chave de API. Escopo exigido: `numbers:read` Guia do tema: https://lunahia.com.br/docs/plano-e-numeros#rota-get-v1-numbers #### Parâmetros de consulta | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `externalId` | `string` | não | O rótulo que você deu ao seu cliente. Igualdade exata; rótulo sem número devolve lista vazia. | | `state` | `string` | não | O estado do número (state): PENDING, REGISTER_SENT, REGISTERED, PIN_REQUIRED, BLOCKED ou DISCONNECTED. | | `q` | `string` | não | Busca por prefixo, sem diferenciar maiúscula, em externalId, label e displayNumber. Quem digita só o número de telefone acha o número mesmo sem os espaços e o hífen. | | `wabaId` | `string` | não | O id da conta de negócio na Meta (waba.id): só os números dela. Igualdade exata; uma conta sem número seu devolve lista vazia. | | `qualityRating` | `string` | não | A qualidade que a Meta informou para o número (qualityRating): GREEN, YELLOW, RED, NA ou UNKNOWN. Número cuja qualidade a Luna ainda não leu (qualityRating nulo) não entra em nenhum valor. | | `connectionStatus` | `string` | não | Só os números com este connection.status: connected, connecting, action_required ou disconnected. | | `ready` | `string` | não | true: só os números prontos para enviar e receber. false: só os que ainda não estão. | | `canSend` | `string` | não | true: só os números por onde enviar funciona agora (connection.canSend). false: só os que não. | | `limit` | `integer` | não | Quantos números por página: de 1 a 100, 50 se omitido. | | `cursor` | `string` | não | O nextCursor da resposta anterior. Opaco: carrega posição, não contagem. | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/numbers" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "data": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "metaPhoneNumberId": "YOUR_METAPHONENUMBERID", "displayNumber": "YOUR_DISPLAYNUMBER", "state": "YOUR_STATE", "retryNotBefore": "YOUR_RETRYNOTBEFORE", "podeRetentar": true, "qualityRating": "YOUR_QUALITYRATING", "throughputLevel": "YOUR_THROUGHPUTLEVEL", "limiteDiarioDeConversas": "YOUR_LIMITEDIARIODECONVERSAS", "codeVerificationStatus": "YOUR_CODEVERIFICATIONSTATUS", "displayName": "YOUR_DISPLAYNAME", "displayNameStatus": "YOUR_DISPLAYNAMESTATUS", "pendingDisplayName": "YOUR_PENDINGDISPLAYNAME", "autoRead": true, "externalId": "YOUR_EXTERNALID", "label": "YOUR_LABEL", "orientacao": "YOUR_ORIENTACAO", "awaitingPaymentSince": "YOUR_AWAITINGPAYMENTSINCE", "waba": { "id": "YOUR_ID", "restricted": true, "disabled": true, "credentialExpiresAt": "YOUR_CREDENTIALEXPIRESAT", "credentialNeverExpires": true, "paymentMethodOnMeta": true, "currency": "YOUR_CURRENCY" }, "ready": true, "connection": { "status": "connected", "canSend": true, "reasons": [ { "code": "YOUR_CODE", "message": "YOUR_MESSAGE", "solution": "YOUR_SOLUTION", "action": "send_pin", "actionUrl": null, "docsUrl": null, "since": null } ] }, "allowedActions": [ "disconnect" ], "blockedActions": [ { "action": "disconnect", "message": "YOUR_MESSAGE" } ], "createdAt": "YOUR_CREATEDAT", "updatedAt": "YOUR_UPDATEDAT" } ], "nextCursor": "YOUR_NEXTCURSOR" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Consultar um número `GET /v1/numbers/{id}` Um número, com tudo que a listagem traz mais a saúde da conexão com a Meta. Autenticação: Chave de API. Escopo exigido: `numbers:read` Guia do tema: https://lunahia.com.br/docs/plano-e-numeros#rota-get-v1-numbers-id #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/numbers/YOUR_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "id": "ed404df1-b420-4ed6-8743-ba1609892e0a", "metaPhoneNumberId": "1000000000000001", "displayNumber": "+55 11 90000-0000", "state": "REGISTERED", "retryNotBefore": null, "podeRetentar": false, "qualityRating": "GREEN", "throughputLevel": "STANDARD", "limiteDiarioDeConversas": "TIER_10K", "codeVerificationStatus": "VERIFIED", "displayName": "Clínica Sorriso", "displayNameStatus": "approved", "pendingDisplayName": null, "autoRead": false, "externalId": "cliente-8841", "label": "Atendimento Pinheiros", "orientacao": "Número conectado e operando. Mensagens já entram e saem por ele.", "awaitingPaymentSince": null, "waba": { "id": "102290129340398", "restricted": false, "disabled": false, "credentialExpiresAt": null, "credentialNeverExpires": true, "paymentMethodOnMeta": true, "currency": "BRL" }, "ready": true, "connection": { "status": "connected", "canSend": true, "reasons": [], "steps": [ { "key": "authorized", "label": "Autorização do negócio", "status": "done" }, { "key": "receiving", "label": "Recebimento das mensagens", "status": "done" }, { "key": "registered", "label": "Número registrado", "status": "done" }, { "key": "ready", "label": "Pronto para usar", "status": "done" } ] }, "allowedActions": [ "disconnect", "edit_label" ], "blockedActions": [], "createdAt": "2026-08-07T11:28:14.597Z", "updatedAt": "2026-08-07T11:28:28.703Z", "tetoDeVazaoPorSegundo": null, "sincronizacaoDoHistorico": null, "sincronizacaoPrazo": null, "sincronizacaoProgresso": null, "subscriptionConfirmedAt": "2026-08-07T11:27:47.141Z", "credentialStatus": "active", "podeReconectar": false, "coexistence": false } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Editar um número `PATCH /v1/numbers/{id}` Troca o externalId e o label de um número, e liga ou desliga o autoRead (marcar como lida sozinho cada mensagem recebida). É o jeito de reaproveitar um número para outro cliente seu, ou de dar nome a um número que foi conectado pelo console, sem link. Autenticação: Chave de API. Escopo exigido: `numbers:write` Guia do tema: https://lunahia.com.br/docs/plano-e-numeros#rota-patch-v1-numbers-id #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. | #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `externalId` | `string \| null` | não | O seu identificador para o cliente dono do número (1 a 128 caracteres). null limpa. · 1 a 128 caracteres | | `label` | `string \| null` | não | Um nome livre e curto para reconhecer o número (1 a 128 caracteres). null limpa. · 1 a 128 caracteres | | `autoRead` | `boolean` | não | true: a Luna marca como lida, na Meta, cada mensagem que o número receber daqui em diante, sem indicador de digitando. false desliga. Ausente não muda. O padrão de um número é false. | #### Exemplos de código ```bash curl -X PATCH "https://api.lunahia.com.br/v1/numbers/YOUR_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "externalId": "YOUR_EXTERNALID", "label": "YOUR_LABEL", "autoRead": true }' ``` #### Respostas **200**: Sucesso. ```json { "id": "ed404df1-b420-4ed6-8743-ba1609892e0a", "metaPhoneNumberId": "1000000000000001", "displayNumber": "+55 11 90000-0000", "state": "REGISTERED", "retryNotBefore": null, "podeRetentar": false, "qualityRating": "GREEN", "throughputLevel": "STANDARD", "limiteDiarioDeConversas": "TIER_10K", "codeVerificationStatus": "VERIFIED", "displayName": "Clínica Sorriso", "displayNameStatus": "approved", "pendingDisplayName": null, "autoRead": false, "externalId": "cliente-8841", "label": "Atendimento Pinheiros", "orientacao": "Número conectado e operando. Mensagens já entram e saem por ele.", "awaitingPaymentSince": null, "waba": { "id": "102290129340398", "restricted": false, "disabled": false, "credentialExpiresAt": null, "credentialNeverExpires": true, "paymentMethodOnMeta": true, "currency": "BRL" }, "ready": true, "connection": { "status": "connected", "canSend": true, "reasons": [], "steps": [ { "key": "authorized", "label": "Autorização do negócio", "status": "done" }, { "key": "receiving", "label": "Recebimento das mensagens", "status": "done" }, { "key": "registered", "label": "Número registrado", "status": "done" }, { "key": "ready", "label": "Pronto para usar", "status": "done" } ] }, "allowedActions": [ "disconnect", "edit_label" ], "blockedActions": [], "createdAt": "2026-08-07T11:28:14.597Z", "updatedAt": "2026-08-07T11:28:28.703Z", "tetoDeVazaoPorSegundo": null, "sincronizacaoDoHistorico": null, "sincronizacaoPrazo": null, "sincronizacaoProgresso": null, "subscriptionConfirmedAt": "2026-08-07T11:27:47.141Z", "credentialStatus": "active", "podeReconectar": false, "coexistence": false } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Desconectar um número `DELETE /v1/numbers/{id}` Tira o número da Luna. É o jeito de abrir uma vaga na capacidade do plano: o número deixa de contar a partir deste instante, e o seu cliente pode ser trocado por outro. Autenticação: Chave de API. Escopo exigido: `numbers:write` Guia do tema: https://lunahia.com.br/docs/plano-e-numeros#rota-delete-v1-numbers-id #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. | #### Exemplos de código ```bash curl -X DELETE "https://api.lunahia.com.br/v1/numbers/YOUR_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo. **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Informar o PIN de verificação em duas etapas de um número `POST /v1/numbers/{id}/pin` Informa o PIN de verificação em duas etapas de um número que já está registrado na Cloud API de outro provedor, para que a Luna consiga registrá-lo sem que o negócio final precise desligar a verificação. Autenticação: Chave de API. Escopo exigido: `onboarding:write` Guia do tema: https://lunahia.com.br/docs/conectar-numero#rota-post-v1-numbers-id-pin #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. | #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `pin` | `string` | sim | O PIN de verificação em duas etapas deste número, com exatamente seis dígitos. Quando o número já tem verificação em duas etapas configurada em outro provedor, é o PIN existente dele, e apenas o negócio final o conhece: não existe endpoint para ler nem para desligar o PIN de um número. Quando o número não tem verificação em duas etapas, este valor passa a ser o PIN dele. · /^\d{6}$/ | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/numbers/YOUR_ID/pin" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "pin": "YOUR_PIN" }' ``` #### Respostas **200**: Sucesso. ```json { "id": "ed404df1-b420-4ed6-8743-ba1609892e0a", "state": "PENDING" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "pin_not_applicable", "docsUrl": "https://lunahia.com.br/docs/conectar-numero", "message": "Este número não está aguardando o PIN de verificação em duas etapas. O campo state diz em que ponto ele está." } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Reconectar um número cuja autorização morreu `POST /v1/onboarding/reconnect` Abre uma sessão de conexão para um número que já existe, quando a autorização concedida pelo cliente expirou ou foi revogada. Autenticação: Chave de API. Escopo exigido: `onboarding:write` Guia do tema: https://lunahia.com.br/docs/conectar-numero#rota-post-v1-onboarding-reconnect #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `numberId` | `string` | sim | O número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/onboarding/reconnect" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "numberId": "YOUR_NUMBERID" }' ``` #### Respostas **201**: Criado. ```json { "sessionId": "77012a00-f049-4523-a658-3a3a4b105de6", "state": "STARTED", "configId": "1234567890", "sdkVersion": "v26.0", "csrfState": "Xk3s...", "expiresAt": "2026-08-26T18:30:00.000Z" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "reconnect_not_applicable", "docsUrl": "https://lunahia.com.br/docs/conectar-numero", "message": "A autorização deste número não admite reconexão.", "credentialStatus": "active" } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Listar contas de negócio `GET /v1/business-accounts` As contas de WhatsApp Business que este cliente conectou, da mais recente para a mais antiga, cada uma com o nome na Meta, o endereço no WhatsApp Manager e os números. Autenticação: Chave de API. Escopo exigido: `numbers:read` Guia do tema: https://lunahia.com.br/docs/conectar-numero#rota-get-v1-business-accounts #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/business-accounts" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "data": [ { "id": "ed404df1-b420-4ed6-8743-ba1609892e0a", "wabaId": "102290129340398", "numbers": [ "+55 11 90000-0000" ], "name": "Padaria do Zé", "managerUrl": "https://business.facebook.com/latest/whatsapp_manager/overview?asset_id=102290129340398", "phoneNumbers": [ { "id": "a3c1f5b2-7d4e-4b8a-9c21-5e6f7a8b9c0d", "displayNumber": "+55 11 90000-0000", "externalId": "cliente-8841", "label": "Atendimento Pinheiros" } ], "status": { "restricted": false, "restrictions": [], "disabled": false, "violationType": null, "reportedAt": null }, "credentialExpiresAt": null, "credentialNeverExpires": true, "paymentMethodOnMeta": true, "currency": "BRL", "createdAt": "2026-08-07T11:27:41.208Z" } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Conferir agora a forma de pagamento da conta na Meta `POST /v1/business-accounts/{id}/payment-method/check` Lê na Meta se a conta tem forma de pagamento cadastrada, sem esperar a leitura de hora em hora, e devolve o resultado. O aviso por webhook segue o caminho de sempre: number.action_required (motivo payment_method_missing) quando falta e number.action_resolved quando aparece. Leitura com menos de 60 segundos é devolvida sem chamar a Meta, e a chamada respeita o orçamento de chamadas da conta. Autenticação: Chave de API. Escopo exigido: `numbers:read` #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O id da conta de negócio na Luna, o mesmo que GET /v1/business-accounts devolve em id. | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/business-accounts/YOUR_ID/payment-method/check" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "id": "ed404df1-b420-4ed6-8743-ba1609892e0a", "wabaId": "102290129340398", "paymentMethodOnMeta": false, "currency": "BRL", "checkedAt": "2026-11-05T14:02:11.000Z", "refreshed": true, "reason": "checked" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Consultar a saúde de um número `GET /v1/numbers/{id}/health` A avaliação de qualidade, o nível de vazão e o limite diário de conversas que a Meta atribui a este número agora, e as mudanças que a plataforma observou ao longo do tempo. Autenticação: Chave de API. Escopo exigido: `numbers:read` Guia do tema: https://lunahia.com.br/docs/saude-da-conta#rota-get-v1-numbers-id-health #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem. | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/numbers/YOUR_ID/health" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "qualityRating": "GREEN", "throughputLevel": "HIGH", "tetoDeVazaoPorSegundo": null, "sincronizacaoDoHistorico": "em_curso", "sincronizacaoPrazo": "2026-09-19T09:00:00.000Z", "sincronizacaoProgresso": 40, "limiteDiarioDeConversas": "TIER_10K", "codeVerificationStatus": "VERIFIED", "checkedAt": "2026-08-26T12:00:00.000Z", "transitions": [ { "qualityRating": "GREEN", "throughputLevel": "HIGH", "limiteDiarioDeConversas": "TIER_2K", "codeVerificationStatus": "VERIFIED", "observedAt": "2026-08-24T10:00:00.000Z" } ] } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Ler o consumo da Meta de um número ou de um cliente `GET /v1/usage` O consumo que a Meta mede para um número (numberId) ou para todos os números de um cliente seu (externalId), repassado como ela informa, com a moeda de cada conta e sem somar. format=csv devolve text/csv. A Luna só lê e mostra: nada disto entra na assinatura da Luna. Autenticação: Chave de API. Escopo exigido: `numbers:read` #### Parâmetros de consulta | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `numberId` | `string` | não | O número a consultar: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Os dois valem. Mande este ou externalId, nunca os dois. | | `externalId` | `string` | não | O rótulo do seu cliente (o externalId do link de conexão): lê o consumo de todos os números dele, cada um na moeda da conta dele. Mande este ou numberId, nunca os dois. | | `start` | `any` | não | O começo do período, em ISO 8601 (data ou data e hora, em UTC). Ausente, o primeiro dia do mês corrente. | | `end` | `any` | não | O fim do período, em ISO 8601. Ausente, agora (arredondado para baixo a cada cinco minutos). | | `granularity` | `string` | não | O tamanho de cada ponto, no vocabulário da Meta: HALF_HOUR, DAILY (o padrão) ou MONTHLY. A Meta limita o período de cada um, e recusa o que passa do limite dela. | | `format` | `string` | não | json (o padrão) ou csv. O csv vem em text/csv, uma linha por ponto, com numberId, phoneNumberId e currency em cada linha, para planilha. | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/usage" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "numberId": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phoneNumberId": "123456789012345", "externalId": null, "start": "2026-11-01T00:00:00.000Z", "end": "2026-11-03T15:00:00.000Z", "granularity": "DAILY", "readAt": "2026-11-03T15:00:12.000Z", "notice": "Valores aproximados, como a Meta os informa, na moeda da conta do negócio na Meta. A Meta cobra o uso do WhatsApp direto do negócio dono do número, e a fatura dela é a referência: este consumo pode divergir dela. A Luna só repassa a leitura, e nada daqui entra na assinatura da Luna.", "numbers": [ { "numberId": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phoneNumberId": "123456789012345", "currency": "BRL", "read": true, "reason": null } ], "data": [ { "numberId": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phoneNumberId": "123456789012345", "currency": "BRL", "start": "2026-11-02T03:00:00.000Z", "end": "2026-11-03T03:00:00.000Z", "pricingCategory": "UTILITY", "pricingType": "REGULAR", "tier": null, "country": "BR", "volume": 12, "cost": 0.5 } ] } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "number_disconnected", "docsUrl": "https://lunahia.com.br/docs/conectar-numero", "message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)." } ``` **422**: O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa. ```json { "error": "meta_rejected", "docsUrl": "https://lunahia.com.br/docs/numero-na-meta", "message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.", "meta": { "codigo": 131030, "categoria": "nao_entregavel", "mensagem": "A Meta recusou o pedido.", "acaoRecomendada": "Confira os campos enviados e tente de novo.", "original": { "error": { "message": "Invalid parameter", "type": "OAuthException", "code": 131030, "fbtrace_id": "AbCdEfGhIjK" } } } } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ## Links de conexão Um link que o seu cliente abre para conectar o número de WhatsApp dele, sem receber o login do seu console. Um link por cliente seu, amarrado ao externalId que você escolheu. ### Listar os links de conexão `GET /v1/onboarding/links` Os links que você criou, do mais recente para o mais antigo, inclusive os revogados. Filtros: externalId (igualdade), q (começo do externalId) e status (open, used, expired ou revoked). Autenticação: Chave de API. Escopo exigido: `numbers:read` Guia do tema: https://lunahia.com.br/docs/saas-com-n-clientes#rota-get-v1-onboarding-links #### Parâmetros de consulta | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `q` | `string` | não | O começo do rótulo do seu cliente: os links cujo externalId começa com este texto, sem diferenciar maiúscula. Use no lugar de externalId quando você só lembra do começo. Combina com os outros filtros. | | `externalId` | `string` | não | O rótulo que você deu ao seu cliente (externalId): só os links dele. Igualdade exata; um rótulo sem link devolve lista vazia. | | `status` | `string` | não | Só os links neste estado: open, used, expired ou revoked. | | `limit` | `integer` | não | | | `cursor` | `string` | não | | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/onboarding/links" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "data": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "externalId": "YOUR_EXTERNALID", "status": "open", "createdAt": "YOUR_CREATEDAT", "purpose": "new", "revokedAt": "YOUR_REVOKEDAT", "lastFailure": { "step": "YOUR_STEP", "reason": "YOUR_REASON", "at": "YOUR_AT" }, "allowedActions": [ "revoke" ], "expiresAt": "YOUR_EXPIRESAT", "usedAt": "YOUR_USEDAT", "redirectUrl": "YOUR_REDIRECTURL", "displayName": "YOUR_DISPLAYNAME", "numberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ], "nextCursor": "YOUR_NEXTCURSOR" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Criar um link de conexão para o seu cliente `POST /v1/onboarding/links` Cria um link que o seu cliente abre para conectar o número de WhatsApp dele, sem receber o login do seu console. Autenticação: Chave de API. Escopo exigido: `onboarding:write` Guia do tema: https://lunahia.com.br/docs/saas-com-n-clientes#rota-post-v1-onboarding-links #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `externalId` | `string` | não | O seu identificador para este cliente, em texto livre de 1 a 128 caracteres. A Luna não o interpreta: ele volta como externalId no link e no número que resultar da conexão. · 1 a 128 caracteres | | `displayName` | `string` | não | O nome do seu cliente, em texto livre de 1 a 120 caracteres, que a página do link mostra ("Conectar o WhatsApp de ..."). Serve para o cliente reconhecer de quem é o pedido. É só texto da página: a janela da Meta que abre em seguida mostra o nome da Luna e não pode ser mudada. · 1 a 120 caracteres | | `redirectUrl` | `string` | não | Para onde a página do link leva o seu cliente quando a conexão termina (https, até 2048 caracteres). A página acrescenta status (o estado final da conexão) e numberId (o número, quando a Luna já o registrou) na query. Ausente, o cliente fica na página da Luna. · até 2048 caracteres · /^https:\/\/[^\s]+$/ | | `numberId` | `string` | não | O número a reconectar: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Com ele, o link abre a reconexão daquele número em vez de uma conexão nova. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/onboarding/links" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "externalId": "YOUR_EXTERNALID", "displayName": "YOUR_DISPLAYNAME", "redirectUrl": "YOUR_REDIRECTURL" }' ``` #### Respostas **201**: Criado. ```json { "id": "5b8a0e0e-9a1f-4d1c-8d27-2f0c5f3a7d10", "url": "https://app.lunahia.com.br/conectar/0f2c8e6a-1d3b-4a5c-9e7f-2b4d6a8c0e12.k3JrYq1w2hX9s0Zt4uVb7nLmP5dQe8aRfG6yTcIoWxU", "expiresAt": "2026-10-10T14:00:00.000Z", "externalId": "cliente-8841", "redirectUrl": "https://app.exemplo.com.br/whatsapp/conectado", "displayName": "Escritório Silva & Filhos" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "number_capacity_reached", "message": "Esta conta já tem 20 números ativos, o máximo contratado (20). Para conectar outro, desconecte um número (DELETE /v1/numbers/{id}) ou escreva para contato@lunahia.com.br.", "capacity": 20, "activeNumbers": 20 } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Consultar um link de conexão `GET /v1/onboarding/links/{id}` O estado de um link: open, used, expired ou revoked, com a finalidade, a última falha e o que a conta pode fazer com ele. Autenticação: Chave de API. Escopo exigido: `numbers:read` Guia do tema: https://lunahia.com.br/docs/saas-com-n-clientes#rota-get-v1-onboarding-links-id #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/onboarding/links/YOUR_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "externalId": "YOUR_EXTERNALID", "status": "open", "createdAt": "YOUR_CREATEDAT", "purpose": "new", "revokedAt": "YOUR_REVOKEDAT", "lastFailure": { "step": "YOUR_STEP", "reason": "YOUR_REASON", "at": "YOUR_AT" }, "allowedActions": [ "revoke" ], "expiresAt": "YOUR_EXPIRESAT", "usedAt": "YOUR_USEDAT", "redirectUrl": "YOUR_REDIRECTURL", "displayName": "YOUR_DISPLAYNAME", "numberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Revogar um link de conexão `DELETE /v1/onboarding/links/{id}` Revoga o link. A url deixa de funcionar na hora e passa a responder 404 a quem a abrir, como uma que nunca existiu. Uma conexão que o cliente já tinha começado na janela da Meta não pode mais ser concluída por ela. O link continua na sua lista, com status revoked e revokedAt. Revogar de novo um link já revogado responde 404. Autenticação: Chave de API. Escopo exigido: `onboarding:write` Guia do tema: https://lunahia.com.br/docs/saas-com-n-clientes#rota-delete-v1-onboarding-links-id #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | | #### Exemplos de código ```bash curl -X DELETE "https://api.lunahia.com.br/v1/onboarding/links/YOUR_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo. **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Criar vários links de conexão de uma vez `POST /v1/onboarding/links/batch` Cria até 100 links, cada item no mesmo formato de POST /v1/onboarding/links e com as mesmas regras, inclusive a capacidade do plano. Responde 200 com um resultado por item, com a url de cada link criado; um item que falha não derruba os outros. Autenticação: Chave de API. Escopo exigido: `onboarding:write` #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `links` | `array` | sim | De 1 a 100 links, cada um no mesmo formato do corpo de POST /v1/onboarding/links: externalId, displayName, redirectUrl e numberId, todos opcionais. · 1 a 100 itens | | `links[].externalId` | `string` | não | O seu identificador para este cliente, em texto livre de 1 a 128 caracteres. A Luna não o interpreta: ele volta como externalId no link e no número que resultar da conexão. · 1 a 128 caracteres | | `links[].displayName` | `string` | não | O nome do seu cliente, em texto livre de 1 a 120 caracteres, que a página do link mostra ("Conectar o WhatsApp de ..."). Serve para o cliente reconhecer de quem é o pedido. É só texto da página: a janela da Meta que abre em seguida mostra o nome da Luna e não pode ser mudada. · 1 a 120 caracteres | | `links[].redirectUrl` | `string` | não | Para onde a página do link leva o seu cliente quando a conexão termina (https, até 2048 caracteres). A página acrescenta status (o estado final da conexão) e numberId (o número, quando a Luna já o registrou) na query. Ausente, o cliente fica na página da Luna. · até 2048 caracteres · /^https:\/\/[^\s]+$/ | | `links[].numberId` | `string` | não | O número a reconectar: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Com ele, o link abre a reconexão daquele número em vez de uma conexão nova. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/onboarding/links/batch" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "links": [ { "externalId": "YOUR_EXTERNALID", "displayName": "YOUR_DISPLAYNAME", "redirectUrl": "YOUR_REDIRECTURL" } ] }' ``` #### Respostas **200**: Sucesso. ```json { "results": [ { "index": 1, "status": 1, "link": { "id": "5b8a0e0e-9a1f-4d1c-8d27-2f0c5f3a7d10", "url": "https://app.lunahia.com.br/conectar/0f2c8e6a-1d3b-4a5c-9e7f-2b4d6a8c0e12.k3JrYq1w2hX9s0Zt4uVb7nLmP5dQe8aRfG6yTcIoWxU", "expiresAt": "2026-10-10T14:00:00.000Z", "externalId": "cliente-8841", "redirectUrl": "https://app.exemplo.com.br/whatsapp/conectado", "displayName": "Escritório Silva & Filhos" }, "error": { "error": "YOUR_ERROR", "message": "YOUR_MESSAGE" } } ] } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Gerar de novo a url de um link de conexão `POST /v1/onboarding/links/{id}/reissue` Gera um token novo para o mesmo link (mesmo id, mesmo rótulo, mesmo prazo): a url antiga deixa de funcionar na hora e a nova aparece só nesta resposta. Só vale para um link aberto; usado, vencido ou revogado responde 409. Use quando o seu cliente perdeu a url, em vez de revogar e criar outro. Autenticação: Chave de API. Escopo exigido: `onboarding:write` #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/onboarding/links/YOUR_ID/reissue" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "id": "5b8a0e0e-9a1f-4d1c-8d27-2f0c5f3a7d10", "url": "https://app.lunahia.com.br/conectar/0f2c8e6a-1d3b-4a5c-9e7f-2b4d6a8c0e12.k3JrYq1w2hX9s0Zt4uVb7nLmP5dQe8aRfG6yTcIoWxU", "expiresAt": "2026-10-10T14:00:00.000Z", "externalId": "cliente-8841", "redirectUrl": "https://app.exemplo.com.br/whatsapp/conectado", "displayName": "Escritório Silva & Filhos" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "link_not_open", "docsUrl": "https://lunahia.com.br/docs/conectar-numero", "message": "Só um link aberto pode ser reemitido, e este está usado. Crie um link novo com POST /v1/onboarding/links.", "status": "used" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ## Webhooks e eventos Para onde a Luna entrega o que chega no seu número, o segredo que assina essas entregas e os tipos de evento, cada um com o esquema e um exemplo. ### Listar os endpoints de webhook `GET /v1/webhooks/endpoints` Os endpoints cadastrados neste cliente, do mais recente para o mais antigo, com o limite de endpoints e se ainda dá para cadastrar outro (limit e canCreate). Cada endpoint traz deliveryStatus. Autenticação: Chave de API. Escopo exigido: `webhooks:read` Guia do tema: https://lunahia.com.br/docs/receber-eventos#rota-get-v1-webhooks-endpoints #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/webhooks/endpoints" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Os endpoints cadastrados neste cliente, do mais recente para o mais antigo, com o limite de endpoints e se ainda dá para cadastrar outro (limit e canCreate). ```json { "data": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "url": "https://exemplo.com.br/arquivo", "createdAt": "YOUR_CREATEDAT", "updatedAt": "YOUR_UPDATEDAT", "previousSecretExpiresAt": "YOUR_PREVIOUSSECRETEXPIRESAT", "paused": true, "pausedAt": "YOUR_PAUSEDAT", "eventTypes": [ "YOUR_EVENTTYPES" ], "externalIds": [ "YOUR_EXTERNALIDS" ], "phoneNumberIds": [ "YOUR_PHONENUMBERIDS" ], "headerNames": [ "YOUR_HEADERNAMES" ], "lastDeliveryAt": "YOUR_LASTDELIVERYAT", "lastFailureAt": "YOUR_LASTFAILUREAT", "lastHttpStatus": 1, "deliveryStatus": "ok" } ], "limit": 1, "canCreate": true } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Cadastrar o endpoint de webhook `POST /v1/webhooks/endpoints` Registra a URL do seu servidor e devolve o segredo que assina as entregas. headers, opcional, leva até 5 cabeçalhos HTTP próprios que a Luna envia em cada entrega (para um gateway que exige um token fixo); os valores são segredo e nenhuma resposta os devolve. Autenticação: Chave de API. Escopo exigido: `webhooks:write` Guia do tema: https://lunahia.com.br/docs/receber-eventos#rota-post-v1-webhooks-endpoints #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `url` | `string` | sim | A URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público. · até 2048 caracteres | | `eventTypes` | `array` | não | Os tipos de evento que este endpoint recebe, por exemplo ["message.received", "message.status"]. Ausente ou vazio quer dizer todos, inclusive os tipos que a Luna criar depois. Com a lista preenchida, o endpoint só recebe esses tipos, e um tipo novo não chega até você incluí-lo. O filtro é só por tipo. O evento webhook.test não é filtrável: ele só sai quando você o pede. Os tipos estão no guia Receber eventos. · até 30 itens | | `externalIds` | `array` | não | Os clientes seus (externalId) de que este endpoint recebe eventos, por exemplo ["cliente-42"]. Ausente ou vazio quer dizer todos. Com a lista preenchida, o endpoint só recebe eventos de números com um destes externalId, inclusive os conectados depois, e dos links de conexão com ele. Eventos que não falam de um cliente (os de template, por exemplo) só chegam se a conta do template tem um número dele. O filtro é só por identificador. · até 100 itens | | `phoneNumberIds` | `array` | não | Os números de que este endpoint recebe eventos: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId), em qualquer mistura. A resposta devolve os ids da Meta, os mesmos que os eventos trazem em phone_number_id. Ausente ou vazio quer dizer todos. Um número que não é da conta responde 400. Para cobrir números que ainda serão conectados, use externalIds. · até 100 itens | | `headers` | `object` | não | Cabeçalhos HTTP que a Luna envia em cada entrega a este endpoint, como { "X-Token": "valor" }, até 5. Para quem tem um gateway que exige um token fixo. Os valores são segredo: ficam cifrados, e nenhuma resposta os devolve, só os nomes (headerNames). Não valem os de transporte (content-type, host, content-length e afins) nem os x-luna-*. O valor tem até 1024 caracteres ASCII visíveis. No PATCH, o objeto enviado substitui o anterior, e {} remove todos. | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/webhooks/endpoints" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://exemplo.com.br/arquivo" }' ``` #### Respostas **201**: O endpoint recém-criado, com o segredo de assinatura. ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "url": "https://exemplo.com.br/arquivo", "createdAt": "YOUR_CREATEDAT", "updatedAt": "YOUR_UPDATEDAT", "previousSecretExpiresAt": "YOUR_PREVIOUSSECRETEXPIRESAT", "paused": true, "pausedAt": "YOUR_PAUSEDAT", "eventTypes": [ "YOUR_EVENTTYPES" ], "externalIds": [ "YOUR_EXTERNALIDS" ], "phoneNumberIds": [ "YOUR_PHONENUMBERIDS" ], "headerNames": [ "YOUR_HEADERNAMES" ], "lastDeliveryAt": "YOUR_LASTDELIVERYAT", "lastFailureAt": "YOUR_LASTFAILUREAT", "lastHttpStatus": 1, "deliveryStatus": "ok", "secret": "YOUR_SECRET" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "webhook_endpoint_limit", "docsUrl": "https://lunahia.com.br/docs/receber-eventos", "message": "Este cliente já tem o máximo de endpoints de webhook, e o limite é o mesmo para todos. Remova um endpoint com DELETE /v1/webhooks/endpoints/{id} para liberar a vaga.", "limit": 25 } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Listar os tipos de evento `GET /v1/webhooks/event-types` Os tipos de evento que a Luna entrega, e que eventTypes aceita no cadastro e na alteração do endpoint. Cada item traz o type, que é o valor a enviar, uma frase que diz o que o evento é e o grupo a que pertence (group e groupLabel). Autenticação: Chave de API. Escopo exigido: `webhooks:read` Guia do tema: https://lunahia.com.br/docs/receber-eventos#rota-get-v1-webhooks-event-types #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/webhooks/event-types" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Os tipos de evento que a Luna entrega, na ordem do contrato. O evento webhook.test não está na lista: ele só sai quando você o pede. ```json { "data": [ { "type": "YOUR_TYPE", "summary": "YOUR_SUMMARY", "group": "messages", "groupLabel": "YOUR_GROUPLABEL" } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Consultar o endpoint de webhook `GET /v1/webhooks/endpoints/{id}` A configuração do endpoint. Autenticação: Chave de API. Escopo exigido: `webhooks:read` Guia do tema: https://lunahia.com.br/docs/receber-eventos#rota-get-v1-webhooks-endpoints-id #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador do endpoint, devolvido no cadastro. | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: A configuração do endpoint. O segredo NÃO vem aqui: ele sai uma vez, no cadastro e na rotação. ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "url": "https://exemplo.com.br/arquivo", "createdAt": "YOUR_CREATEDAT", "updatedAt": "YOUR_UPDATEDAT", "previousSecretExpiresAt": "YOUR_PREVIOUSSECRETEXPIRESAT", "paused": true, "pausedAt": "YOUR_PAUSEDAT", "eventTypes": [ "YOUR_EVENTTYPES" ], "externalIds": [ "YOUR_EXTERNALIDS" ], "phoneNumberIds": [ "YOUR_PHONENUMBERIDS" ], "headerNames": [ "YOUR_HEADERNAMES" ], "lastDeliveryAt": "YOUR_LASTDELIVERYAT", "lastFailureAt": "YOUR_LASTFAILUREAT", "lastHttpStatus": 1, "deliveryStatus": "ok" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Alterar o endpoint de webhook `PATCH /v1/webhooks/endpoints/{id}` Muda a URL, pausa ou retoma o endpoint, ou troca os tipos de evento que ele recebe. Envie url, paused, eventTypes, externalIds, phoneNumberIds, headers ou qualquer combinação: um corpo sem nenhum deles responde 400. Autenticação: Chave de API. Escopo exigido: `webhooks:write` Guia do tema: https://lunahia.com.br/docs/receber-eventos#rota-patch-v1-webhooks-endpoints-id #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador do endpoint, devolvido no cadastro. | #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `url` | `string` | não | A URL nova. Passa pela mesma validação do cadastro: https e endereço público. O segredo de assinatura continua o mesmo. · até 2048 caracteres | | `paused` | `boolean` | não | true pausa o endpoint: os eventos que ocorrerem enquanto ele estiver pausado não são entregues, nem depois. false o retoma, e ele passa a receber os eventos a partir desse momento. | | `eventTypes` | `array` | não | Troca a lista de tipos que o endpoint recebe: a lista enviada substitui a anterior. Lista vazia volta a receber todos. O que ocorreu antes da troca e foi filtrado não é entregue depois. · até 30 itens | | `externalIds` | `array` | não | Troca a lista de clientes de que o endpoint recebe eventos: a lista enviada substitui a anterior, e lista vazia volta a receber de todos. Vale daí em diante. · até 100 itens | | `phoneNumberIds` | `array` | não | Troca a lista de números de que o endpoint recebe eventos: a lista enviada substitui a anterior, e lista vazia volta a receber de todos. Aceita o UUID da Luna ou o id da Meta. · até 100 itens | | `headers` | `object` | não | Cabeçalhos HTTP que a Luna envia em cada entrega a este endpoint, como { "X-Token": "valor" }, até 5. Para quem tem um gateway que exige um token fixo. Os valores são segredo: ficam cifrados, e nenhuma resposta os devolve, só os nomes (headerNames). Não valem os de transporte (content-type, host, content-length e afins) nem os x-luna-*. O valor tem até 1024 caracteres ASCII visíveis. No PATCH, o objeto enviado substitui o anterior, e {} remove todos. | #### Exemplos de código ```bash curl -X PATCH "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://exemplo.com.br/arquivo", "paused": true, "eventTypes": [ "message.received" ] }' ``` #### Respostas **200**: A configuração do endpoint. O segredo NÃO vem aqui: ele sai uma vez, no cadastro e na rotação. ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "url": "https://exemplo.com.br/arquivo", "createdAt": "YOUR_CREATEDAT", "updatedAt": "YOUR_UPDATEDAT", "previousSecretExpiresAt": "YOUR_PREVIOUSSECRETEXPIRESAT", "paused": true, "pausedAt": "YOUR_PAUSEDAT", "eventTypes": [ "YOUR_EVENTTYPES" ], "externalIds": [ "YOUR_EXTERNALIDS" ], "phoneNumberIds": [ "YOUR_PHONENUMBERIDS" ], "headerNames": [ "YOUR_HEADERNAMES" ], "lastDeliveryAt": "YOUR_LASTDELIVERYAT", "lastFailureAt": "YOUR_LASTFAILUREAT", "lastHttpStatus": 1, "deliveryStatus": "ok" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Remover o endpoint de webhook `DELETE /v1/webhooks/endpoints/{id}` Remove o endpoint. A resposta é 204, e o endpoint deixa de receber eventos. Autenticação: Chave de API. Escopo exigido: `webhooks:write` Guia do tema: https://lunahia.com.br/docs/receber-eventos#rota-delete-v1-webhooks-endpoints-id #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador do endpoint, devolvido no cadastro. | #### Exemplos de código ```bash curl -X DELETE "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo. **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Listar as entregas do endpoint `GET /v1/webhooks/endpoints/{id}/deliveries` O histórico das tentativas de entrega ao endpoint nos últimos 7 dias, da mais recente à mais antiga: eventId, eventType, status, httpStatus (nulo quando o seu servidor não respondeu), durationMs, attempt e at. Filtros: status (success ou failed), eventType e since. Não traz o corpo enviado nem o que o seu servidor respondeu. Autenticação: Chave de API. Escopo exigido: `webhooks:read` Guia do tema: https://lunahia.com.br/docs/receber-eventos#rota-get-v1-webhooks-endpoints-id-deliveries #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador do endpoint, devolvido no cadastro. | #### Parâmetros de consulta | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `limit` | `integer` | não | Quantos itens trazer. Padrão 50, máximo 100, igual para todos. | | `status` | `string` | não | success: só as tentativas que o seu servidor aceitou (2xx). failed: só as que falharam, com outro status ou sem resposta. | | `eventType` | `string` | não | Só as tentativas de eventos deste tipo (um valor de GET /v1/webhooks/event-types). | | `since` | `any` | não | Só as tentativas deste instante em diante (ISO 8601, ou a data pura, que vale meia-noite UTC). O histórico guarda 7 dias. | | `cursor` | `string` | não | O nextCursor da página anterior. Omita na primeira. | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ID/deliveries" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: O histórico de entregas do endpoint nos últimos 7 dias, uma linha por tentativa. Não traz o corpo enviado nem o que o seu servidor respondeu: só o status. ```json { "data": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "eventId": "YOUR_EVENTID", "eventType": "YOUR_EVENTTYPE", "status": "success", "httpStatus": 1, "durationMs": 1, "attempt": 1, "at": "YOUR_AT" } ], "nextCursor": "YOUR_NEXTCURSOR" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Enviar um evento de teste `POST /v1/webhooks/endpoints/{id}/test` Envia UM evento webhook.test ao endpoint, agora, e devolve o resultado na própria resposta. O evento sai assinado, com os mesmos cabeçalhos, a mesma assinatura e as mesmas defesas de destino de uma entrega real, então um teste que passa prova que a URL e a verificação da assinatura funcionam. Com eventType no corpo, o evento é um exemplo daquele tipo, com corpo de mentira e test: true no envelope. Autenticação: Chave de API. Escopo exigido: `webhooks:write` Guia do tema: https://lunahia.com.br/docs/receber-eventos#rota-post-v1-webhooks-endpoints-id-test #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador do endpoint, devolvido no cadastro. | #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `eventType` | `string` | não | Um tipo de GET /v1/webhooks/event-types. A Luna entrega ao endpoint um exemplo desse tipo, com corpo de mentira (identificadores que não existem) e test: true no envelope, para você exercitar o seu código sem esperar o evento de verdade. Ausente, o teste é o webhook.test de sempre. O exemplo não passa por nenhum número seu. · Valores: message.received, message.status, contact.identity_changed, contact.preferences_changed, backlog.dropped, history_sync.deadline_approaching, message.echo, template.status, number.connected, number.payment_required, number.payment_resolved, account.restricted, account.violation, account.disabled, account.reinstated, account.update, account.limit_changed, number.disconnected, number.quality_changed, number.display_name_reviewed, number.credential_expiring, account.alert, number.action_required, number.action_resolved, onboarding.link.completed, onboarding.link.opened, onboarding.link.failed, onboarding.link.expired, template.category, template.quality | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ID/test" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "eventType": "message.received" }' ``` #### Respostas **200**: O resultado do evento de teste. O corpo que o seu servidor respondeu não volta aqui, de propósito. ```json { "delivered": true, "statusCode": 1, "durationMs": 1, "failure": "timeout" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Rotacionar o segredo de assinatura `POST /v1/webhooks/endpoints/{id}/rotacionar` Emite um segredo novo e devolve ele uma vez. Guarde-o agora, como no cadastro. Autenticação: Chave de API. Escopo exigido: `webhooks:write` Guia do tema: https://lunahia.com.br/docs/receber-eventos#rota-post-v1-webhooks-endpoints-id-rotacionar #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador do endpoint, devolvido no cadastro. | #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `revokePrevious` | `boolean` | não | Com true, o segredo anterior deixa de valer no mesmo instante, em vez de seguir válido por sete dias. Use quando o segredo anterior vazou. As entregas que já saíram assinadas só com ele falham na verificação do seu lado. | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ID/rotacionar" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "revokePrevious": true }' ``` #### Respostas **200**: O endpoint com o segredo novo. O anterior continua válido até previousSecretExpiresAt, então você pode trocar a configuração do seu lado sem pressa e sem perder entrega. ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "url": "https://exemplo.com.br/arquivo", "createdAt": "YOUR_CREATEDAT", "updatedAt": "YOUR_UPDATEDAT", "previousSecretExpiresAt": "YOUR_PREVIOUSSECRETEXPIRESAT", "paused": true, "pausedAt": "YOUR_PAUSEDAT", "eventTypes": [ "YOUR_EVENTTYPES" ], "externalIds": [ "YOUR_EXTERNALIDS" ], "phoneNumberIds": [ "YOUR_PHONENUMBERIDS" ], "headerNames": [ "YOUR_HEADERNAMES" ], "lastDeliveryAt": "YOUR_LASTDELIVERYAT", "lastFailureAt": "YOUR_LASTFAILUREAT", "lastHttpStatus": 1, "deliveryStatus": "ok", "secret": "YOUR_SECRET" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Listar as entregas que falharam definitivamente `GET /v1/webhooks/dlq` Os eventos que a Luna tentou entregar ao seu endpoint e desistiu, do mais recente ao mais antigo, cada um com o número, o rótulo do cliente, as tentativas, o último status HTTP e o que se pode fazer com ele (allowedActions). Filtros: endpointId, externalId e requeued. Autenticação: Chave de API. Escopo exigido: `webhooks:read` Guia do tema: https://lunahia.com.br/docs/receber-eventos#rota-get-v1-webhooks-dlq #### Parâmetros de consulta | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `cursor` | `string` | não | O cursor devolvido em nextCursor pela chamada anterior. Omita na primeira página. | | `limit` | `integer` | não | Quantos itens trazer nesta página. Máximo 100, igual para todos. | | `endpointId` | `string` | não | Só os itens deste endpoint. | | `externalId` | `string` | não | Só os itens dos números deste cliente seu (externalId do número). Igualdade exata; um rótulo sem item devolve lista vazia. | | `requeued` | `string` | não | true: só os já re-enfileirados. false: só os que ainda podem ser (os que têm requeue em allowedActions). | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/webhooks/dlq" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Uma página da fila de rejeitados. Sem total e sem contagem: a Luna não soma entregas, e nenhum número desta resposta alimenta cobrança. attempts e lastHttpStatus descrevem UMA entrega que falhou, e não um agregado. ```json { "items": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "endpointId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "eventType": "message.received", "wamid": "YOUR_WAMID", "rejectedAt": "YOUR_REJECTEDAT", "failureReason": "http_4xx", "requeuedAt": "YOUR_REQUEUEDAT", "numberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "externalId": "YOUR_EXTERNALID", "attempts": 1, "lastHttpStatus": 1, "allowedActions": [ "requeue" ] } ], "nextCursor": "YOUR_NEXTCURSOR" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Re-enfileirar uma entrega que falhou `POST /v1/webhooks/dlq/{id}/reenfileirar` Recoloca o evento na fila de entrega. A resposta é 202: o pedido foi registrado, e a entrega acontece de forma assíncrona. Autenticação: Chave de API. Escopo exigido: `webhooks:write` Guia do tema: https://lunahia.com.br/docs/receber-eventos#rota-post-v1-webhooks-dlq-id-reenfileirar #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | O identificador deste item na fila de rejeitados. | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/webhooks/dlq/YOUR_ID/reenfileirar" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **202**: O item foi recolocado na fila de entrega. A entrega em si é assíncrona, como qualquer outra: se o seu endpoint ainda estiver fora do ar, ela será adiada e retentada pela mesma política de sempre. ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "requeuedAt": "YOUR_REQUEUEDAT" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "already_requeued", "docsUrl": "https://lunahia.com.br/docs/receber-eventos", "message": "Este item já foi re-enfileirado.", "reenfileiradoEm": "2026-10-06T12:00:00.000Z" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ## Chaves Criar, listar e revogar as credenciais que autenticam as suas chamadas. ### Listar chaves `GET /v1/api-keys` As chaves deste cliente, com escopos, perfil, status (active, revoked ou expired), data de criação, último uso, revogação e o que a conta pode fazer com cada uma (allowedActions). Autenticação: Chave de API. Escopo exigido: `keys:read` Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-get-v1-api-keys #### Parâmetros de consulta | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `kind` | `string` | não | | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/api-keys" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json [ { "id": "7d1f4c02-9a3b-4e51-8c7d-2f0b6a91e334", "label": "integração de produção", "kind": "integration", "scopes": [ "messages:write", "messages:read", "numbers:read" ], "mode": "live", "externalId": null, "createdAt": "2026-08-07T12:10:44.201Z", "expiresAt": null, "revokedAt": null, "lastUsedAt": "2026-08-10T09:02:18.664Z", "status": "active", "profile": "agent", "allowedActions": [ "revoke" ] } ] ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Criar uma chave `POST /v1/api-keys` Cunha uma chave nova e devolve o segredo uma única vez. Guarde-o no momento em que recebe, porque não há rota que o devolva depois. Autenticação: Chave de API. Escopo exigido: `keys:write` Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-api-keys #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `label` | `string` | não | 1 a 120 caracteres | | `scopes` | `array` | não | O que a chave pode fazer, escopo por escopo. Mande scopes ou profile, e nunca os dois: a lista de escopos que cada perfil concede está em GET /v1/api-keys/profiles. · no mínimo 1 itens | | `profile` | `string` | não | Um perfil pronto no lugar de scopes: agent (atendimento), full (integração completa) ou read_only (somente leitura). A chave nasce com os escopos que o perfil concede no momento da criação, e a lista deles está em GET /v1/api-keys/profiles. · Valores: agent, full, read_only | | `expiresAt` | `string (date-time)` | não | | | `mode` | `string` | não | live (o padrão) é a chave de sempre. test cria uma chave do modo de teste: POST /v1/messages com ela NÃO vai à Meta, não usa número seu e não conta na capacidade do plano; a Luna devolve ao seu webhook eventos simulados, assinados e com test: true. Uma chave de teste só usa POST /v1/messages e POST /v1/test-mode/inbound-messages, e não aceita externalId. Não dá para mudar depois: crie outra. · Valores: live, test | | `externalId` | `string` | não | O seu identificador para o cliente a que esta chave pertence (1 a 128 caracteres), o mesmo externalId do link de conexão e dos números. Com ele, a chave é de UM cliente seu: só lê e envia pelos números com este externalId (inclusive os conectados depois), só cria link com ele, e não lista nem cria endpoints de webhook nem chaves. Sem ele, a chave é da conta inteira. Não dá para mudar depois: crie outra. · 1 a 128 caracteres | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/api-keys" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "label": "YOUR_LABEL", "scopes": [ "keys:read" ], "profile": "agent" }' ``` #### Respostas **201**: Criado. ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "label": "YOUR_LABEL", "kind": "integration", "scopes": [ "YOUR_SCOPES" ], "mode": "live", "externalId": "YOUR_EXTERNALID", "createdAt": "YOUR_CREATEDAT", "expiresAt": "YOUR_EXPIRESAT", "revokedAt": "YOUR_REVOKEDAT", "lastUsedAt": "YOUR_LASTUSEDAT", "status": "active", "profile": "agent", "allowedActions": [ "revoke" ], "secret": "YOUR_SECRET" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Listar os escopos que uma chave pode ter `GET /v1/api-keys/scopes` Os escopos que uma chave de integração pode receber, cada um com o nome em português, o que ele permite e se dá um poder que exige cuidado. Autenticação: Chave de API. Escopo exigido: `keys:read` #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/api-keys/scopes" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "data": [ { "scope": "messages:write", "label": "Enviar mensagens", "summary": "Envia mensagens e templates pelos números conectados.", "sensitive": false }, { "scope": "keys:write", "label": "Criar e revogar chaves", "summary": "Permite que esta chave crie outras chaves, sem prazo. Dê só a quem precisa.", "sensitive": true } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Listar os perfis de chave `GET /v1/api-keys/profiles` Os perfis prontos de chave (agent, full e read_only) e os escopos que cada um concede. Em POST /v1/api-keys, profile vale no lugar de scopes. Autenticação: Chave de API. Escopo exigido: `keys:read` #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/api-keys/profiles" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "data": [ { "id": "read_only", "label": "Somente leitura", "summary": "Consulta tudo e não altera nada.", "scopes": [ "keys:read", "numbers:read", "messages:read", "templates:read", "webhooks:read" ] } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Consultar uma chave `GET /v1/api-keys/{id}` Os metadados de uma chave. O segredo não volta, pelo mesmo motivo descrito na listagem. Autenticação: Chave de API. Escopo exigido: `keys:read` #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/api-keys/YOUR_ID" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "id": "7d1f4c02-9a3b-4e51-8c7d-2f0b6a91e334", "label": "integração de produção", "kind": "integration", "scopes": [ "messages:write", "messages:read", "numbers:read" ], "mode": "live", "externalId": null, "createdAt": "2026-08-07T12:10:44.201Z", "expiresAt": null, "revokedAt": null, "lastUsedAt": "2026-08-10T09:02:18.664Z", "status": "active", "profile": "agent", "allowedActions": [ "revoke" ] } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Revogar uma chave `POST /v1/api-keys/{id}/revoke` Invalida a chave imediatamente. A operação é idempotente, então revogar de novo devolve o mesmo resultado, sem erro. Autenticação: Chave de API. Escopo exigido: `keys:write` Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-api-keys-id-revoke #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | `string` | sim | | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/api-keys/YOUR_ID/revoke" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "id": "7d1f4c02-9a3b-4e51-8c7d-2f0b6a91e334", "label": "integração de produção", "kind": "integration", "scopes": [ "messages:write", "messages:read", "numbers:read" ], "mode": "live", "externalId": null, "createdAt": "2026-08-07T12:10:44.201Z", "expiresAt": null, "revokedAt": null, "lastUsedAt": "2026-08-10T09:02:18.664Z", "status": "active", "profile": "agent", "allowedActions": [ "revoke" ] } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ## Conta e plano A conta da credencial, o plano, a capacidade de números e quantos estão em uso no período. ### Consultar o plano e a assinatura `GET /v1/subscription` O plano da conta (teste grátis ou contratado), a capacidade de números e quantos estão em uso, e o que é cobrado pela Helsen no período: a capacidade de números ativos, e nada além disso. Autenticação: Chave de API. Escopo exigido: `numbers:read` Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-get-v1-subscription #### Parâmetros de consulta | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `inicio` | `string` | não | | | `fim` | `string` | não | | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/subscription" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "planName": "Growth", "status": "trial", "suspendedReason": null, "capacity": 20, "activeNumbers": 3, "trialEndsAt": "2026-11-03T13:00:00.000Z", "trialDaysLeft": 5, "periodo": { "inicio": "2026-03-01T00:00:00.000Z", "fim": "2026-04-01T00:00:00.000Z" }, "canConnectNumber": true, "capacityLeft": 17, "capacityNotice": null, "writesAllowed": true, "suspendedNotice": null, "pricePerMonth": 990, "currency": "BRL", "contactEmail": "contato@lunahia.com.br", "numerosAtivos": 3, "phoneNumberIds": [ "15550001111", "15550002222" ] } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Ler os limites técnicos da plataforma `GET /v1/limits` Os tetos que a API aplica, cada um com o valor, a unidade e o motivo. São iguais para todos os clientes e não dependem do plano: existem por capacidade de infraestrutura ou porque a Meta os impõe. Não são contagem do seu uso e não entram em cobrança. Autenticação: Chave de API. Escopo exigido: `numbers:read` #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/limits" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "data": [ { "key": "webhook_endpoints", "label": "Endpoints de webhook por cliente", "value": 25, "unit": "endpoints", "reason": "Cada evento é entregue a cada endpoint que o aceita. Remover um endpoint libera a vaga." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Ler as regras de preço da Meta `GET /v1/meta-pricing` As regras com que a Meta cobra o uso do WhatsApp do negócio dono do número, e o dia em que a Luna as leu. Não traz valor em moeda: a tabela de tarifas fica na Meta. A Luna não cobra nada disto. Autenticação: Chave de API. Escopo exigido: `numbers:read` #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/meta-pricing" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "readAt": "2026-10-07", "sourceUrl": "https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing", "aiProvidersUrl": "https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing/ai-providers", "rules": [ { "key": "marketing_templates", "title": "Template de marketing", "text": "É sempre cobrado pela Meta, dentro ou fora da janela de 24 horas." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Ler a própria conta `GET /v1/account` Devolve a conta da credencial apresentada: identificador, nome, se o e-mail já foi confirmado e quando a conta foi criada. Autenticação: Chave de API. Escopo exigido: `numbers:read` Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-get-v1-account #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/account" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "YOUR_NAME", "emailConfirmed": true, "createdAt": "YOUR_CREATEDAT", "operatorEmail": "YOUR_OPERATOREMAIL" } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Trocar o nome da conta `PATCH /v1/account` Troca o nome da conta, o mesmo que GET /v1/account devolve. Devolve a conta já com o nome novo. Só a sessão do console faz isto. Autenticação: Chave de API. Escopo exigido: `session:end` #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `name` | `string` | sim | O novo nome da conta, de 1 a 120 caracteres: o mesmo limite do cadastro. · 1 a 120 caracteres | #### Exemplos de código ```bash curl -X PATCH "https://api.lunahia.com.br/v1/account" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "YOUR_NAME" }' ``` #### Respostas **200**: Sucesso. ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "YOUR_NAME", "emailConfirmed": true, "createdAt": "YOUR_CREATEDAT", "operatorEmail": "YOUR_OPERATOREMAIL" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Ver o resumo da conta `GET /v1/account/overview` O que a conta precisa olhar agora (avisos em ordem de gravidade), os quatro primeiros passos e os números por estado de conexão. Tudo decidido pela API, para uma tela inicial não precisar calcular nada. Autenticação: Chave de API. Escopo exigido: `numbers:read` #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/account/overview" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "attention": [ { "code": "number_credential_expiring", "severity": "warning", "title": "Autorização do cliente perto de vencer (+55 11 90000-0000)", "message": "A autorização que o seu cliente deu à Luna vence em até 14 dias. O número continua enviando até lá.", "solution": "Gere um link de reconexão com POST /v1/onboarding/links informando numberId e envie ao seu cliente.", "resource": { "type": "number", "id": "ed404df1-b420-4ed6-8743-ba1609892e0a" }, "action": "reconnect_link", "actionUrl": null, "since": "2026-10-25T12:00:00.000Z" } ], "checklist": [ { "key": "connect_number", "done": true, "doneAt": "2026-08-07T11:28:14.597Z" }, { "key": "create_key", "done": true, "doneAt": "2026-08-07T12:10:44.201Z" }, { "key": "add_webhook_endpoint", "done": true, "doneAt": "2026-08-08T09:00:00.000Z" }, { "key": "send_message", "done": false, "doneAt": null } ], "numbers": { "total": 1, "byStatus": { "connected": 1, "connecting": 0, "action_required": 0, "disconnected": 0 } } } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ## Status Sondas de disponibilidade e o estado da plataforma. Sem autenticação. ### Verificar se a API está no ar `GET /healthz` Responde 200 quando o processo está de pé. Não exige autenticação e não consulta banco nem fila, porque é sonda de processo e não de dependência. Um 200 aqui não promete que o envio de mensagem está funcionando. Autenticação: Pública, sem chave #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/healthz" ``` #### Respostas **200**: Sucesso. ### Ver se a Luna está recebendo e entregando `GET /status` Responde 200 com o estado da plataforma, medido a cada poucos minutos por uma mensagem sintética que entra pela mesma porta que a Meta usa e precisa chegar a um destino por HTTPS. Não exige autenticação e não revela dado de nenhuma conta. Quando ainda não há verificação recente, o estado é unknown, e nunca ok. Autenticação: Pública, sem chave #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/status" ``` #### Respostas **200**: Sucesso. ```json { "status": "ok", "checkedAt": "YOUR_CHECKEDAT", "components": { "ingestion": "ok", "delivery": "ok", "partitions": "ok" }, "since": "YOUR_SINCE" } ``` ### Apresentar a API `GET /` Responde 200 com o nome da API e os endereços da documentação e da especificação OpenAPI. Não exige autenticação e não consulta banco nem fila. Autenticação: Pública, sem chave #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/" ``` #### Respostas **200**: Sucesso. ```json { "name": "YOUR_NAME", "docs": "YOUR_DOCS", "openapi": "YOUR_OPENAPI" } ``` ## Console e páginas públicas Rotas que o console da Luna e a página pública do link de conexão usam: cadastro, login, sessão e conclusão do fluxo. Você normalmente não precisa delas. Elas existem aqui porque o console é cliente desta mesma API, sem rota privilegiada. ### Ler o link de conexão (página do cliente) `GET /v1/public/onboarding-links/{token}` Para a página que o seu cliente abre. Devolve o nome da conta que pediu a conexão, o status do link e os identificadores públicos do aplicativo da Meta que a janela de conexão usa. Nada mais da sua conta sai aqui. Autenticação: Pública, sem chave Guia do tema: https://lunahia.com.br/docs/saas-com-n-clientes#rota-get-v1-public-onboarding-links-token #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `token` | `string` | sim | | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/public/onboarding-links/YOUR_TOKEN" ``` #### Respostas **200**: Sucesso. ```json { "accountName": "YOUR_ACCOUNTNAME", "displayName": "YOUR_DISPLAYNAME", "status": "open", "expiresAt": "YOUR_EXPIRESAT", "metaAppId": "YOUR_METAAPPID", "metaConfigId": "YOUR_METACONFIGID", "sdkVersion": "YOUR_SDKVERSION", "redirectUrl": "YOUR_REDIRECTURL", "reconnect": true } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Abrir a sessão de conexão pelo link `POST /v1/public/onboarding-links/{token}/sessions` Abre a sessão que a janela da Meta preenche, para a conta dona do link. É a mesma abertura de POST /v1/onboarding/sessions, pela porta do token. Autenticação: Pública, sem chave Guia do tema: https://lunahia.com.br/docs/saas-com-n-clientes#rota-post-v1-public-onboarding-links-token-sessions #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `token` | `string` | sim | | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/public/onboarding-links/YOUR_TOKEN/sessions" ``` #### Respostas **201**: Criado. ```json { "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "state": "YOUR_STATE", "configId": "YOUR_CONFIGID", "sdkVersion": "YOUR_SDKVERSION", "csrfState": "YOUR_CSRFSTATE", "expiresAt": "YOUR_EXPIRESAT" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **409**: O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. ```json { "error": "account_at_capacity", "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros", "message": "A conta que pediu esta conexão atingiu o máximo de números. Avise quem enviou este link: assim que ela abrir uma vaga, ele poderá enviar um link novo." } ``` **410**: O link de conexão venceu ou já foi usado. O campo error diz qual dos dois. ```json { "error": "link_expired", "docsUrl": "https://lunahia.com.br/docs/conectar-numero", "message": "Este link venceu. Peça um novo a quem enviou este." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Concluir a conexão pelo link `POST /v1/public/onboarding-links/{token}/sessions/{sessionId}/complete` Troca o código da janela da Meta por acesso à conta do cliente. É a mesma conclusão de POST /v1/onboarding/sessions/{id}/complete, pela porta do token, e vale o mesmo aviso: o código dura 30 segundos, então chame no instante em que ele chega. Autenticação: Pública, sem chave Guia do tema: https://lunahia.com.br/docs/saas-com-n-clientes#rota-post-v1-public-onboarding-links-token-sessions-sessionid-complete #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `token` | `string` | sim | | | `sessionId` | `string` | sim | | #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `code` | `string` | sim | | | `csrfState` | `string` | sim | | | `wabaId` | `string \| null` | não | | | `phoneNumberId` | `string \| null` | não | | | `businessId` | `string \| null` | não | | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/public/onboarding-links/YOUR_TOKEN/sessions/YOUR_SESSION_ID/complete" \ -H "Content-Type: application/json" \ -d '{ "code": "YOUR_CODE", "csrfState": "YOUR_CSRFSTATE" }' ``` #### Respostas **200**: Sucesso. ```json { "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "state": "YOUR_STATE", "orientacao": "YOUR_ORIENTACAO", "terminal": true, "motivo": "YOUR_MOTIVO", "podeRetentar": true, "numberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "returnUrl": "YOUR_RETURNURL" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **410**: O link de conexão venceu ou já foi usado. O campo error diz qual dos dois. ```json { "error": "link_used", "docsUrl": "https://lunahia.com.br/docs/conectar-numero", "message": "Este link já foi usado. Se precisar conectar outro número, peça um novo a quem enviou este." } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Registrar abandono ou erro pelo link `POST /v1/public/onboarding-links/{token}/sessions/{sessionId}/abandon` Telemetria do que aconteceu na janela da Meta quando o cliente não concluiu. É o mesmo relato de POST /v1/onboarding/sessions/{id}/abandon, pela porta do token, e só vale para uma sessão aberta por este mesmo link. Autenticação: Pública, sem chave Guia do tema: https://lunahia.com.br/docs/saas-com-n-clientes#rota-post-v1-public-onboarding-links-token-sessions-sessionid-abandon #### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `token` | `string` | sim | | | `sessionId` | `string` | sim | | #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `csrfState` | `string` | sim | | | `currentStep` | `string \| null` | não | 1 a 120 caracteres | | `errorCode` | `integer \| null` | não | | | `errorMessage` | `string \| null` | não | | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/public/onboarding-links/YOUR_TOKEN/sessions/YOUR_SESSION_ID/abandon" \ -H "Content-Type: application/json" \ -d '{ "csrfState": "YOUR_CSRFSTATE" }' ``` #### Respostas **200**: Sucesso. ```json { "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "state": "YOUR_STATE", "orientacao": "YOUR_ORIENTACAO", "abandonedAtStep": "YOUR_ABANDONEDATSTEP" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **404**: O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. ```json { "error": "not_found", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Recurso não encontrado." } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Criar uma conta `POST /v1/operators/signup` Cria a conta e o primeiro operador dela, numa única chamada e sem credencial. Autenticação: Pública, sem chave Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-operators-signup #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `email` | `string` | sim | até 254 caracteres | | `password` | `string` | sim | 12 a 512 caracteres | | `tenantName` | `string` | sim | 1 a 120 caracteres | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/operators/signup" \ -H "Content-Type: application/json" \ -d '{ "email": "ana@suaempresa.com.br", "password": "YOUR_PASSWORD", "tenantName": "YOUR_TENANTNAME" }' ``` #### Respostas **201**: Criado. ```json { "nextStep": "login" } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Confirmar o e-mail de uma conta `GET /v1/operators/confirm` Destino do link enviado por e-mail quando a conta é criada. Ela responde com um redirecionamento para o console, e não com JSON, porque quem a abre é uma pessoa num navegador. Autenticação: Pública, sem chave Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-get-v1-operators-confirm #### Parâmetros de consulta | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `token` | `string` | não | | #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/operators/confirm" ``` #### Respostas **200**: Sucesso. **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Pedir a redefinição da senha `POST /v1/operators/password/forgot` Pede o envio de um link para escolher uma senha nova. Recebe só o e-mail da conta. Autenticação: Pública, sem chave Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-operators-password-forgot #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `email` | `string` | sim | até 254 caracteres | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/operators/password/forgot" \ -H "Content-Type: application/json" \ -d '{ "email": "ana@suaempresa.com.br" }' ``` #### Respostas **202**: Aceito: o pedido foi registrado e será processado. ```json { "accepted": true } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Escolher uma senha nova `POST /v1/operators/password/reset` Troca a senha do operador a partir do token do link enviado por e-mail, e responde 204. Autenticação: Pública, sem chave Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-operators-password-reset #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `token` | `string` | sim | até 512 caracteres | | `password` | `string` | sim | 12 a 512 caracteres | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/operators/password/reset" \ -H "Content-Type: application/json" \ -d '{ "token": "YOUR_TOKEN", "password": "YOUR_PASSWORD" }' ``` #### Respostas **204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo. **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Conferir o link de redefinição `POST /v1/operators/password/reset/check` Responde 204 quando o token do link ainda vale e 400 quando não vale, sem consumi-lo. Serve para a tela avisar antes de a pessoa digitar a senha nova. Autenticação: Pública, sem chave #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `token` | `string` | sim | até 512 caracteres | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/operators/password/reset/check" \ -H "Content-Type: application/json" \ -d '{ "token": "YOUR_TOKEN" }' ``` #### Respostas **204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo. **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Ler a regra de senha `GET /v1/public/password-policy` O comprimento mínimo de uma senha de operador, o mesmo no cadastro, na redefinição e na troca. Não pede credencial. Autenticação: Pública, sem chave #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/public/password-policy" ``` #### Respostas **200**: Sucesso. ```json { "minLength": 12 } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Trocar a senha `POST /v1/operators/password/change` Troca a senha do operador da sessão apresentada, conferindo a senha atual, e responde 204. As outras sessões do mesmo operador são encerradas e a apresentada continua valendo. Senha atual errada, ou credencial sem operador (chave de integração), responde 401. Autenticação: Chave de API. Escopo exigido: `session:elevate` #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `currentPassword` | `string` | sim | A senha de hoje do operador da sessão. · até 512 caracteres | | `newPassword` | `string` | sim | A senha nova, pela mesma regra do cadastro (GET /v1/public/password-policy diz o mínimo). · 12 a 512 caracteres | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/operators/password/change" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "currentPassword": "YOUR_CURRENTPASSWORD", "newPassword": "YOUR_NEWPASSWORD" }' ``` #### Respostas **204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo. **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Reenviar o e-mail de confirmação `POST /v1/operators/confirmation/resend` Envia de novo o link de confirmação para o e-mail do operador da sessão, e invalida o link anterior que ainda não tinha sido aberto. O link novo vale por sete dias e é aceito uma única vez. Autenticação: Chave de API. Escopo exigido: `session:end` Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-operators-confirmation-resend #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/operators/confirmation/resend" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **202**: Aceito: o pedido foi registrado e será processado. ```json { "emailConfirmed": true } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Autenticar um operador `POST /v1/operators/login` Troca email e senha por uma credencial de sessão de oito horas, usada pelo console web. Autenticação: Pública, sem chave Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-operators-login #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `email` | `string` | sim | 1 a 254 caracteres | | `password` | `string` | sim | 1 a 512 caracteres | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/operators/login" \ -H "Content-Type: application/json" \ -d '{ "email": "ana@suaempresa.com.br", "password": "YOUR_PASSWORD" }' ``` #### Respostas **200**: Sucesso. ```json { "tenantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "operatorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "token": "YOUR_TOKEN", "expiresAt": "YOUR_EXPIRESAT", "scopes": [ "YOUR_SCOPES" ] } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Reautenticar para uma ação sensível `POST /v1/operators/step-up` Confirma a senha do operador da sessão apresentada e abre uma janela de duas horas em que essa mesma sessão pode criar e revogar chaves de API. Autenticação: Chave de API. Escopo exigido: `session:elevate` Guia do tema: https://lunahia.com.br/docs/conta-e-chaves#rota-post-v1-operators-step-up #### Corpo da requisição `application/json` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `password` | `string` | sim | 1 a 512 caracteres | #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/operators/step-up" \ -H "Authorization: Bearer $LUNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "password": "YOUR_PASSWORD" }' ``` #### Respostas **200**: Sucesso. ```json { "elevatedUntil": "YOUR_ELEVATEDUNTIL", "scopes": [ "YOUR_SCOPES" ] } ``` **400**: O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. ```json { "error": "invalid_request", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisição inválida.", "campos": [ { "campo": "text.body", "motivo": "Não pode ficar vazio." } ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **415**: O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. ```json { "error": "unsupported_media_type", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Envie o corpo como application/json." } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Ler a sessão apresentada `GET /v1/operators/session` Quando a credencial apresentada expira, até quando vale a elevação aberta por POST /v1/operators/step-up (nulo sem elevação ou com a janela fechada) e os escopos que ela tem agora. Lê só a própria credencial: o identificador vem da autenticação e nunca do caminho. Autenticação: Chave de API. Escopo exigido: `session:end` #### Exemplos de código ```bash curl -X GET "https://api.lunahia.com.br/v1/operators/session" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **200**: Sucesso. ```json { "expiresAt": "2026-11-03T20:00:00.000Z", "elevatedUntil": "2026-11-03T14:30:00.000Z", "scopes": [ "numbers:read", "session:end", "session:elevate", "keys:write" ] } ``` **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ### Encerrar a sessão `POST /v1/operators/logout` Revoga a credencial apresentada, e apenas ela. O identificador vem da própria autenticação e nunca do corpo, então esta rota não consegue revogar chave de terceiro. Autenticação: Chave de API. Escopo exigido: `session:end` #### Exemplos de código ```bash curl -X POST "https://api.lunahia.com.br/v1/operators/logout" \ -H "Authorization: Bearer $LUNA_API_KEY" ``` #### Respostas **204**: Sem conteúdo: a operação foi feita e a resposta não tem corpo. **401**: A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. ```json { "error": "unauthorized", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Credencial ausente ou inválida." } ``` **403**: A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. ```json { "error": "forbidden", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.", "requiredScope": "numbers:read" } ``` **429**: Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. ```json { "error": "rate_limited", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Requisições demais. Tente novamente em instantes." } ``` **503**: A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. ```json { "error": "unavailable", "docsUrl": "https://lunahia.com.br/docs/erros", "message": "Não foi possível concluir a operação agora. Tente novamente em instantes." } ``` ## Eventos de webhook A Luna faz POST do evento no endpoint que você cadastrou, com o corpo em application/json e o cabeçalho de assinatura. Responda 2xx para confirmar; qualquer outra resposta, ou nenhuma, conta como falha e é repetida pela política de retentativa. Verifique a assinatura sobre o corpo bruto antes de confiar no conteúdo. `x-luna-signature`: A assinatura da entrega: t=,v1=."> com o segredo do endpoint. Durante uma rotação de segredo o cabeçalho traz dois valores v1=, e basta um conferir. Rejeite entregas com t fora de 300 segundos do seu relógio. ### Mensagem recebida `message.received` Um contato escreveu para um dos seus números. Traz o texto, e o conteúdo quando a mensagem é de outro tipo (mídia, botão clicado, localização, contatos, reação). | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object \| null` | sim | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. | | `event_type` | `"message.received"` | sim | | | `message` | `object` | sim | Uma mensagem que chegou de um interlocutor. Além de wamid, wa_id (que pode ser nulo), user_id, parent_user_id, username, type e text, ela traz o conteúdo que o tipo carrega (mídia, botão ou item clicado, resposta de Flow, localização, contatos, reação, pedido, edição, apagamento, aviso de tipo sem suporte), a citação, o anúncio de origem e o nome de perfil. Os nomes dentro desses campos são os da Meta. Todo campo está sempre presente, e é nulo quando não se aplica. | | `message.id` | `string (uuid)` | sim | O identificador da mensagem na Luna. É o id que GET /v1/messages/{id}/media, POST /v1/messages/{id}/read, POST /v1/messages/{id}/typing e POST /v1/messages/{id}/replay pedem. | | `message.wamid` | `string` | sim | O identificador da mensagem na Meta. | | `message.wa_id` | `string \| null` | sim | O identificador do interlocutor na Meta, em E.164 sem o sinal de mais: o telefone. Nulo quando o usuário escreveu sem que o telefone apareça (nome de usuário adotado): use user_id. | | `message.user_id` | `string \| null` | sim | O BSUID do interlocutor, o identificador do usuário que não depende do telefone (por exemplo US.13491208655302741918), como a Meta o mandou. Nulo quando a Meta ainda não o mandou para esta conversa. Quando wa_id é nulo, é o único identificador do interlocutor. | | `message.parent_user_id` | `string \| null` | sim | O BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais. | | `message.username` | `string \| null` | sim | O nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais. | | `message.type` | `string` | sim | O tipo da mensagem, no vocabulário da Meta. | | `message.text` | `string \| null` | sim | O texto da mensagem, quando o tipo é texto. Nulo nos demais tipos: a legenda de uma mídia está em media.caption, e o título de um botão clicado em interactive.title. | | `message.profile_name` | `string \| null` | sim | O nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou. | | `message.media` | `object \| null` | sim | | | `message.media.mime_type` | `string \| null` | sim | O tipo MIME do arquivo, como a Meta o informou. Nulo na mídia enviada: a Luna não guarda os dados do arquivo que você subiu. | | `message.media.sha256` | `string \| null` | sim | O resumo SHA-256 do arquivo, como a Meta o informou. Nulo na mídia enviada, pela mesma razão do mime_type. | | `message.media.caption` | `string \| null` | sim | A legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma. | | `message.media.filename` | `string \| null` | sim | O nome do arquivo. Só documento tem. | | `message.media.voice` | `boolean \| null` | sim | Verdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem. | | `message.media.animated` | `boolean \| null` | sim | Verdadeiro quando a figurinha é animada. Só figurinha tem. | | `message.media.url` | `string \| null` | sim | Link da Luna para baixar o arquivo, sem chave de API: GET desse endereço responde 302 para uma URL assinada de vida curta. É credencial de portador (quem tiver o link baixa o arquivo): não registre em log. É o mesmo em toda reentrega do aviso, e vale por 30 dias contados do recebimento. Se a Luna ainda estiver baixando o arquivo da Meta, responde 409 com Retry-After: tente de novo. Nulo quando a mídia não pode ser obtida (a Meta não mandou identificador, ou o prazo de obtenção acabou). GET /v1/messages/{id}/media, com chave, continua valendo. | | `message.interactive` | `object \| null` | sim | A resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu. | | `message.interactive.type` | `string \| null` | sim | Qual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow). | | `message.interactive.id` | `string \| null` | sim | O id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply. | | `message.interactive.title` | `string \| null` | sim | O título do botão ou do item, como estava na mensagem. Nulo em nfm_reply. | | `message.interactive.description` | `string \| null` | sim | A descrição do item da lista. Nula nos demais. | | `message.interactive.name` | `string \| null` | sim | O nome do Flow. Só em nfm_reply. | | `message.interactive.response_json` | `string \| null` | sim | As respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply. | | `message.button` | `object \| null` | sim | O clique num botão de resposta rápida de um template. | | `message.button.payload` | `string \| null` | sim | O payload que você definiu no botão de resposta rápida do template. | | `message.button.text` | `string \| null` | sim | O texto do botão. | | `message.location` | `object \| null` | sim | A localização que o interlocutor compartilhou. | | `message.location.latitude` | `number \| null` | sim | A latitude, em graus decimais. | | `message.location.longitude` | `number \| null` | sim | A longitude, em graus decimais. | | `message.location.name` | `string \| null` | sim | O nome do lugar, quando o interlocutor escolheu um. | | `message.location.address` | `string \| null` | sim | O endereço, quando há. | | `message.location.url` | `string \| null` | sim | O endereço web do lugar, quando há. | | `message.contacts` | `array \| null` | sim | Os cartões de contato que o interlocutor compartilhou. | | `message.contacts[].name` | `object \| null` | sim | O nome do contato, nos campos da Meta. | | `message.contacts[].name.formatted_name` | `string \| null` | sim | | | `message.contacts[].name.first_name` | `string \| null` | sim | | | `message.contacts[].name.last_name` | `string \| null` | sim | | | `message.contacts[].name.middle_name` | `string \| null` | sim | | | `message.contacts[].name.prefix` | `string \| null` | sim | | | `message.contacts[].name.suffix` | `string \| null` | sim | | | `message.contacts[].phones` | `array \| null` | sim | Os telefones do contato. wa_id só existe quando o telefone tem WhatsApp. | | `message.contacts[].phones[].phone` | `string \| null` | sim | | | `message.contacts[].phones[].wa_id` | `string \| null` | sim | | | `message.contacts[].phones[].type` | `string \| null` | sim | | | `message.contacts[].emails` | `array \| null` | sim | Os e-mails do contato. | | `message.contacts[].emails[].email` | `string \| null` | sim | | | `message.contacts[].emails[].type` | `string \| null` | sim | | | `message.contacts[].org` | `object \| null` | sim | A organização do contato. | | `message.contacts[].org.company` | `string \| null` | sim | | | `message.contacts[].org.department` | `string \| null` | sim | | | `message.contacts[].org.title` | `string \| null` | sim | | | `message.reaction` | `object \| null` | sim | A reação a uma mensagem, ou a retirada dela. | | `message.reaction.wamid` | `string \| null` | sim | O wamid da mensagem que recebeu a reação. | | `message.reaction.emoji` | `string \| null` | sim | O emoji. Nulo quando o interlocutor retirou a reação. | | `message.context` | `object \| null` | sim | A resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada. | | `message.context.wamid` | `string \| null` | sim | O wamid da mensagem que o interlocutor citou ao responder. | | `message.context.from` | `string \| null` | sim | Quem enviou a mensagem citada. | | `message.context.forwarded` | `boolean \| null` | sim | Verdadeiro quando a mensagem foi encaminhada. | | `message.context.frequently_forwarded` | `boolean \| null` | sim | Verdadeiro quando a mensagem foi encaminhada muitas vezes. | | `message.referral` | `object \| null` | sim | O anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever. | | `message.referral.source_type` | `string \| null` | sim | A origem do clique, como ad ou post. | | `message.referral.source_id` | `string \| null` | sim | O identificador do anúncio ou da publicação na Meta. | | `message.referral.source_url` | `string \| null` | sim | O endereço do anúncio ou da publicação. | | `message.referral.headline` | `string \| null` | sim | O título do anúncio. | | `message.referral.body` | `string \| null` | sim | O texto do anúncio. | | `message.referral.media_type` | `string \| null` | sim | O tipo da mídia do anúncio, como image ou video. | | `message.referral.ctwa_clid` | `string \| null` | sim | O identificador do clique, para atribuição de conversão. | | `message.unsupported` | `object \| null` | sim | Presente quando o interlocutor mandou algo que a Cloud API não entrega (type é unsupported). Não há conteúdo a ler: o aviso existe para o seu agente poder responder "não consigo ver isso". | | `message.unsupported.code` | `integer \| null` | sim | O código de erro da Meta, como ela mandou (131051 é "tipo de mensagem sem suporte"). | | `message.unsupported.title` | `string \| null` | sim | O título do erro, como a Meta o mandou. | | `message.unsupported.details` | `string \| null` | sim | O detalhe do erro, como a Meta o mandou. | | `message.edit` | `object \| null` | sim | Presente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit). | | `message.edit.wamid` | `string \| null` | sim | O wamid da mensagem que foi editada. | | `message.edit.type` | `string \| null` | sim | O tipo do conteúdo novo, como text. | | `message.edit.text` | `string \| null` | sim | O texto novo, quando o conteúdo novo é texto. | | `message.revoke` | `object \| null` | sim | Presente quando o interlocutor apagou uma mensagem para todos (type é revoke). | | `message.revoke.wamid` | `string \| null` | sim | O wamid da mensagem que o interlocutor apagou para todos. | | `message.order` | `object \| null` | sim | O pedido que o interlocutor montou num catálogo e enviou (type é order). | | `message.order.catalog_id` | `string \| null` | sim | O catálogo de onde veio o pedido. | | `message.order.text` | `string \| null` | sim | O texto que o interlocutor escreveu junto com o pedido. | | `message.order.items` | `array \| null` | sim | Os itens do pedido. | | `message.order.items[].product_retailer_id` | `string \| null` | sim | O identificador do produto no seu catálogo. | | `message.order.items[].quantity` | `string \| null` | sim | A quantidade pedida, como a Meta mandou. | | `message.order.items[].item_price` | `string \| null` | sim | O preço unitário, como a Meta mandou. | | `message.order.items[].currency` | `string \| null` | sim | A moeda do preço. | ```json { "version": "2026-11-10", "event_id": "1fd66b6f86489c36c3552f14dbf49f50df6b2d946c259f7b0eaa0ef88f58adb5", "event_type": "message.received", "occurred_at": "2026-10-06T14:05:40.120Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "message": { "id": "7d1c4b8e-2a3f-4e5d-9c6b-1f0a2b3c4d5e", "wamid": "wamid.EXAMPLE_BUTTON_CLICK", "wa_id": "5511900000000", "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": null, "type": "interactive", "text": null, "profile_name": "Maria Souza", "media": null, "interactive": { "type": "button_reply", "id": "rastrear", "title": "Rastrear pedido", "description": null, "name": null, "response_json": null }, "button": null, "location": null, "contacts": null, "reaction": null, "context": { "wamid": "wamid.EXAMPLE_MESSAGE_WITH_BUTTONS", "from": "5511900000001", "forwarded": null, "frequently_forwarded": null }, "referral": null, "unsupported": null, "edit": null, "revoke": null, "order": null } } ``` ```json { "version": "2026-11-10", "event_id": "0ab56cecd18b825ebeb4548219cb8fe392fec9e56301e52be1086f3c734ace86", "event_type": "message.received", "occurred_at": "2026-10-06T14:07:03.900Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "message": { "id": "4c9e2d1a-8b7f-4a6c-b5d3-0e1f2a3b4c5d", "wamid": "wamid.EXAMPLE_IMAGE", "wa_id": "5511900000000", "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": null, "type": "image", "text": null, "profile_name": "Maria Souza", "media": { "mime_type": "image/jpeg", "sha256": "EXAMPLE_SHA256_OF_THE_FILE", "caption": "A nota fiscal do pedido", "filename": null, "voice": null, "animated": null, "url": "https://api.lunahia.com.br/v1/media/6f1a2b3c-4d5e-4f60-8a7b-9c0d1e2f3a4b.EXEMPLO_DO_SEGREDO_DE_43_CARACTERES_AAAAAAAA" }, "interactive": null, "button": null, "location": null, "contacts": null, "reaction": null, "context": null, "referral": null, "unsupported": null, "edit": null, "revoke": null, "order": null } } ``` ```json { "version": "2026-11-10", "event_id": "a2f4909b0fd2db8ab8b1bfe4e16487f49b86113e27bf8c3c9d10a2d0fefebc72", "event_type": "message.received", "occurred_at": "2026-10-06T14:02:11.482Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "message": { "id": "b6d84033-a8e8-4db9-aab6-565ce203cc51", "wamid": "wamid.EXAMPLE_NOT_A_REAL_ID", "wa_id": "5511900000000", "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": null, "type": "text", "text": "Oi! Queria saber o status do meu pedido.", "profile_name": "Maria Souza", "media": null, "interactive": null, "button": null, "location": null, "contacts": null, "reaction": null, "context": null, "referral": null, "unsupported": null, "edit": null, "revoke": null, "order": null } } ``` ```json { "version": "2026-11-10", "event_id": "e2f81dd079e4419dac363779655be694a25cc502b7646be51cdac4b0cfc276fb", "event_type": "message.received", "occurred_at": "2026-11-03T14:02:11.482Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "message": { "id": "c8a1e5d2-6f3b-4a7c-9e0d-1b2c3d4e5f60", "wamid": "wamid.EXAMPLE_NO_PHONE", "wa_id": null, "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": "mariasouza", "type": "text", "text": "Oi! Queria saber o status do meu pedido.", "profile_name": "Maria Souza", "media": null, "interactive": null, "button": null, "location": null, "contacts": null, "reaction": null, "context": null, "referral": null, "unsupported": null, "edit": null, "revoke": null, "order": null } } ``` ```json { "version": "2026-11-10", "event_id": "1eaa360e693d1a7366e66ba81d7bee362a56c2b4f4ef4854e43ad35861bd7ae1", "event_type": "message.received", "occurred_at": "2026-11-04T14:10:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "message": { "id": "f3a8c1d2-5b6e-4f70-8a9b-0c1d2e3f4a5b", "wamid": "wamid.EXAMPLE_ORDER", "wa_id": "5511900000000", "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": null, "type": "order", "text": null, "profile_name": "Maria Souza", "media": null, "interactive": null, "button": null, "location": null, "contacts": null, "reaction": null, "context": null, "referral": null, "unsupported": null, "edit": null, "revoke": null, "order": { "catalog_id": "EXAMPLE_CATALOG_ID", "text": "Quero estes dois, por favor.", "items": [ { "product_retailer_id": "sku-001", "quantity": "2", "item_price": "49.90", "currency": "BRL" }, { "product_retailer_id": "sku-002", "quantity": "1", "item_price": "15.00", "currency": "BRL" } ] } } } ``` ```json { "version": "2026-11-10", "event_id": "b9714a025db0a22bd3a63f9dfd9aa52aed7ddcae4efde825dfb2fa41e1736dd2", "event_type": "message.received", "occurred_at": "2026-11-04T14:12:30.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "message": { "id": "a4b9d2e3-6c7f-4081-9bac-1d2e3f4a5b6c", "wamid": "wamid.EXAMPLE_FLOW_REPLY", "wa_id": "5511900000000", "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": null, "type": "interactive", "text": null, "profile_name": "Maria Souza", "media": null, "interactive": { "type": "nfm_reply", "id": null, "title": null, "description": null, "name": "flow", "response_json": "{\"flow_token\":\"EXAMPLE_FLOW_TOKEN\",\"nome\":\"Maria Souza\",\"data\":\"2026-11-10\"}" }, "button": null, "location": null, "contacts": null, "reaction": null, "context": null, "referral": null, "unsupported": null, "edit": null, "revoke": null, "order": null } } ``` ### Estado de uma mensagem que você enviou `message.status` Uma mensagem que você enviou mudou de estado: sent, delivered, read ou failed. Em failed, o evento traz o erro. Em sent e em um entre delivered e read, traz o pricing: o custo que a Meta aplicou à mensagem, com os nomes dela. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object \| null` | sim | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. | | `event_type` | `"message.status"` | sim | | | `message` | `object` | sim | Uma mudança de estado de uma mensagem que você enviou. | | `message.id` | `string (uuid) \| null` | sim | O identificador da mensagem na Luna, o mesmo que POST /v1/messages devolveu quando você a enviou. Nulo quando o status é de uma mensagem que a Luna não conhece. | | `message.wamid` | `string \| null` | sim | O identificador da mensagem na Meta. Nulo quando a Meta recusou o envio antes de aceitar a mensagem, caso em que ela nunca teve identificador: use id para correlacionar. | | `message.wa_id` | `string \| null` | sim | O identificador do interlocutor na Meta: o telefone. Nulo quando a conversa é só de BSUID: use user_id. | | `message.user_id` | `string \| null` | sim | O BSUID do interlocutor, o identificador do usuário que não depende do telefone (por exemplo US.13491208655302741918), como a Meta o mandou. Nulo quando a Meta ainda não o mandou para esta conversa. Quando wa_id é nulo, é o único identificador do interlocutor. | | `message.parent_user_id` | `string \| null` | sim | O BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais. | | `message.username` | `string \| null` | sim | O nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais. | | `message.status` | `string` | sim | O estado da mensagem, no vocabulário da Meta. Novos estados podem aparecer. | | `message.error_code` | `integer \| null` | sim | O código de erro da Meta quando o estado é de falha. Nulo nos demais. | | `message.error` | `object \| null` | sim | O primeiro erro que a Meta informou quando o estado é de falha, com code, title e message. Nulo nos demais estados. O detalhe completo, com a causa e a ação recomendada, está em GET /v1/messages/{id}. | | `message.error.code` | `integer \| null` | sim | O código do erro, como a Meta o informou. | | `message.error.title` | `string \| null` | sim | O título do erro, como a Meta o informou. | | `message.error.message` | `string \| null` | sim | A descrição do erro, como a Meta a informou. | | `message.pricing` | `object \| null` | sim | O custo que a Meta aplicou à mensagem. A Meta o informa só no estado sent e em um entre delivered e read, então nos demais estados vem nulo. Não é a fatura da Meta: a fonte da verdade é o painel de cobrança dela. | | `message.pricing.billable` | `boolean \| null` | sim | Se a Meta marcou a mensagem como cobrada. A Meta vai descontinuar este campo: use type e category juntos. | | `message.pricing.pricing_model` | `string \| null` | sim | O modelo de preço da Meta, como ela informou (hoje PMP ou CBP). | | `message.pricing.type` | `string \| null` | sim | O tipo de cobrança da Meta, como ela informou (por exemplo regular ou free_customer_service). Novos valores podem aparecer. | | `message.pricing.category` | `string \| null` | sim | A categoria da Meta, como ela informou (por exemplo service, utility ou marketing). Novos valores podem aparecer. | | `message.callback_data` | `string \| null` | sim | A etiqueta que você mandou em callbackData ao enviar a mensagem, devolvida como veio. Nulo quando o envio não trouxe etiqueta. Está em todos os estados da mensagem, inclusive failed. | ```json { "version": "2026-11-10", "event_id": "464e089a80690f1792db6249678ddeced5ad5be0d46d95e2daa263779f7d92e5", "event_type": "message.status", "occurred_at": "2026-10-06T14:02:14.090Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "message": { "id": "ae60f288-7565-4315-a440-3663e9c231e1", "wamid": "wamid.EXAMPLE_NOT_A_REAL_ID", "wa_id": "5511900000000", "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": null, "status": "sent", "error_code": null, "error": null, "pricing": { "billable": false, "pricing_model": "PMP", "type": "free_customer_service", "category": "service" }, "callback_data": "atendimento-8841" } } ``` ```json { "version": "2026-11-10", "event_id": "6a79ec64bfea6acc67135d032067fd6261aa568c3aea35af7999790a7730cf69", "event_type": "message.status", "occurred_at": "2026-10-06T14:02:15.311Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "message": { "id": "ae60f288-7565-4315-a440-3663e9c231e1", "wamid": "wamid.EXAMPLE_NOT_A_REAL_ID", "wa_id": "5511900000000", "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": null, "status": "failed", "error_code": 131026, "error": { "code": 131026, "title": "Message undeliverable", "message": "Message undeliverable" }, "pricing": null, "callback_data": null } } ``` ### Contato trocou de telefone ou de BSUID `contact.identity_changed` Um contato trocou de telefone (user_changed_number) ou de BSUID (user_changed_user_id). A Luna ligou a nova identidade à mesma conversa. Use previous_user_id e user_id para atualizar o contato no seu cadastro. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object \| null` | sim | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. | | `event_type` | `"contact.identity_changed"` | sim | | | `contact` | `object` | sim | O contato trocou de telefone ou de BSUID. A Luna ligou a nova identidade à mesma conversa. Use previous_user_id e user_id para atualizar o contato no seu cadastro. Todo campo está sempre presente, e é nulo quando não se aplica. | | `contact.wamid` | `string` | sim | O identificador, na Meta, da mensagem de sistema que avisou a troca. | | `contact.change_type` | `string` | sim | O que mudou, como a Meta informou: user_changed_number (o telefone) ou user_changed_user_id (o BSUID). Novos valores podem aparecer. | | `contact.wa_id` | `string \| null` | sim | O telefone do contato, quando a Meta o informa. Nulo quando ela não o manda (usuário com nome de usuário). | | `contact.user_id` | `string \| null` | sim | O BSUID do contato depois da troca, como a Meta mandou. | | `contact.previous_user_id` | `string \| null` | sim | O BSUID de antes da troca, quando a Meta o informa. Use-o para achar o contato no seu cadastro. | | `contact.parent_user_id` | `string \| null` | sim | O BSUID pai do contato depois da troca, quando a Meta o informa. | | `contact.previous_parent_user_id` | `string \| null` | sim | O BSUID pai de antes da troca, quando a Meta o informa. | ```json { "version": "2026-11-10", "event_id": "f73a65b1f155f86f94e0886ad29bac662a822fabf796b626cdf865c7060f0db9", "event_type": "contact.identity_changed", "occurred_at": "2026-11-03T15:20:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "contact": { "wamid": "wamid.EXAMPLE_IDENTITY_CHANGE", "change_type": "user_changed_user_id", "wa_id": null, "user_id": "BR.98765432109876543210", "previous_user_id": "BR.13491208655302741918", "parent_user_id": null, "previous_parent_user_id": null } } ``` ### Contato mudou uma preferência `contact.preferences_changed` Um contato mudou uma preferência na Meta, hoje a de receber mensagens de marketing: pediu para parar (por exemplo value stop) ou voltou a aceitar. Os valores chegam como a Meta mandou. A Luna não bloqueia nenhum envio por causa do aviso: o seu sistema decide, e deve parar de mandar marketing a quem pediu. Só chega se o campo user_preferences estiver assinado no app da Meta. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object \| null` | sim | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. | | `event_type` | `"contact.preferences_changed"` | sim | | | `contact` | `object` | sim | Quem mudou a preferência. | | `contact.wa_id` | `string \| null` | sim | O telefone do contato, quando a Meta o informa. Nulo quando ela não o manda (usuário com nome de usuário): use user_id. | | `contact.user_id` | `string \| null` | sim | O BSUID do contato, como a Meta mandou. | | `contact.parent_user_id` | `string \| null` | sim | O BSUID pai do contato, quando a Meta o informa. | | `contact.username` | `string \| null` | sim | O nome de usuário do contato, quando ele adotou um. | | `contact.profile_name` | `string \| null` | sim | O nome que o contato exibe no WhatsApp, quando a Meta o manda. | | `preference` | `object` | sim | O que mudou. | | `preference.category` | `string \| null` | sim | A categoria da preferência, como a Meta informou (por exemplo marketing_messages). Novos valores podem aparecer. | | `preference.value` | `string \| null` | sim | O que o contato escolheu, como a Meta informou (por exemplo stop para parar de receber, resume para voltar). Novos valores podem aparecer. | | `preference.detail` | `string \| null` | sim | O texto que a Meta mandou para explicar a mudança. | ```json { "version": "2026-11-10", "event_id": "4236ccfb21e7cec359d1e1b5b5f3f8e65cb3e8a8db0fc86e4d95da037796e97c", "event_type": "contact.preferences_changed", "occurred_at": "2026-11-04T16:45:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "contact": { "wa_id": "5511900000000", "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": null, "profile_name": "Maria Souza" }, "preference": { "category": "marketing_messages", "value": "stop", "detail": "User requested to stop marketing messages" } } ``` ### Eventos descartados por indisponibilidade `backlog.dropped` O seu endpoint ficou fora do ar por tempo demais, e a plataforma descartou o que se acumulou. Diz quantos eventos e de que período. O aviso não é descartado junto. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object \| null` | sim | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. | | `event_type` | `"backlog.dropped"` | sim | | | `backlog` | `object` | sim | Eventos que a plataforma descartou sem entregar, e que não serão reenviados. | | `backlog.motivo` | `string` | sim | Qual limite foi atingido: idade, quando as mensagens ficaram velhas demais para serem acionáveis; volume, quando o acumulado deste endpoint passou do teto da plataforma. · Valores: idade, volume | | `backlog.quantidade` | `integer` | sim | Quantos eventos foram descartados nesta ocorrência. | | `backlog.janela_inicio` | `string` | sim | O evento mais antigo descartado nesta ocorrência. | | `backlog.janela_fim` | `string` | sim | O evento mais recente descartado nesta ocorrência. | ```json { "version": "2026-11-10", "event_id": "f76937420c2e818b87ce9b6acc5cb192c059ed2e33cda23339d5cf650b762ce5", "event_type": "backlog.dropped", "occurred_at": "2026-10-06T14:30:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "backlog": { "motivo": "idade", "quantidade": 37, "janela_inicio": "2026-10-06T09:00:00.000Z", "janela_fim": "2026-10-06T14:30:00.000Z" } } ``` ### Prazo da importação do histórico se aproximando `history_sync.deadline_approaching` Num número conectado em coexistência, a importação das conversas anteriores ainda está em curso e o prazo dela se aproxima. Passado o prazo sem concluir, a Meta desconecta o negócio final. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object \| null` | sim | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. | | `event_type` | `"history_sync.deadline_approaching"` | sim | | | `history_sync` | `object` | sim | A importação das conversas anteriores de um número em coexistência está em curso e o prazo dela se aproxima. O estado corrente, inclusive o progresso, está em GET /v1/numbers/{id}/health. | | `history_sync.prazo` | `string` | sim | Até quando a importação precisa terminar, em UTC. É o mesmo instante que sincronizacaoPrazo devolve na rota de saúde do número. | ```json { "version": "2026-11-10", "event_id": "d42ca56e44ef023d52b0a0739dcf3afb0d5054a8b84321c41e432ed6707b043f", "event_type": "history_sync.deadline_approaching", "occurred_at": "2026-10-07T03:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "history_sync": { "prazo": "2026-10-07T09:00:00.000Z" } } ``` ### Evento de teste `webhook.test` O evento que POST /v1/webhooks/endpoints/{id}/test envia ao seu endpoint, para você conferir URL e verificação de assinatura. Não passa por nenhum número. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `null` | sim | Sempre null neste tipo: o evento de teste não passa por nenhum número. | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `null` | sim | Sempre null neste tipo: o evento não passa por um número. | | `event_type` | `"webhook.test"` | sim | | | `webhook_test` | `object` | sim | Um evento de teste, enviado porque você pediu em POST /v1/webhooks/endpoints/{id}/test. Ele nunca aparece se você não pediu, não tem número nem conversa, e serve para conferir a URL e a verificação da assinatura. | | `webhook_test.endpoint_id` | `string (uuid)` | sim | O endpoint que pediu este teste, o mesmo id que POST /v1/webhooks/endpoints devolveu. | ```json { "version": "2026-11-10", "event_id": "6af3f85d8fedc8bb0f6d5bb6b4631e324574c539763c25cf113fd40db822cea8", "event_type": "webhook.test", "occurred_at": "2026-10-07T12:00:00.000Z", "phone_number_id": null, "number": null, "webhook_test": { "endpoint_id": "5c0e9a52-3a0e-4c3f-9f3e-0b3f6f1a2c77" } } ``` ### Resposta dada pelo aplicativo do celular `message.echo` O dono do negócio respondeu a um cliente pelo aplicativo WhatsApp Business do celular. Só ocorre em número conectado em coexistência. message.wa_id é o destinatário. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object \| null` | sim | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. | | `event_type` | `"message.echo"` | sim | | | `message` | `object` | sim | Uma mensagem que o dono do negócio escreveu pelo aplicativo WhatsApp Business do celular, num número conectado em coexistência. Só ocorre em número conectado em coexistência. É o sinal para um agente automatizado ficar quieto na conversa: um humano respondeu. A forma é a de message.received, e wa_id é o destinatário. Todo campo está sempre presente, e é nulo quando não se aplica. | | `message.id` | `string (uuid)` | sim | O identificador da mensagem na Luna. É o id que GET /v1/messages/{id}/media, POST /v1/messages/{id}/read, POST /v1/messages/{id}/typing e POST /v1/messages/{id}/replay pedem. | | `message.wamid` | `string` | sim | O identificador da mensagem na Meta. | | `message.wa_id` | `string \| null` | sim | O identificador do DESTINATÁRIO na Meta, em E.164 sem o sinal de mais: o cliente final para quem o dono do negócio escreveu. É a conversa onde o seu agente deve ficar quieto. Nulo quando a conversa é só de BSUID: use user_id. | | `message.user_id` | `string \| null` | sim | O BSUID do interlocutor, o identificador do usuário que não depende do telefone (por exemplo US.13491208655302741918), como a Meta o mandou. Nulo quando a Meta ainda não o mandou para esta conversa. Quando wa_id é nulo, é o único identificador do interlocutor. | | `message.parent_user_id` | `string \| null` | sim | O BSUID pai do interlocutor (por exemplo US.ENT.11815799212886844830). Só existe quando a Meta o manda; nulo no demais. | | `message.username` | `string \| null` | sim | O nome de usuário do interlocutor. Só existe quando ele adotou um; nulo no demais. | | `message.type` | `string` | sim | O tipo da mensagem, no vocabulário da Meta. | | `message.text` | `string \| null` | sim | O texto da mensagem, quando o tipo é texto. Nulo nos demais tipos: a legenda de uma mídia está em media.caption, e o título de um botão clicado em interactive.title. | | `message.profile_name` | `string \| null` | sim | O nome que o interlocutor exibe no WhatsApp. Nulo quando a Meta não o mandou. | | `message.media` | `object \| null` | sim | | | `message.media.mime_type` | `string \| null` | sim | O tipo MIME do arquivo, como a Meta o informou. Nulo na mídia enviada: a Luna não guarda os dados do arquivo que você subiu. | | `message.media.sha256` | `string \| null` | sim | O resumo SHA-256 do arquivo, como a Meta o informou. Nulo na mídia enviada, pela mesma razão do mime_type. | | `message.media.caption` | `string \| null` | sim | A legenda. Nula em áudio e em figurinha, e quando o interlocutor não escreveu uma. | | `message.media.filename` | `string \| null` | sim | O nome do arquivo. Só documento tem. | | `message.media.voice` | `boolean \| null` | sim | Verdadeiro quando o áudio foi gravado na hora, como mensagem de voz. Só áudio tem. | | `message.media.animated` | `boolean \| null` | sim | Verdadeiro quando a figurinha é animada. Só figurinha tem. | | `message.media.url` | `string \| null` | sim | Link da Luna para baixar o arquivo, sem chave de API: GET desse endereço responde 302 para uma URL assinada de vida curta. É credencial de portador (quem tiver o link baixa o arquivo): não registre em log. É o mesmo em toda reentrega do aviso, e vale por 30 dias contados do recebimento. Se a Luna ainda estiver baixando o arquivo da Meta, responde 409 com Retry-After: tente de novo. Nulo quando a mídia não pode ser obtida (a Meta não mandou identificador, ou o prazo de obtenção acabou). GET /v1/messages/{id}/media, com chave, continua valendo. | | `message.interactive` | `object \| null` | sim | A resposta a uma mensagem interativa que você enviou: o botão ou o item que o interlocutor escolheu. | | `message.interactive.type` | `string \| null` | sim | Qual resposta foi dada: button_reply (botão de resposta), list_reply (item de lista) ou nfm_reply (resposta de um Flow). | | `message.interactive.id` | `string \| null` | sim | O id que você deu ao botão ou ao item quando enviou a mensagem. Nulo em nfm_reply. | | `message.interactive.title` | `string \| null` | sim | O título do botão ou do item, como estava na mensagem. Nulo em nfm_reply. | | `message.interactive.description` | `string \| null` | sim | A descrição do item da lista. Nula nos demais. | | `message.interactive.name` | `string \| null` | sim | O nome do Flow. Só em nfm_reply. | | `message.interactive.response_json` | `string \| null` | sim | As respostas do Flow, como o texto JSON que a Meta mandou, sem interpretar. Só em nfm_reply. | | `message.button` | `object \| null` | sim | O clique num botão de resposta rápida de um template. | | `message.button.payload` | `string \| null` | sim | O payload que você definiu no botão de resposta rápida do template. | | `message.button.text` | `string \| null` | sim | O texto do botão. | | `message.location` | `object \| null` | sim | A localização que o interlocutor compartilhou. | | `message.location.latitude` | `number \| null` | sim | A latitude, em graus decimais. | | `message.location.longitude` | `number \| null` | sim | A longitude, em graus decimais. | | `message.location.name` | `string \| null` | sim | O nome do lugar, quando o interlocutor escolheu um. | | `message.location.address` | `string \| null` | sim | O endereço, quando há. | | `message.location.url` | `string \| null` | sim | O endereço web do lugar, quando há. | | `message.contacts` | `array \| null` | sim | Os cartões de contato que o interlocutor compartilhou. | | `message.contacts[].name` | `object \| null` | sim | O nome do contato, nos campos da Meta. | | `message.contacts[].name.formatted_name` | `string \| null` | sim | | | `message.contacts[].name.first_name` | `string \| null` | sim | | | `message.contacts[].name.last_name` | `string \| null` | sim | | | `message.contacts[].name.middle_name` | `string \| null` | sim | | | `message.contacts[].name.prefix` | `string \| null` | sim | | | `message.contacts[].name.suffix` | `string \| null` | sim | | | `message.contacts[].phones` | `array \| null` | sim | Os telefones do contato. wa_id só existe quando o telefone tem WhatsApp. | | `message.contacts[].phones[].phone` | `string \| null` | sim | | | `message.contacts[].phones[].wa_id` | `string \| null` | sim | | | `message.contacts[].phones[].type` | `string \| null` | sim | | | `message.contacts[].emails` | `array \| null` | sim | Os e-mails do contato. | | `message.contacts[].emails[].email` | `string \| null` | sim | | | `message.contacts[].emails[].type` | `string \| null` | sim | | | `message.contacts[].org` | `object \| null` | sim | A organização do contato. | | `message.contacts[].org.company` | `string \| null` | sim | | | `message.contacts[].org.department` | `string \| null` | sim | | | `message.contacts[].org.title` | `string \| null` | sim | | | `message.reaction` | `object \| null` | sim | A reação a uma mensagem, ou a retirada dela. | | `message.reaction.wamid` | `string \| null` | sim | O wamid da mensagem que recebeu a reação. | | `message.reaction.emoji` | `string \| null` | sim | O emoji. Nulo quando o interlocutor retirou a reação. | | `message.context` | `object \| null` | sim | A resposta citando uma mensagem, ou o aviso de que a mensagem foi encaminhada. | | `message.context.wamid` | `string \| null` | sim | O wamid da mensagem que o interlocutor citou ao responder. | | `message.context.from` | `string \| null` | sim | Quem enviou a mensagem citada. | | `message.context.forwarded` | `boolean \| null` | sim | Verdadeiro quando a mensagem foi encaminhada. | | `message.context.frequently_forwarded` | `boolean \| null` | sim | Verdadeiro quando a mensagem foi encaminhada muitas vezes. | | `message.referral` | `object \| null` | sim | O anúncio Click to WhatsApp ou a publicação que levou o interlocutor a escrever. | | `message.referral.source_type` | `string \| null` | sim | A origem do clique, como ad ou post. | | `message.referral.source_id` | `string \| null` | sim | O identificador do anúncio ou da publicação na Meta. | | `message.referral.source_url` | `string \| null` | sim | O endereço do anúncio ou da publicação. | | `message.referral.headline` | `string \| null` | sim | O título do anúncio. | | `message.referral.body` | `string \| null` | sim | O texto do anúncio. | | `message.referral.media_type` | `string \| null` | sim | O tipo da mídia do anúncio, como image ou video. | | `message.referral.ctwa_clid` | `string \| null` | sim | O identificador do clique, para atribuição de conversão. | | `message.unsupported` | `object \| null` | sim | Presente quando o interlocutor mandou algo que a Cloud API não entrega (type é unsupported). Não há conteúdo a ler: o aviso existe para o seu agente poder responder "não consigo ver isso". | | `message.unsupported.code` | `integer \| null` | sim | O código de erro da Meta, como ela mandou (131051 é "tipo de mensagem sem suporte"). | | `message.unsupported.title` | `string \| null` | sim | O título do erro, como a Meta o mandou. | | `message.unsupported.details` | `string \| null` | sim | O detalhe do erro, como a Meta o mandou. | | `message.edit` | `object \| null` | sim | Presente quando o interlocutor editou uma mensagem que já tinha mandado (type é edit). | | `message.edit.wamid` | `string \| null` | sim | O wamid da mensagem que foi editada. | | `message.edit.type` | `string \| null` | sim | O tipo do conteúdo novo, como text. | | `message.edit.text` | `string \| null` | sim | O texto novo, quando o conteúdo novo é texto. | | `message.revoke` | `object \| null` | sim | Presente quando o interlocutor apagou uma mensagem para todos (type é revoke). | | `message.revoke.wamid` | `string \| null` | sim | O wamid da mensagem que o interlocutor apagou para todos. | | `message.order` | `object \| null` | sim | O pedido que o interlocutor montou num catálogo e enviou (type é order). | | `message.order.catalog_id` | `string \| null` | sim | O catálogo de onde veio o pedido. | | `message.order.text` | `string \| null` | sim | O texto que o interlocutor escreveu junto com o pedido. | | `message.order.items` | `array \| null` | sim | Os itens do pedido. | | `message.order.items[].product_retailer_id` | `string \| null` | sim | O identificador do produto no seu catálogo. | | `message.order.items[].quantity` | `string \| null` | sim | A quantidade pedida, como a Meta mandou. | | `message.order.items[].item_price` | `string \| null` | sim | O preço unitário, como a Meta mandou. | | `message.order.items[].currency` | `string \| null` | sim | A moeda do preço. | ```json { "version": "2026-11-10", "event_id": "01b53d46e858f6ab6c89e183ef9509d703f665f6cfe2eb1d6bb185df56224d88", "event_type": "message.echo", "occurred_at": "2026-10-07T13:02:30.250Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "message": { "id": "9a3e6b14-5c2d-4f81-b7a0-2d8e1c4f6a93", "wamid": "wamid.EXAMPLE_ECHO", "wa_id": "5511900000000", "user_id": "BR.13491208655302741918", "parent_user_id": null, "username": null, "type": "text", "text": "Oi, Maria! Já separei o seu pedido, sai hoje.", "profile_name": null, "media": null, "interactive": null, "button": null, "location": null, "contacts": null, "reaction": null, "context": null, "referral": null, "unsupported": null, "edit": null, "revoke": null, "order": null } } ``` ### Estado de um template mudou `template.status` A Meta aprovou, rejeitou, pausou ou desativou um template, e quando houver motivo ele vem junto. Não tem número nem mensagem. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `null` | sim | Sempre null neste tipo: o template pertence à conta de negócio, e não a um número. | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `null` | sim | Sempre null neste tipo: o evento não passa por um número. | | `event_type` | `"template.status"` | sim | | | `template` | `object` | sim | O estado de um template mudou na Meta: aprovado, rejeitado, pausado, desativado ou outro. Não tem número nem conversa, porque o template pertence à conta de negócio. | | `template.id` | `string (uuid)` | sim | O identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem. | | `template.name` | `string` | sim | O nome do template. | | `template.language` | `string` | sim | O idioma do template, no código da Meta. | | `template.waba_id` | `string` | sim | A conta de WhatsApp Business na Meta (WABA) a que o template pertence, o mesmo id que GET /v1/business-accounts devolve em wabaId. | | `template.external_id` | `string \| null` | sim | O rótulo do cliente dono do template (o externalId que o seu sistema deu ao conectar o número). É o rótulo dos números da conta quando todos eles têm o mesmo. Nulo quando a conta tem números de clientes diferentes, quando algum número dela não tem rótulo e quando ela não tem número conectado: nesses casos, ligue o evento ao cliente por waba_id (GET /v1/business-accounts). | | `template.status` | `string` | sim | O novo estado do template, no vocabulário da Meta: APPROVED, REJECTED, PAUSED, DISABLED e outros. Novos estados podem aparecer. | | `template.category` | `string` | sim | A categoria do template, no vocabulário da Meta. | | `template.reason` | `string \| null` | sim | O motivo que a Meta informou para a rejeição ou a pausa. Nulo quando ela não informa um, como nas aprovações. | ```json { "version": "2026-11-10", "event_id": "821d41ec2c33a28abe8a0baf97db034baaef1dbe511a6e546a37eca4ad565c65", "event_type": "template.status", "occurred_at": "2026-10-07T13:20:00.000Z", "phone_number_id": null, "number": null, "template": { "id": "3f6a1c52-9d4e-4b87-a1f0-5e2c7b9d8a14", "name": "confirmacao_de_pedido", "language": "pt_BR", "waba_id": "102290129340398", "external_id": "cliente-8841", "status": "REJECTED", "category": "UTILITY", "reason": "INVALID_FORMAT" } } ``` ### Número conectado `number.connected` Um número terminou de ser conectado e está registrado na Cloud API. É o sinal de que o seu cliente concluiu a conexão que você abriu com o link de conexão, e traz o externalId dele. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object` | sim | Um número terminou de ser conectado e está registrado na Cloud API. É o sinal de que o seu cliente concluiu a conexão: você não precisa consultar a lista de números para descobrir. Para saber se o envio já está liberado, leia o campo ready de GET /v1/numbers/{id}. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. | | `number.waba_id` | `string` | sim | A conta de WhatsApp Business na Meta (WABA) a que o número pertence, o mesmo id que GET /v1/business-accounts devolve em wabaId. | | `number.coexistence` | `boolean` | sim | true quando a Luna já observou tráfego de coexistência neste número, ou seja, ele continua funcionando no aplicativo do celular. Pode ser false no instante da conexão e passar a true depois. O estado corrente está no campo coexistence de GET /v1/numbers/{id}. | | `event_type` | `"number.connected"` | sim | | ```json { "version": "2026-11-10", "event_id": "458470a340db14358f03ac02fde7e3839cb6887f3071c06c57a3d9d456621996", "event_type": "number.connected", "occurred_at": "2026-10-07T13:45:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "waba_id": "102290129340398", "coexistence": false } } ``` ### Número aguardando método de pagamento na Meta `number.payment_required` A Meta recusou um envio deste número por falta de método de pagamento do negócio dono da conta (erro 131042). Sai uma vez ao entrar no estado, e não a cada mensagem recusada. Quem resolve é o dono da conta, no WhatsApp Manager da Meta: a Luna não intermedeia esse pagamento. O guia Pagamento na Meta explica o que dizer ao seu cliente. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object` | sim | A Meta recusou um envio deste número por falta de método de pagamento do negócio dono da conta (erro 131042). O número continua conectado e os eventos de entrada seguem chegando, mas os envios são recusados até o dono da conta cadastrar ou regularizar o método de pagamento no WhatsApp Manager da Meta. A Luna não intermedeia esse pagamento. O evento sai uma vez ao entrar no estado, e não a cada mensagem recusada: as mensagens recusadas chegam como message.status com status failed. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. | | `number.awaiting_payment_since` | `string` | sim | Quando a Meta recusou o primeiro envio por falta de método de pagamento. É o mesmo valor que GET /v1/numbers/{id} devolve em awaitingPaymentSince enquanto a espera durar. | | `event_type` | `"number.payment_required"` | sim | | ```json { "version": "2026-11-10", "event_id": "50a49cee4b216c529e3f7cdd0be525f8902ff6aff66439e004dfe34a0c979fcf", "event_type": "number.payment_required", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "awaiting_payment_since": "2026-10-13T12:00:00.000Z" } } ``` ### Número voltou a enviar depois da espera por pagamento `number.payment_resolved` Um envio deste número voltou a ser aceito pela Meta depois de uma espera por método de pagamento. É o único sinal de que o pagamento foi regularizado: a Meta não avisa e não oferece consulta. As mensagens recusadas durante a espera não são reenviadas sozinhas. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object` | sim | Um envio deste número voltou a ser aceito pela Meta depois de uma espera por método de pagamento. É o único sinal de que o pagamento foi regularizado: a Meta não avisa e não oferece consulta. As mensagens recusadas durante a espera não são reenviadas sozinhas; envie de novo o que ainda interessa. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. | | `event_type` | `"number.payment_resolved"` | sim | | ```json { "version": "2026-11-10", "event_id": "6a956161dd17bb975533e63286e811ae62b77b3350107945952b2e53f0a9d1e2", "event_type": "number.payment_resolved", "occurred_at": "2026-10-13T15:30:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841" } } ``` ### Conta restrita pela Meta `account.restricted` A Meta restringiu a conta de WhatsApp Business do número. Traz o tipo, o prazo e a orientação da Meta em restrictions. O aviso é da conta: sai um evento por número conectado dela, todos com o mesmo waba_id. Quem resolve é o dono da conta, no WhatsApp Manager. O guia Saúde da conta explica cada caso. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object \| null` | sim | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. | | `event_type` | `"account.restricted"` | sim | | | `waba` | `object` | sim | A Meta restringiu a conta de WhatsApp Business deste número. O que a restrição impede depende do tipo: confira restrictions[].restriction_type e o prazo em expiration. A Luna não levanta restrição; quem resolve é o dono da conta, no WhatsApp Manager da Meta. A Meta não avisa quando uma restrição por prazo termina. | | `waba.waba_id` | `string` | sim | A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id. | | `waba.number_id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `waba.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. | | `waba.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. | | `waba.restrictions` | `array` | sim | As restrições que a Meta aplicou à conta. Pode vir vazia quando a Meta avisa sem detalhar. | | `waba.restrictions[].restriction_type` | `string \| null` | sim | O tipo da restrição, no vocabulário da Meta. | | `waba.restrictions[].expiration` | `string \| null` | sim | Quando a restrição termina, como a Meta informou. Nulo quando ela não informa prazo. | | `waba.restrictions[].remediation` | `string \| null` | sim | O que a Meta diz que resolve a restrição, quando informa. | ```json { "version": "2026-11-10", "event_id": "d3b1b97cb8b69ac0bf9db087b5200febbea3dcbcc8d0a4108913592b51fdaf29", "event_type": "account.restricted", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "waba": { "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "restrictions": [ { "restriction_type": "RESTRICTED_ADD_PHONE_NUMBER_ACTION", "expiration": "2026-11-13T12:00:00Z", "remediation": null } ] } } ``` ### Violação de política na conta `account.violation` A Meta registrou uma violação de política na conta de WhatsApp Business do número. É um aviso: a conta pode ser restringida ou desativada se a violação não for tratada. Sai um evento por número da conta. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object \| null` | sim | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. | | `event_type` | `"account.violation"` | sim | | | `waba` | `object` | sim | A Meta registrou uma violação de política na conta de WhatsApp Business deste número. É um aviso: a conta pode ser restringida ou desativada se a violação não for tratada. O dono da conta lê os detalhes no WhatsApp Manager da Meta. | | `waba.waba_id` | `string` | sim | A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id. | | `waba.number_id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `waba.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. | | `waba.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. | | `waba.violation_type` | `string \| null` | sim | O tipo da violação, no vocabulário da Meta. | ```json { "version": "2026-11-10", "event_id": "a2fa828795bf24fd8e7460738c1a1e11a1bcd278fc09a0d238f92ba8c5994441", "event_type": "account.violation", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "waba": { "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "violation_type": "ALCOHOL_VIOLATION" } } ``` ### Conta desativada pela Meta `account.disabled` A Meta desativou a conta de WhatsApp Business do número, e os envios deixam de ser aceitos. A Luna não reativa conta: o dono pede revisão à Meta. Sai um evento por número da conta, e account.reinstated avisa se a conta voltar. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object \| null` | sim | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. | | `event_type` | `"account.disabled"` | sim | | | `waba` | `object` | sim | A Meta desativou a conta de WhatsApp Business deste número. Os envios param de ser aceitos. A Luna não reativa conta: o dono dela pede a revisão à Meta, e o evento account.reinstated avisa se a conta voltar. | | `waba.waba_id` | `string` | sim | A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id. | | `waba.number_id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `waba.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. | | `waba.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. | | `waba.ban_date` | `string \| null` | sim | A data da desativação, como a Meta informou. | ```json { "version": "2026-11-10", "event_id": "b0308dcc1ab6324eaea0474f1bcdec28146d3a6eb62668a1425fb3a7d6aad778", "event_type": "account.disabled", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "waba": { "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "ban_date": "2026-10-13" } } ``` ### Conta reativada pela Meta `account.reinstated` A Meta reativou a conta de WhatsApp Business do número depois de uma desativação. Sai um evento por número da conta. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object \| null` | sim | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. | | `event_type` | `"account.reinstated"` | sim | | | `waba` | `object` | sim | A Meta reativou a conta de WhatsApp Business deste número depois de uma desativação. | | `waba.waba_id` | `string` | sim | A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id. | | `waba.number_id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `waba.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. | | `waba.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. | | `waba.ban_date` | `string \| null` | sim | A data informada pela Meta junto com a reativação, quando houver. | ```json { "version": "2026-11-10", "event_id": "135a9c7b3f192a7cab5ea55f68e0a8113e8d8e80acaa0ae8dad7f20aaf61f2db", "event_type": "account.reinstated", "occurred_at": "2026-10-14T09:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "waba": { "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "ban_date": null } } ``` ### Outro aviso de conta da Meta `account.update` Um aviso de conta da Meta que a Luna não traduz em tipo próprio, com o campo event cru dela (por exemplo ACCOUNT_DELETED, ACCOUNT_RECONNECTED ou VOLUME_BASED_PRICING_TIER_UPDATE). Se você não usa, ignore. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object \| null` | sim | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. | | `event_type` | `"account.update"` | sim | | | `waba` | `object` | sim | Um aviso de conta da Meta que a Luna não traduz em um tipo próprio. Chega com o event cru da Meta para que o seu sistema decida o que fazer com ele. Se você não usa, ignore. | | `waba.waba_id` | `string` | sim | A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id. | | `waba.number_id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `waba.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. | | `waba.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. | | `waba.event` | `string` | sim | O campo event do aviso account_update da Meta, sem tradução: ACCOUNT_DELETED, ACCOUNT_RECONNECTED, VOLUME_BASED_PRICING_TIER_UPDATE, DISABLED_UPDATE com um estado que não é desativação nem reativação, e outros. Novos valores podem aparecer. | | `waba.details` | `object` | sim | O restante do aviso da Meta, como ela mandou, sem o campo event. | ```json { "version": "2026-11-10", "event_id": "f663ad9f077e865db5d29245db96fe579e9aaa487bdf2f9d91a6e535af3d7949", "event_type": "account.update", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "waba": { "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "event": "ACCOUNT_DELETED", "details": {} } } ``` ### Limite da conta mudou `account.limit_changed` A Meta mudou o limite da conta: o limite de mensagens, que conta pessoas únicas fora da janela de atendimento (TIER_250, TIER_2K, TIER_10K, TIER_100K ou TIER_UNLIMITED), ou o de números. É o teto concedido, e nunca quanto foi usado. Vale para o portfólio inteiro, então sai um evento por número da conta. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object \| null` | sim | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. | | `event_type` | `"account.limit_changed"` | sim | | | `waba` | `object` | sim | A Meta mudou o limite desta conta. O limite é do portfólio de negócio, e vale para todos os números da conta. O valor corrente de cada número está em limiteDiarioDeConversas, em GET /v1/numbers. | | `waba.waba_id` | `string` | sim | A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id. | | `waba.number_id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `waba.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. | | `waba.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. | | `waba.daily_conversation_limit` | `string \| null` | sim | O limite de mensagens da Meta, no nome de faixa dela: TIER_250, TIER_2K, TIER_10K, TIER_100K ou TIER_UNLIMITED (250, 2.000, 10.000 e 100.000 pessoas por período de 24 horas, ou sem teto). Conta pessoas únicas a quem o negócio escreve fora da janela de atendimento, e é do portfólio empresarial. É o teto concedido, e nunca quanto foi usado. Nulo quando o aviso mudou só o limite de números. | | `waba.max_phone_numbers_per_waba` | `number \| null` | sim | Quantos números a Meta permite nesta conta. Nulo quando o aviso mudou só o limite de conversas. | ```json { "version": "2026-11-10", "event_id": "a3bddf693de91539edaebb432d0d4f936b40822085cafa5c7864ae149756dbff", "event_type": "account.limit_changed", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "waba": { "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "daily_conversation_limit": "TIER_2K", "max_phone_numbers_per_waba": null } } ``` ### Número desconectado `number.disconnected` O número deixou de estar conectado à Luna: o cliente removeu o aplicativo, a Luna foi removida como parceira da conta, o vínculo da conta com a Luna foi encerrado, ou você o desconectou com DELETE /v1/numbers/{id} (reason requested_by_tenant). É o par de number.connected. Para voltar, o seu cliente conecta de novo com um novo link de conexão. Traz o motivo no campo reason. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object` | sim | O número deixou de estar conectado à Luna. É o par de number.connected. Os envios deste número não funcionam mais; para voltar, o seu cliente precisa conectar de novo, com um novo link de conexão. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. | | `number.waba_id` | `string` | sim | A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id. | | `number.reason` | `string` | sim | O motivo da desconexão: requested_by_tenant (você desconectou o número com DELETE /v1/numbers/{id}), ou o aviso da Meta que a causou, PARTNER_APP_UNINSTALLED (o cliente removeu o aplicativo), PARTNER_REMOVED (a Luna foi removida como parceira da conta) ou ACCOUNT_OFFBOARDED (o vínculo da conta com a Luna foi encerrado). Novos valores podem aparecer. | | `number.disconnection_reason` | `string \| null` | sim | O motivo que a Meta informou em disconnection_info, quando informa. | | `number.initiated_by` | `string \| null` | sim | Quem iniciou a desconexão, como a Meta informou. | | `event_type` | `"number.disconnected"` | sim | | ```json { "version": "2026-11-10", "event_id": "0dfe4e31d4e40e4a5da6d3f42f0d44b660f67ce551b2a43966e5fb0390fcd741", "event_type": "number.disconnected", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "waba_id": "102290129340398", "reason": "PARTNER_APP_UNINSTALLED", "disconnection_reason": null, "initiated_by": null } } ``` ### Qualidade do número mudou `number.quality_changed` A avaliação de qualidade do número mudou (GREEN, YELLOW, RED). A Meta não tem webhook para isso: a Luna confere a qualidade periodicamente, então o evento chega com atraso de até cerca de uma hora. O histórico está em GET /v1/numbers/{id}/health. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object` | sim | A avaliação de qualidade do número mudou. A Meta não tem webhook para isso: a Luna confere a qualidade de cada número periodicamente, então o evento chega com atraso de até a cadência da conferência (cerca de uma hora). O histórico está em GET /v1/numbers/{id}/health. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. | | `number.waba_id` | `string` | sim | A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id. | | `number.previous_quality_rating` | `string` | sim | A avaliação de qualidade anterior, no vocabulário da Meta: GREEN, YELLOW, RED. | | `number.quality_rating` | `string` | sim | A avaliação de qualidade atual, no vocabulário da Meta. | | `event_type` | `"number.quality_changed"` | sim | | ```json { "version": "2026-11-10", "event_id": "cc81de4eb28ad6a80e39c6cca13eb4b6db12f223f3c1346552cbc24795bcdbbe", "event_type": "number.quality_changed", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "waba_id": "102290129340398", "previous_quality_rating": "GREEN", "quality_rating": "YELLOW" } } ``` ### Nome de exibição revisado `number.display_name_reviewed` O estado da revisão do nome de exibição do número mudou (status: approved, pending_review, declined, expired ou none), por exemplo de pending_review para approved ou declined. name é o nome a que o estado se refere. A Meta não informa o motivo de uma recusa nesta consulta. A Luna confere o nome periodicamente, então o evento chega com atraso de até cerca de uma hora. Um nome aprovado só passa a valer depois que o número é registrado de novo. O estado corrente está em displayNameStatus, em GET /v1/numbers/{id}. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object` | sim | O estado da revisão do nome de exibição do número mudou, por exemplo de pending_review para approved ou declined. A Luna confere o nome de cada número periodicamente, então o evento chega com atraso de até cerca de uma hora. Um nome aprovado só passa a valer depois que o número é registrado de novo; o estado corrente está em displayNameStatus, em GET /v1/numbers/{id}. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. | | `number.waba_id` | `string` | sim | A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id. | | `number.status` | `string` | sim | O estado da revisão do nome de exibição, o mesmo de displayNameStatus em GET /v1/numbers/{id}: approved, pending_review, declined, expired ou none. Novos valores podem aparecer. | | `number.name` | `string \| null` | sim | O nome a que o estado se refere: o nome pedido, quando há um pedido, senão o nome em uso. Nulo quando a Meta não informou. | | `event_type` | `"number.display_name_reviewed"` | sim | | ```json { "version": "2026-11-10", "event_id": "23fd01fabc59f4c9ffda20955726e7e3e19c6a05cf609197c8b3c0aef8405e76", "event_type": "number.display_name_reviewed", "occurred_at": "2026-11-04T14:20:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "waba_id": "102290129340398", "status": "declined", "name": "Clínica Sorriso Centro" } } ``` ### Autorização do cliente perto de vencer `number.credential_expiring` A autorização que o cliente deu à Luna para operar o número vence em até 14 dias (credential_expires_at). Para renovar, o cliente refaz a conexão: crie um link com POST /v1/onboarding/links informando numberId e ele abre direto a reconexão deste número, sem contar um número novo. Sai uma vez por vencimento e por número da conta. Autorização emitida sem prazo nunca gera este evento. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object` | sim | A autorização que o cliente deu à Luna para operar este número vence em até 14 dias. Para renovar, o seu cliente refaz a conexão: abra um link com POST /v1/onboarding/links informando numberId, e ele cai direto na reconexão deste número, sem contar um número novo. O evento sai uma vez por vencimento e por número, e não se repete a cada dia. Se a autorização foi emitida sem prazo, ele não sai nunca. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. | | `number.waba_id` | `string` | sim | A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id. | | `number.credential_expires_at` | `string` | sim | Quando a autorização que o cliente deu à Luna vence, em ISO-8601 UTC. É o mesmo valor que GET /v1/business-accounts devolve em credentialExpiresAt. Depois dessa data a Meta recusa as chamadas da Luna nesta conta, e o número para de enviar e de receber. | | `event_type` | `"number.credential_expiring"` | sim | | ```json { "version": "2026-11-10", "event_id": "33b03111fe7f1f225626ece55b50955389e78742a6b99059f05be056ce2b2260", "event_type": "number.credential_expiring", "occurred_at": "2026-11-21T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "waba_id": "102290129340398", "credential_expires_at": "2026-12-05T12:00:00.000Z" } } ``` ### Alerta da Meta sobre a conta `account.alert` A Meta mandou um alerta sobre a conta de WhatsApp Business do número (o campo account_alerts), por exemplo a negativa de um aumento de limite ou a perda da foto de perfil. Os campos chegam como a Meta mandou, sem tradução. O alerta é da conta: sai um evento por número conectado dela, todos com o mesmo waba_id. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object \| null` | sim | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. | | `event_type` | `"account.alert"` | sim | | | `waba` | `object` | sim | A Meta mandou um alerta sobre a conta de WhatsApp Business deste número (o campo account_alerts). Os campos chegam como a Meta mandou, sem tradução. O alerta é da conta: sai um evento por número conectado dela, todos com o mesmo waba_id. Quem resolve é o dono da conta, no WhatsApp Manager da Meta. | | `waba.waba_id` | `string` | sim | A conta de WhatsApp Business na Meta (WABA) a que o aviso se refere. O aviso é da conta inteira: a Luna entrega um evento por número conectado dela, todos com o mesmo waba_id. | | `waba.number_id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `waba.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. | | `waba.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. | | `waba.entity_type` | `string \| null` | sim | A que o alerta se refere, como a Meta informou (por exemplo a conta, o portfólio ou um número). | | `waba.entity_id` | `string \| null` | sim | O identificador, na Meta, do que o alerta cita. | | `waba.alert_severity` | `string \| null` | sim | A gravidade que a Meta atribuiu ao alerta, no vocabulário dela. | | `waba.alert_status` | `string \| null` | sim | Se o alerta está ativo ou foi resolvido, no vocabulário da Meta. | | `waba.alert_type` | `string \| null` | sim | O tipo do alerta, no vocabulário da Meta: por exemplo INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED, INCREASED_CAPABILITIES_ELIGIBILITY_FAILED, INCREASED_CAPABILITIES_ELIGIBILITY_NEED_MORE_INFO ou PROFILE_PICTURE_LOST. Novos valores podem aparecer. | | `waba.alert_description` | `string \| null` | sim | A descrição do alerta, em texto, como a Meta mandou. | | `waba.details` | `object` | sim | O restante do alerta, como a Meta mandou, para o que a Luna ainda não nomeia. | ```json { "version": "2026-11-10", "event_id": "fb613a0660724669d9251d4185488ec26409b34345c592b908ce9747b8430f99", "event_type": "account.alert", "occurred_at": "2026-10-19T12:00:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "external_id": "cliente-8841" }, "waba": { "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "entity_type": "WABA", "entity_id": "102290129340398", "alert_severity": "INFORMATIONAL", "alert_status": "ACTIVE", "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED", "alert_description": "Messaging limit increase deferred.", "details": {} } } ``` ### Número precisa de ação `number.action_required` Este número passou a precisar de uma ação sua ou do seu cliente: autorização do cliente vencendo ou vencida, método de pagamento ausente na Meta, conta restrita ou desativada, PIN pedido, registro bloqueado ou plano suspenso. Traz status, can_send e reasons, cada motivo com code, message e solution, prontos para você mostrar ao seu cliente. Sai quando a lista de motivos passa de vazia para não vazia, e não a cada mudança dela; é o mesmo cálculo de connection em GET /v1/numbers/{id}. Quando a lista esvazia, sai number.action_resolved. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object` | sim | Este número passou a precisar de uma ação sua ou do seu cliente: autorização vencendo ou vencida, método de pagamento ausente na Meta, conta restrita ou desativada, PIN pedido, registro bloqueado ou plano suspenso. Sai quando a lista de motivos passa de vazia para não vazia, e não a cada mudança dela. Mostra o motivo ao seu cliente com message e solution. Quando a lista esvazia, sai number.action_resolved. O estado corrente está em connection, em GET /v1/numbers/{id}. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. | | `number.status` | `string` | sim | O estado resumido da conexão, o mesmo de connection.status em GET /v1/numbers/{id}. · Valores: connected, connecting, action_required, disconnected | | `number.can_send` | `boolean` | sim | Se o envio por este número vai funcionar agora, o mesmo de connection.canSend. | | `number.reasons` | `array` | sim | Os motivos, os mesmos de connection.reasons em GET /v1/numbers/{id}, no instante do evento. · no mínimo 1 itens | | `number.reasons[].code` | `string` | sim | O código do motivo, para o seu código comparar: pin_required, registration_blocked, credential_invalid, credential_expired, credential_expiring, payment_required, payment_method_missing, account_restricted, account_disabled, trial_expired, account_blocked. Novos códigos podem aparecer. | | `number.reasons[].message` | `string` | sim | O que está acontecendo, em português, pronto para repassar ao seu cliente. | | `number.reasons[].solution` | `string` | sim | O que fazer a respeito, em português. | | `event_type` | `"number.action_required"` | sim | | ```json { "version": "2026-11-10", "event_id": "8832cdd12544436fce3b39d709158baa046091d010b5ed144a289c81b807c710", "event_type": "number.action_required", "occurred_at": "2026-10-28T15:02:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "status": "action_required", "can_send": false, "reasons": [ { "code": "payment_required", "message": "A Meta recusou um envio deste número por falta de método de pagamento na conta de WhatsApp Business do negócio.", "solution": "O dono da conta cadastra o método de pagamento no WhatsApp Manager da Meta. A Luna não intermedeia esse pagamento. Quando um envio voltar a ser aceito, o aviso sai do ar." } ] } } ``` ### Número não precisa mais de ação `number.action_resolved` O número deixou de precisar de ação: a lista de motivos de connection esvaziou, depois de um number.action_required. É o par dele, como number.payment_resolved é o de number.payment_required. status diz como a conexão ficou. Um número que você desconectou não gera este evento: number.disconnected já avisou. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object` | sim | Este número não precisa mais de ação: a lista de motivos de connection esvaziou, depois de um number.action_required. É o par dele, como number.payment_resolved é o de number.payment_required. status diz como a conexão ficou (connected, ou connecting se a conexão voltou a estar em curso). | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele ao criar o link de conexão (externalId em POST /v1/onboarding/links). Nulo quando o número foi conectado sem link. | | `number.status` | `string` | sim | O estado resumido da conexão, o mesmo de connection.status em GET /v1/numbers/{id}. · Valores: connected, connecting, action_required, disconnected | | `number.can_send` | `boolean` | sim | Se o envio por este número vai funcionar agora, o mesmo de connection.canSend. | | `event_type` | `"number.action_resolved"` | sim | | ```json { "version": "2026-11-10", "event_id": "3279de99ef1bc2ade5d88bde7a2fd878b8faabddc179b8dceebded74d5b7394b", "event_type": "number.action_resolved", "occurred_at": "2026-10-28T15:40:00.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "status": "connected", "can_send": true } } ``` ### Link de conexão concluído `onboarding.link.completed` O seu cliente concluiu a conexão por um link: o link passa a used. Traz o externalId do link e, quando a Luna já registrou o número, number_id; o evento number.connected avisa quando o número fica pronto para enviar. Sai uma vez por link. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string \| null` | sim | O número do link de reconexão ou o que resultou da conexão, ou null quando o evento não tem número. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object \| null` | sim | O número que resultou da conexão, no mesmo formato dos eventos number.*, com waba_id. Nulo quando a conta foi conectada sem número, ou quando a Luna ainda não o registrou: o evento number.connected avisa quando ele fica pronto. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.display_number` | `string \| null` | sim | O número de telefone, como a Meta o exibe. Nulo quando a Meta ainda não o informou. | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. | | `number.waba_id` | `string` | sim | A conta de WhatsApp Business na Meta (WABA) a que o número pertence, o mesmo id que GET /v1/business-accounts devolve em wabaId. | | `event_type` | `"onboarding.link.completed"` | sim | | | `link` | `object` | sim | O seu cliente concluiu a conexão por um link: ele aceitou os termos da Meta e a Luna recebeu o acesso à conta dele. É o fim do link, que passa a used. O número pode ainda estar sendo registrado: quem avisa que ele ficou pronto para enviar é number.connected. Sai uma vez por link. | | `link.id` | `string (uuid)` | sim | O identificador do link, o mesmo que POST /v1/onboarding/links devolveu. | | `link.external_id` | `string \| null` | sim | O externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele. | | `link.used_at` | `string` | sim | Quando a conexão por este link concluiu, o mesmo usedAt de GET /v1/onboarding/links/{id}. | | `link.waba_id` | `string \| null` | sim | A conta de WhatsApp Business que o seu cliente conectou, o mesmo id que GET /v1/business-accounts devolve em wabaId. Está preenchido mesmo quando a conta foi conectada sem número (number_id nulo). Nulo só se a Luna não a leu. | | `link.number_id` | `string (uuid) \| null` | sim | O número que resultou da conexão, o mesmo id de GET /v1/numbers. Nulo quando a conta foi conectada sem número, ou quando a Luna ainda não o registrou: o evento number.connected avisa quando ele fica pronto. | ```json { "version": "2026-11-10", "event_id": "fd3596b2273541c7a77c69cb8a2ddb0e060052ddc84f251b5a76961053b578b1", "event_type": "onboarding.link.completed", "occurred_at": "2026-10-28T15:30:12.000Z", "phone_number_id": "123456789012345", "number": { "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b", "phone_number_id": "123456789012345", "display_number": "+55 11 90000-0000", "external_id": "cliente-8841", "waba_id": "102290129340398" }, "link": { "id": "7c3e5a19-2b4d-4f60-8a1e-9d0b3c5f7a21", "external_id": "cliente-8841", "used_at": "2026-10-28T15:30:12.000Z", "waba_id": "102290129340398", "number_id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b" } } ``` ### Link de conexão aberto `onboarding.link.opened` O seu cliente abriu o link pela primeira vez. Sai uma vez por link, e não de novo quando ele volta à página ou tenta outra vez. Traz o externalId do link e opened_at. É o começo do ciclo: depois vêm onboarding.link.completed, onboarding.link.failed ou onboarding.link.expired. Quem abriu e nunca concluiu aparece aqui sem um completed. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string \| null` | sim | O número do link de reconexão, ou null quando o link é de uma conexão nova. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object \| null` | sim | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. | | `event_type` | `"onboarding.link.opened"` | sim | | | `link` | `object` | sim | O seu cliente abriu o link pela primeira vez. Sai uma vez por link, na primeira abertura, e não de novo quando ele volta à página ou tenta outra vez. É o começo do ciclo: depois dele vêm onboarding.link.completed, onboarding.link.failed ou onboarding.link.expired. Quem abriu e nunca concluiu aparece aqui sem um completed. | | `link.id` | `string (uuid)` | sim | O identificador do link, o mesmo que POST /v1/onboarding/links devolveu. | | `link.external_id` | `string \| null` | sim | O externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele. | | `link.opened_at` | `string` | sim | Quando o seu cliente abriu o link pela primeira vez. | ```json { "version": "2026-11-10", "event_id": "b8a277c5c9377c213ee4c3b79c3e83829f3bef5f69521db1a0434da05acfbc1d", "event_type": "onboarding.link.opened", "occurred_at": "2026-10-28T15:21:40.000Z", "phone_number_id": null, "number": null, "link": { "id": "7c3e5a19-2b4d-4f60-8a1e-9d0b3c5f7a21", "external_id": "cliente-8841", "opened_at": "2026-10-28T15:21:40.000Z" } } ``` ### Tentativa de conexão pelo link não deu certo `onboarding.link.failed` Uma tentativa de conexão por um link não deu certo. reason diz por quê: abandoned (o cliente fechou a janela da Meta, e step traz a tela em que parou), error (a janela da Meta relatou um erro, em error_code), failed (a Luna tentou concluir e não conseguiu), country_not_supported (o número não é +55) ou registration_blocked (a Meta bloqueou o registro por 72 horas). O link continua aberto até vencer. Sai uma vez por tentativa. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string \| null` | sim | O número do link de reconexão, ou null quando o link é de uma conexão nova. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object \| null` | sim | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. | | `event_type` | `"onboarding.link.failed"` | sim | | | `link` | `object` | sim | Uma tentativa de conexão por um link não deu certo: o cliente desistiu em alguma tela, a janela da Meta relatou um erro, ou a conexão parou. O link continua aberto até vencer, e o cliente pode tentar de novo. Sai uma vez por tentativa. O que o cliente deve fazer para cada reason está no guia Conectar um número. | | `link.id` | `string (uuid)` | sim | O identificador do link, o mesmo que POST /v1/onboarding/links devolveu. | | `link.external_id` | `string \| null` | sim | O externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele. | | `link.session_id` | `string (uuid)` | sim | A tentativa de conexão que não deu certo. Um link aberto admite várias. | | `link.reason` | `string` | sim | Por que a tentativa não deu certo: abandoned (o cliente fechou a janela da Meta e a tela em que parou está em step), error (a janela da Meta relatou um erro, em error_code), failed (a Luna tentou concluir várias vezes e não conseguiu), country_not_supported (o número escolhido não é +55) ou registration_blocked (a Meta bloqueou o registro do número por 72 horas). Novos motivos podem aparecer. · Valores: abandoned, error, failed, country_not_supported, registration_blocked | | `link.step` | `string \| null` | sim | O nome da tela da janela da Meta em que o cliente parou, como o navegador relatou. Nulo quando não foi relatado. | | `link.error_code` | `integer \| null` | sim | O código de erro que a janela da Meta relatou. Nulo quando não houve erro relatado. | ```json { "version": "2026-11-10", "event_id": "cabf3f3478bda2efd0e9a3726d503dbcd575bec16cc0ccf5fc65cdcb4c88cea3", "event_type": "onboarding.link.failed", "occurred_at": "2026-10-28T15:12:40.000Z", "phone_number_id": null, "number": null, "link": { "id": "7c3e5a19-2b4d-4f60-8a1e-9d0b3c5f7a21", "external_id": "cliente-8841", "session_id": "2e8f4b60-1a3c-4d57-9b0e-6c7d8e9f0a12", "reason": "abandoned", "step": "phone_number_setup", "error_code": null } } ``` ### Link de conexão venceu `onboarding.link.expired` O link venceu sem ninguém concluir a conexão. Gere outro com POST /v1/onboarding/links quando quiser. Um link usado nunca gera este evento. Sai uma vez por link. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `string \| null` | sim | O número do link de reconexão, ou null quando o link é de uma conexão nova. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `object \| null` | sim | O número por onde o evento passou: id da Luna, phone_number_id da Meta e external_id, o rótulo que o seu sistema deu ao cliente. Está em todo evento que passa por um número, para você separar os eventos de N clientes com um endpoint só. Nos eventos number.* este mesmo objeto traz também os campos próprios do evento. Nulo nos eventos que não passam por número. | | `number.id` | `string (uuid)` | sim | O identificador do número na Luna, o mesmo que GET /v1/numbers devolve. | | `number.phone_number_id` | `string` | sim | O identificador do número na Meta, o mesmo que a listagem de números devolve. · 1 a 64 caracteres · /^[A-Za-z0-9_-]+$/ | | `number.external_id` | `string \| null` | sim | O rótulo que o seu sistema deu ao cliente dele (externalId no link de conexão ou em PATCH /v1/numbers/{id}). Nulo quando o número não tem rótulo. É com ele que um endpoint só separa os eventos de todos os seus clientes. | | `event_type` | `"onboarding.link.expired"` | sim | | | `link` | `object` | sim | O link venceu sem ninguém concluir a conexão. Gere outro com POST /v1/onboarding/links quando quiser. Um link que foi usado nunca gera este evento. Sai uma vez por link. | | `link.id` | `string (uuid)` | sim | O identificador do link, o mesmo que POST /v1/onboarding/links devolveu. | | `link.external_id` | `string \| null` | sim | O externalId que você deu ao criar o link, sem alteração. Nulo quando o link foi criado sem ele. | | `link.expired_at` | `string` | sim | Quando o link venceu, o mesmo expiresAt de GET /v1/onboarding/links/{id}. | ```json { "version": "2026-11-10", "event_id": "1df73af80cf86f74267290bc13fcd1f82551997dd79845170b35c78f40b563ad", "event_type": "onboarding.link.expired", "occurred_at": "2026-10-31T15:00:00.000Z", "phone_number_id": null, "number": null, "link": { "id": "7c3e5a19-2b4d-4f60-8a1e-9d0b3c5f7a21", "external_id": "cliente-8841", "expired_at": "2026-10-31T15:00:00.000Z" } } ``` ### Categoria de um template mudou `template.category` A Meta mudou, ou avisou que vai mudar, a categoria de um template. A categoria define o preço que a Meta cobra do negócio: de UTILITY para MARKETING, o preço sobe. Chega como aviso prévio (correct_category e scheduled_for) e como mudança feita (previous_category e new_category). Não tem número nem mensagem. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `null` | sim | Sempre null neste tipo: o template pertence à conta de negócio, e não a um número. | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `null` | sim | Sempre null neste tipo: o evento não passa por um número. | | `event_type` | `"template.category"` | sim | | | `template` | `object` | sim | A Meta mudou, ou vai mudar, a categoria de um template. Chega de duas formas: o aviso prévio (correct_category e scheduled_for preenchidos) e a mudança feita (previous_category e new_category preenchidos). A categoria define o preço que a Meta cobra do negócio por mensagem: de UTILITY para MARKETING, o preço sobe. Quem paga é o dono da conta, direto à Meta. | | `template.id` | `string (uuid)` | sim | O identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem. | | `template.name` | `string` | sim | O nome do template. | | `template.language` | `string` | sim | O idioma do template, no código da Meta. | | `template.waba_id` | `string` | sim | A conta de WhatsApp Business na Meta (WABA) a que o template pertence, o mesmo id que GET /v1/business-accounts devolve em wabaId. | | `template.external_id` | `string \| null` | sim | O rótulo do cliente dono do template (o externalId que o seu sistema deu ao conectar o número). É o rótulo dos números da conta quando todos eles têm o mesmo. Nulo quando a conta tem números de clientes diferentes, quando algum número dela não tem rótulo e quando ela não tem número conectado: nesses casos, ligue o evento ao cliente por waba_id (GET /v1/business-accounts). | | `template.category` | `string` | sim | A categoria do template, no vocabulário da Meta. | | `template.previous_category` | `string \| null` | sim | A categoria de antes, quando a mudança já foi feita. Nulo no aviso prévio. | | `template.new_category` | `string \| null` | sim | A categoria de agora, quando a mudança já foi feita. Nulo no aviso prévio. | | `template.correct_category` | `string \| null` | sim | No aviso prévio, a categoria para a qual a Meta vai mudar o template. Nulo quando a mudança já foi feita. | | `template.scheduled_for` | `string \| null` | sim | No aviso prévio, quando a Meta aplica a mudança. Nulo quando a mudança já foi feita. | ```json { "version": "2026-11-10", "event_id": "67e825cdeb1f139ea3f76761c2e087a272352caca49dea9ab471383293a8ca07", "event_type": "template.category", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": null, "number": null, "template": { "id": "3f6a1c52-9d4e-4b87-a1f0-5e2c7b9d8a14", "name": "pedido_confirmado", "language": "pt_BR", "waba_id": "102290129340398", "external_id": "cliente-8841", "category": "UTILITY", "previous_category": null, "new_category": null, "correct_category": "MARKETING", "scheduled_for": "2026-10-14T17:46:40.000Z" } } ``` ```json { "version": "2026-11-10", "event_id": "a088e870f11e399bc1d40266c5d07e18d0b13da6d1cf4d2021cbb232451ed86d", "event_type": "template.category", "occurred_at": "2026-10-14T17:46:40.000Z", "phone_number_id": null, "number": null, "template": { "id": "3f6a1c52-9d4e-4b87-a1f0-5e2c7b9d8a14", "name": "pedido_confirmado", "language": "pt_BR", "waba_id": "102290129340398", "external_id": "cliente-8841", "category": "MARKETING", "previous_category": "UTILITY", "new_category": "MARKETING", "correct_category": null, "scheduled_for": null } } ``` ### Qualidade de um template mudou `template.quality` A nota de qualidade de um template mudou (GREEN, YELLOW, RED). Nota baixa antecede a pausa do template pela Meta. Não tem número nem mensagem. | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `version` | `"2026-11-10"` | sim | A versão deste contrato. Ela sobe apenas com aviso e prazo, e um tipo novo de evento não a faz subir. | | `event_id` | `string` | sim | O identificador estável deste evento. Use-o para descartar repetições. · 64 a 64 caracteres | | `occurred_at` | `string` | sim | Quando o evento ocorreu, em UTC. | | `phone_number_id` | `null` | sim | Sempre null neste tipo: o template pertence à conta de negócio, e não a um número. | | `test` | `true` | não | Presente, e true, só no exemplo que POST /v1/webhooks/endpoints/{id}/test entrega quando você pede um eventType, e nos eventos simulados do modo de teste (chave com mode test e POST /v1/test-mode/inbound-messages): o corpo é de mentira, com identificadores que não existem. Ausente em todo evento de verdade. Se o seu código age sobre o evento, confira este campo antes. | | `number` | `null` | sim | Sempre null neste tipo: o evento não passa por um número. | | `event_type` | `"template.quality"` | sim | | | `template` | `object` | sim | A nota de qualidade de um template mudou. Nota baixa antecede a pausa do template pela Meta: é o momento de revisar o conteúdo ou o público. | | `template.id` | `string (uuid)` | sim | O identificador do template na Luna, o mesmo que POST /v1/templates e GET /v1/templates devolvem. | | `template.name` | `string` | sim | O nome do template. | | `template.language` | `string` | sim | O idioma do template, no código da Meta. | | `template.waba_id` | `string` | sim | A conta de WhatsApp Business na Meta (WABA) a que o template pertence, o mesmo id que GET /v1/business-accounts devolve em wabaId. | | `template.external_id` | `string \| null` | sim | O rótulo do cliente dono do template (o externalId que o seu sistema deu ao conectar o número). É o rótulo dos números da conta quando todos eles têm o mesmo. Nulo quando a conta tem números de clientes diferentes, quando algum número dela não tem rótulo e quando ela não tem número conectado: nesses casos, ligue o evento ao cliente por waba_id (GET /v1/business-accounts). | | `template.previous_quality_score` | `string \| null` | sim | A nota de qualidade de antes, no vocabulário da Meta: GREEN, YELLOW, RED, UNKNOWN. | | `template.new_quality_score` | `string \| null` | sim | A nota de qualidade de agora, no vocabulário da Meta. | ```json { "version": "2026-11-10", "event_id": "8624296410fe8b7631164b57d667847f22145595d3bac4ae644e32930aab9321", "event_type": "template.quality", "occurred_at": "2026-10-13T12:00:00.000Z", "phone_number_id": null, "number": null, "template": { "id": "3f6a1c52-9d4e-4b87-a1f0-5e2c7b9d8a14", "name": "pedido_confirmado", "language": "pt_BR", "waba_id": "102290129340398", "external_id": "cliente-8841", "previous_quality_score": "GREEN", "new_quality_score": "YELLOW" } } ``` ## Erros | Status HTTP | Descrição | | --- | --- | | `400` | O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa. | | `401` | A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. | | `403` | A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed. | | `404` | O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. | | `409` | O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. | | `410` | O link de conexão venceu ou já foi usado. O campo error diz qual dos dois. | | `413` | O arquivo passa do teto de tamanho, que é o mesmo para todos os clientes. | | `415` | O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. | | `422` | O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa. | | `429` | Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key. | | `503` | A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver. | | Código do erro (error) | Status HTTP | Quando acontece | | --- | --- | --- | | `invalid_request` | 400 | Campo recusado, com o motivo | | `invalid_reset_token` | 400 | Link de redefinição inválido | | `unauthorized` | 401 | Chave recusada | | `account_blocked` | 403 | Conta bloqueada pela Helsen | | `connection_not_released` | 403 | Conta ainda sem liberação para conectar | | `forbidden` | 403 | Escopo insuficiente | | `test_key_not_allowed` | 403 | Chave de teste numa rota que não é do modo de teste | | `trial_expired` | 403 | Teste grátis terminado | | `not_found` | 404 | Não existe, ou não é seu | | `account_at_capacity` | 409 | A conta que pediu o link atingiu o máximo de números | | `already_requeued` | 409 | Item já re-enfileirado | | `idempotency_key_reused` | 409 | Idempotency-Key usada com outro corpo | | `link_not_open` | 409 | Link que não está aberto | | `media_not_ready` | 409 | Mídia ainda não obtida | | `message_not_cancelable` | 409 | Mensagem que já saiu da fila | | `no_webhook_endpoint` | 409 | Sem endpoint de webhook ativo | | `not_available_in_coexistence` | 409 | Indisponível em coexistência | | `number_capacity_reached` | 409 | A conta já está na capacidade de números | | `number_disconnected` | 409 | Número desconectado da Luna | | `pin_not_applicable` | 409 | O número não pede PIN | | `reconnect_not_applicable` | 409 | A autorização não admite reconexão | | `register_budget_reserved` | 409 | Tentativas de registro reservadas | | `template_content_unknown` | 409 | A Luna não conhece o conteúdo do template | | `template_not_approved` | 409 | Template que ainda não está aprovado | | `webhook_endpoint_limit` | 409 | Limite de endpoints | | `window_closed` | 409 | Janela de atendimento fechada | | `link_expired` | 410 | Link vencido | | `link_used` | 410 | Link já usado | | `file_too_large` | 413 | Arquivo acima do teto | | `unsupported_media_type` | 415 | Tipo de conteúdo não lido | | `meta_rejected` | 422 | A Meta recusou a operação | | `management_busy` | 429 | Gestão da conta ocupada | | `number_rate_limited` | 429 | Ritmo do número | | `queue_full` | 429 | Fila de envio cheia | | `rate_limited` | 429 | Limite de requisições | | `unavailable` | 503 | Indisponível |