# Luna > Luna is a WhatsApp messaging API built on Meta’s official WhatsApp Cloud API, operated by Helsen as an approved Tech Provider. Luna é uma API de mensageria para WhatsApp, construída sobre a WhatsApp Cloud API oficial da Meta. The documentation is in Portuguese and English. ## Guias de integração - [Documentação da Luna](https://lunahia.com.br/docs.md): Guias para integrar a API da Luna: criar a conta, conectar um número, receber eventos, enviar mensagens e usar templates. - [Primeiros passos](https://lunahia.com.br/docs/primeiros-passos.md): De uma conta nova na Luna a uma mensagem enviada e a um evento recebido, com exemplos em curl, Node e Python. - [Conta e chaves](https://lunahia.com.br/docs/conta-e-chaves.md): Cadastrar a conta, entrar, confirmar a senha, 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.md): Como conectar um número novo, um número que continua no aplicativo WhatsApp Business do celular (coexistência) e um número que vem de outro provedor. - [SaaS com N clientes](https://lunahia.com.br/docs/saas-com-n-clientes.md): O caminho completo de um produto que contrata um plano de números e dá WhatsApp aos clientes dele: um link por cliente com externalId, os eventos de todos num endpoint só, a chave e o webhook por cliente, o estado de cada número, desconectar e a capacidade do plano. Com código que roda. - [Plano e números](https://lunahia.com.br/docs/plano-e-numeros.md): O teste grátis, a capacidade de números do plano, como ler o seu uso em GET /v1/subscription, o erro 409 number_capacity_reached, como desconectar e reconectar um número, e o que acontece quando o teste termina. - [Receber eventos](https://lunahia.com.br/docs/receber-eventos.md): Como cadastrar o endpoint de webhook, todos os tipos de evento, como separar os eventos de cada cliente seu, como mudar a URL, pausar, testar e remover, as garantias de entrega, retentativas, reenvio e a verificação da assinatura, com código que funciona. - [Enviar mensagens](https://lunahia.com.br/docs/enviar-mensagens.md): Cada tipo de mensagem que a API da Luna aceita, a janela de 24 horas, quando um template é obrigatório, idempotência e como acompanhar a entrega. - [Agente de IA: o laço completo](https://lunahia.com.br/docs/agente-de-ia.md): O laço de um agente que atende no WhatsApp, inteiro e em código que roda colando (Python só com a biblioteca padrão, e Node só com o fetch): verificar, deduplicar, responder 200, marcar como lida, mostrar digitando, responder com chave de idempotência determinística e cair para template. - [Usuários sem telefone (BSUID)](https://lunahia.com.br/docs/usuarios-sem-telefone.md): O que muda quando o usuário do WhatsApp escreve sem que o telefone apareça: o BSUID nos eventos e nas listagens, o wa_id que pode ser nulo, como responder com recipient, a troca de telefone ou de BSUID e o que a Luna não consegue fazer. - [O que o número faz na Meta](https://lunahia.com.br/docs/numero-na-meta.md): Perfil do negócio, usuários bloqueados, QR code com link curto e o aviso de que um contato pediu para parar de receber marketing: as rotas, o que a Meta recusa, o que não vale em coexistência e o que ainda está a confirmar. - [Modo de teste](https://lunahia.com.br/docs/modo-de-teste.md): Uma chave de teste que envia mensagem sem ir à Meta e entrega ao seu webhook os estados simulados, assinados e marcados com test true: como criar, o que sai, o que não é simulado. - [SDK e n8n](https://lunahia.com.br/docs/sdk-e-n8n.md): 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 existe do SDK Node/TypeScript e do nó próprio do n8n, que ainda não estão publicados. - [Use a documentação no seu editor (MCP)](https://lunahia.com.br/docs/mcp.md): Conecte o Claude Code, o Cursor, o VS Code, o Claude ou o ChatGPT à documentação da Luna por um servidor MCP público: a IA lê os guias e o contrato exato de cada rota, sempre na versão publicada. - [Templates](https://lunahia.com.br/docs/templates.md): Como criar um template, acompanhar o estado, usar cabeçalho de mídia e por que aprovado não quer dizer liberado para disparo. - [Erros](https://lunahia.com.br/docs/erros.md): O formato do erro da API da Luna, os códigos principais com o que fazer em cada um, e os cabeçalhos do limite de requisições. - [Limites e ritmo](https://lunahia.com.br/docs/limites-e-ritmo.md): Até onde você pode ir e o que acontece quando passa: o limite de requisições, a rajada de cada conversa, o ritmo por número, a fila de envio, o limite diário de conversas da Meta e os demais tetos, com os números. - [Saúde da conta](https://lunahia.com.br/docs/saude-da-conta.md): Os avisos da Meta sobre a conta de WhatsApp Business do seu cliente (restrição, violação, desativação, desconexão, limite, qualidade e alerta), o aviso da Luna de que a autorização do cliente vai vencer, o que cada evento significa e o que o seu sistema faz em cada caso. - [Pagamento na Meta](https://lunahia.com.br/docs/pagamento-na-meta.md): O que acontece quando o negócio dono do número não tem método de pagamento na Meta, como detectar pela API e por evento, o que dizer ao seu cliente e como saber que voltou. - [Custos da Meta](https://lunahia.com.br/docs/custos-da-meta.md): Quem cobra o quê, o que a Meta cobra pelo uso do WhatsApp desde 1º de outubro de 2026 e onde conferir o que foi cobrado. - [Vindo da Z-API ou da Evolution API](https://lunahia.com.br/docs/migrar-de-api-nao-oficial.md): De-para de autenticação, envio, eventos e estados para quem migra da Z-API ou da Evolution API, e o que não existe na API oficial do WhatsApp, com a razão de cada ausência. - [Vindo da Twilio](https://lunahia.com.br/docs/migrar-da-twilio.md): De-para de envio, template, estado, assinatura do webhook e códigos de erro para quem migra o WhatsApp da Twilio para a Luna, e o que não existe aqui. - [Vindo de outro parceiro oficial (360dialog, Gupshup)](https://lunahia.com.br/docs/migrar-de-outro-parceiro.md): De-para de autenticação, onboarding de clientes, eventos, templates e consumo para quem opera clientes por outro parceiro oficial da Meta, e como mover um número com o PIN. - [Glossário](https://lunahia.com.br/docs/glossario.md): Os termos da documentação em linguagem simples: janela de 24 horas, template, idempotência, BSUID, webhook, assinatura, wamid, externalId, event_id e corpo bruto. - [Vindo da Z-API ou da Evolution: migrar para a Luna](https://lunahia.com.br/migrar-da-evolution-api): O que muda no modelo, como o ciclo de vida da instância vira número, link, chave e webhook por cliente, o mapa de capacidade a capacidade, e o que não tem equivalente, com a razão de cada ausência. ## Integration guides (English) - [Luna documentation](https://lunahia.com.br/en/docs.md): Guides to integrate the Luna API: create an account, connect a number, receive events, send messages and use templates. - [Quickstart](https://lunahia.com.br/en/docs/quickstart.md): From a new Luna account to a sent message and a received event, with examples in curl, Node and Python. - [Account and keys](https://lunahia.com.br/en/docs/account-and-keys.md): Sign up, log in, confirm the password, create and revoke API keys, the scopes, and read the account, the plan and the state of the platform, all with curl. - [Connect a number](https://lunahia.com.br/en/docs/connect-a-number.md): How to connect a new number, a number that stays on the WhatsApp Business app on the phone (coexistence), and a number coming from another provider. - [SaaS with N customers](https://lunahia.com.br/en/docs/saas-with-n-customers.md): The complete path of a product that subscribes to a plan of numbers and gives its customers WhatsApp: one link per customer with externalId, everyone’s events on a single endpoint, the key and the webhook per customer, each number’s state, disconnecting and the plan capacity. With code that runs. - [Plan and numbers](https://lunahia.com.br/en/docs/plan-and-numbers.md): The free trial, the plan’s number capacity, how to read your usage at GET /v1/subscription, the 409 number_capacity_reached error, how to disconnect and reconnect a number, and what happens when the trial ends. - [Receive events](https://lunahia.com.br/en/docs/receive-events.md): How to register the webhook endpoint, all the event types, how to separate the events of each of your customers, how to change the URL, pause, test and remove, the delivery guarantees, retries, replay and signature verification, with code that works. - [Send messages](https://lunahia.com.br/en/docs/send-messages.md): Every message type the Luna API accepts, the 24-hour window, when a template is required, idempotency and how to follow delivery. - [AI agent: the complete loop](https://lunahia.com.br/en/docs/ai-agent.md): The loop of an agent that answers on WhatsApp, whole and in code that runs when pasted (Python with only the standard library, and Node with only fetch): verify, deduplicate, answer 200, mark as read, show typing, reply with a deterministic idempotency key and fall back to a template. - [Users without a phone number (BSUID)](https://lunahia.com.br/en/docs/users-without-phone.md): What changes when a WhatsApp user writes without the phone number showing: the BSUID in events and listings, the wa_id that can be null, how to answer with recipient, a change of phone number or BSUID and what Luna cannot do. - [What the number does at Meta](https://lunahia.com.br/en/docs/number-on-meta.md): Business profile, blocked users, QR code with a short link and the notice that a contact asked to stop receiving marketing: the routes, what Meta refuses, what does not work in coexistence and what is still to be confirmed. - [Test mode](https://lunahia.com.br/en/docs/test-mode.md): A test key that sends a message without going to Meta and delivers simulated states to your webhook, signed and marked test true: how to create it, what comes out, what is not simulated. - [SDK and n8n](https://lunahia.com.br/en/docs/sdk-and-n8n.md): The n8n workflow that works today with the standard nodes (Webhook, Code and HTTP Request), with a workflow to import, and what exists of the Node/TypeScript SDK and the dedicated n8n node, which are not published yet. - [Use the documentation in your editor (MCP)](https://lunahia.com.br/en/docs/mcp.md): Connect Claude Code, Cursor, VS Code, Claude or ChatGPT to the Luna documentation through a public MCP server: the AI reads the guides and the exact contract of each route, always in the published version. - [Templates](https://lunahia.com.br/en/docs/templates.md): How to create a template, follow its status, use a media header, and why approved does not mean cleared for sending. - [Errors](https://lunahia.com.br/en/docs/errors.md): The Luna API error shape, the main codes with what to do about each, and the rate limit headers. - [Limits and pacing](https://lunahia.com.br/en/docs/limits-and-pacing.md): How far you can go and what happens when you pass it: the request limit, the burst of each conversation, the per-number pace, the send queue, Meta’s daily conversation limit and the other ceilings, with the numbers. - [Account health](https://lunahia.com.br/en/docs/account-health.md): Meta’s notices about your customer’s WhatsApp Business account (restriction, violation, deactivation, disconnection, limit, quality and alert), Luna’s notice that the customer’s authorization is about to expire, what each event means and what your system does in each case. - [Payment at Meta](https://lunahia.com.br/en/docs/payment-at-meta.md): What happens when the business that owns the number has no payment method at Meta, how to detect it through the API and by event, what to tell your customer, and how to know it is back. - [Meta costs](https://lunahia.com.br/en/docs/meta-costs.md): Who charges for what, what Meta charges for WhatsApp usage since October 1, 2026, and where to check what was charged. - [Coming from Z-API or the Evolution API](https://lunahia.com.br/en/docs/migrate-from-unofficial-api.md): A mapping of authentication, sending, events and states for those migrating from Z-API or the Evolution API, and what does not exist on the official WhatsApp API, with the reason for each absence. - [Coming from Twilio](https://lunahia.com.br/en/docs/migrate-from-twilio.md): A mapping of sending, templates, states, webhook signature and error codes for those moving WhatsApp from Twilio to Luna, and what does not exist here. - [Coming from another official partner (360dialog, Gupshup)](https://lunahia.com.br/en/docs/migrate-from-another-partner.md): A mapping of authentication, customer onboarding, events, templates and usage for those running customers through another official Meta partner, and how to move a number with the PIN. - [Glossary](https://lunahia.com.br/en/docs/glossary.md): The documentation’s terms in plain language: 24-hour window, template, idempotency, BSUID, webhook, signature, wamid, externalId, event_id and raw body. - [Coming from Z-API or Evolution: migrating to Luna](https://lunahia.com.br/en/migrate-from-evolution-api): What changes in the model, how the instance life cycle becomes number, link, key and webhook per customer, the capability-by-capability map, and what has no equivalent, with the reason for each absence. ## Referência da API - [Referência da API](https://lunahia.com.br/docs/referencia.md): Buscar uma rota ou um evento - [Mensagens](https://lunahia.com.br/docs/referencia/mensagens.md): 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. - [Conversas](https://lunahia.com.br/docs/referencia/conversas.md): Uma linha por interlocutor por número, com o estado da janela de atendimento de 24 horas. - [Mídia](https://lunahia.com.br/docs/referencia/midia.md): Enviar um arquivo para a Meta e baixar a mídia que chegou numa mensagem. - [Templates](https://lunahia.com.br/docs/referencia/templates.md): Mensagens pré-aprovadas pela Meta, necessárias para iniciar conversa fora da janela de 24 horas. - [Números](https://lunahia.com.br/docs/referencia/numeros.md): Os números conectados: conectar, ver estado, qualidade e vazão, editar e desconectar. - [Links de conexão](https://lunahia.com.br/docs/referencia/links-de-conexao.md): 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. - [Webhooks e eventos](https://lunahia.com.br/docs/referencia/webhooks-e-eventos.md): 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. - [Chaves](https://lunahia.com.br/docs/referencia/chaves.md): Criar, listar e revogar as credenciais que autenticam as suas chamadas. - [Conta e plano](https://lunahia.com.br/docs/referencia/conta-e-plano.md): A conta da credencial, o plano, a capacidade de números e quantos estão em uso no período. - [Status](https://lunahia.com.br/docs/referencia/status.md): Sondas de disponibilidade e o estado da plataforma. Sem autenticação. - [Console e páginas públicas](https://lunahia.com.br/docs/referencia/console-e-paginas-publicas.md): 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. - [Eventos de webhook](https://lunahia.com.br/docs/referencia/eventos.md) - [Erros](https://lunahia.com.br/docs/referencia/erros.md) ## API reference (English) - [API reference](https://lunahia.com.br/en/docs/reference.md): Search a route or an event - [Messages](https://lunahia.com.br/en/docs/reference/messages.md): Send messages and read what came in and went out. Sending is asynchronous: the answer is 202 and delivery happens at the pace Meta allows. - [Conversations](https://lunahia.com.br/en/docs/reference/conversations.md): One row per contact per number, with the state of the 24 hour customer service window. - [Media](https://lunahia.com.br/en/docs/reference/media.md): Upload a file to Meta and download the media that arrived in a message. - [Templates](https://lunahia.com.br/en/docs/reference/templates.md): Messages pre-approved by Meta, required to start a conversation outside the 24 hour window. - [Phone numbers](https://lunahia.com.br/en/docs/reference/phone-numbers.md): The connected numbers: connect, read state, quality and throughput, edit and disconnect. - [Connection links](https://lunahia.com.br/en/docs/reference/connection-links.md): A link your customer opens to connect their WhatsApp number, without receiving your console login. One link per customer of yours, tied to the externalId you chose. - [Webhooks and events](https://lunahia.com.br/en/docs/reference/webhooks-and-events.md): Where Luna delivers what arrives at your number, the secret that signs those deliveries, and the event types, each with its schema and an example. - [Keys](https://lunahia.com.br/en/docs/reference/keys.md): Create, list and revoke the credentials that authenticate your calls. - [Account and plan](https://lunahia.com.br/en/docs/reference/account-and-plan.md): The credential's account, the plan, the number capacity and how many are in use in the period. - [Status](https://lunahia.com.br/en/docs/reference/status.md): Availability probes and the state of the platform. No authentication. - [Console and public pages](https://lunahia.com.br/en/docs/reference/console-and-public-pages.md): Routes the Luna console and the public connection link page use: sign-up, login, session and completion of the flow. You normally do not need them. They exist here because the console is a client of this same API, with no privileged route. - [Webhook events](https://lunahia.com.br/en/docs/reference/events.md) - [Errors](https://lunahia.com.br/en/docs/reference/errors.md) ## Optional - [OpenAPI 3.1 (pt-BR)](https://api.lunahia.com.br/openapi.json): the machine-readable specification - [OpenAPI 3.1 (en)](https://api.lunahia.com.br/openapi.en.json): the same specification, in English - [Postman (pt-BR)](https://lunahia.com.br/docs/referencia/postman.json) and [Postman (en)](https://lunahia.com.br/en/docs/reference/postman.json): collections generated from the specification - [MCP server](https://lunahia.com.br/mcp): this same documentation as a remote MCP server (Streamable HTTP, read-only, no key); setup for Claude Code, Cursor, VS Code, Claude and ChatGPT at https://lunahia.com.br/en/docs/mcp - [Full documentation in one file (pt-BR)](https://lunahia.com.br/llms-full.txt) and [(en)](https://lunahia.com.br/en/llms-full.txt)