LunaDocs

Carregando a busca...

EnglishEntrar no console
Nesta página

Vindo da Twilio

Usar com IA

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 externalId de uma chave, de um link de conexão e de um endpoint. Veja SaaS com N clientes.
  • O envio responde 202. O id da Luna volta na hora com status: "queued", e o wamid e o estado de entrega chegam em message.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_closed na própria chamada, com fechadaEm e acaoRecomendada. 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_approved se o estado não é APPROVED, e 400 com campos se 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. to começa por 55. Outro formato responde 400 com campos: [{campo: "to"}], salvo para quem já escreveu para o seu número.

De-para do que você usa#

TwilioLuna
Criar mensagem na API de mensagensPOST /v1/messages
Origem no formato whatsapp:+5531...from: o UUID do número (GET /v1/numbers) ou o metaPhoneNumberId.
Destino no formato whatsapp:+5511900000001to: "5511900000001": só dígitos, sem + e sem prefixo.
Corpo de textotext.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çãoPOST /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 mensagemUm endpoint (POST /v1/webhooks/endpoints) recebe o evento message.status de todas as mensagens.
Estados queued, sent, delivered, read, failed, undeliveredqueued (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 mensagemerror_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ãoEvento message.received: message.text, wa_id, message.button.payload e message.interactive.
Chave de idempotência do envioCabeç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 APIAuthorization: Bearer hlsn_..., com escopos (messages:write, messages:read, templates:read...). Veja Conta e chaves.
Subconta por clienteChave com externalId, link de conexão e endpoint com externalIds.
Listar mensagens por destinatário, data e tamanho de páginaGET /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 enviadocontent de GET /v1/messages: em template, o name, o language e as variables.
Sandbox com joinUma 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 2xx para aceitar e 401 a uma assinatura inválida. Só 2xx conta como entregue, e a entrega pode repetir: deduplique pelo event_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 TwilioNa Luna
21211, destino inválido400 com campos: [{campo: "to"}], na hora.
63016, fora da janela de resposta409 window_closed, na hora e antes de ir à Meta. Envie um template.
Conteúdo ou variáveis do template inválidos409 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 Metamessage.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 TwilioNa Luna
Verificação de código por WhatsApp, SMS, voz e e-mailA 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 SMSA 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 enviarA 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 mensagensCada 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 envioUm 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 mensagemNã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 pararA 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 temporizadorA Luna entrega a mensageria; a lógica é sua. Para fluxos sem código, há o nó do n8n em SDK e n8n.