Referência da API
Cada rota da API pública, gerada da especificação OpenAPI que a própria API serve. Cada operação diz como chamar: o escopo, os parâmetros, o corpo, as respostas e exemplos em curl, Node e Python. Para entender o motivo de uma decisão, siga o link do guia em cada operação.
Grupos#
- MensagensEnviar 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.8 operações
- ConversasUma linha por interlocutor por número, com o estado da janela de atendimento de 24 horas.1 operação
- MídiaEnviar um arquivo para a Meta e baixar a mídia que chegou numa mensagem.3 operações
- TemplatesMensagens pré-aprovadas pela Meta, necessárias para iniciar conversa fora da janela de 24 horas.9 operações
- NúmerosOs números conectados: conectar, ver estado, qualidade e vazão, editar e desconectar.22 operações
- Links de conexãoUm 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.6 operações
- Webhooks e eventosPara 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.11 operações
- ChavesCriar, listar e revogar as credenciais que autenticam as suas chamadas.6 operações
- Conta e planoA conta da credencial, o plano, a capacidade de números e quantos estão em uso no período.6 operações
- StatusSondas de disponibilidade e o estado da plataforma. Sem autenticação.3 operações
- Console e páginas públicasRotas 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.16 operações
- Eventos de webhookA Luna entrega cada evento por POST ao endpoint que você cadastrou.31
- ErrosTodo erro da API tem o mesmo formato.36
Autenticação#
URL base: https://api.lunahia.com.br
Toda rota de integração pede uma chave de API no cabeçalho Authorization, no formato Bearer hlsn_.... As rotas públicas, que a página de cada operação marca, não pedem chave.
A chave carrega escopos. Cada operação diz o escopo que exige, e uma chave sem ele recebe 403. Sem chave, ou com uma chave inválida ou revogada, a resposta é 401. A chave aparece uma única vez, quando é criada. O passo a passo para criar e revogar chaves, com curl, está em Conta e chaves.
O envio de mensagem é assíncrono: a resposta é 202, e a Luna entrega à Meta no ritmo que ela permite. O resultado chega como evento de webhook, no seu endpoint.
Existe limite de requisições por chave de API. Ele é técnico, idêntico para todos os clientes, e a resposta 429 traz Retry-After com o tempo a esperar.
Todo erro devolve um corpo JSON com error (um código estável) e message (texto para uma pessoa ler). Decida pelo status e por error, nunca pelo texto de message. A página de erros lista os códigos.