Vindo 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 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
externalIdde uma chave, de um link de conexão e de um endpoint. Veja SaaS com N clientes. - O envio responde
202. Oidda Luna volta na hora comstatus: "queued", e owamide o estado de entrega chegam emmessage.status. Veja Os estados da mensagem. - Fora da janela de 24 horas a recusa é na hora. Texto livre para quem não escreveu nas últimas 24 horas responde
409 window_closedna própria chamada, comfechadaEmeacaoRecomendada. 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_approvedse o estado não éAPPROVED, e400comcamposse 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.
tocomeça por55. Outro formato responde400comcampos: [{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. |
| 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. |
| 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. |
| 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. |
| 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. |
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"
}
]
}
]
}
}'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());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.
- Responda
2xxpara aceitar e401a uma assinatura inválida. Só2xxconta como entregue, e a entrega pode repetir: deduplique peloevent_id. - O SDK em TypeScript tem
lerEvento, que confere a assinatura e devolve o evento tipado. Veja 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. |
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. |
| 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. |