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