Glossário
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.
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, e o envio de texto livre responde 409 com error: "window_closed". Mais em Enviar mensagens.
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. O estado dele (PENDING, APPROVED, REJECTED...) vem da Meta, e só APPROVED envia. Mais em 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 e, para agentes, em Agente de IA.
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.
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.
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.
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.
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.
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.
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.