# Vindo da Twilio

Fonte: https://lunahia.com.br/docs/migrar-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](https://lunahia.com.br/docs/referencia) 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](https://lunahia.com.br/docs/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](https://lunahia.com.br/docs/enviar-mensagens#estados).
- **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

| 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](https://lunahia.com.br/docs/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](https://lunahia.com.br/docs/enviar-mensagens#estados). |
| 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](https://lunahia.com.br/docs/enviar-mensagens#idempotencia). |
| 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](https://lunahia.com.br/docs/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](https://lunahia.com.br/docs/modo-de-teste). |

```bash
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"
          }
        ]
      }
    ]
  }
}'
```

```js
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());
```

```python
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](https://lunahia.com.br/docs/receber-eventos#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](https://lunahia.com.br/docs/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](https://lunahia.com.br/docs/erros#envio). |

## 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](https://lunahia.com.br/docs/templates#autenticacao). |
| 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](https://lunahia.com.br/docs/sdk-e-n8n). |

> A Helsen cobra pela capacidade de números ativos do seu plano, e por nada além disso. O uso da plataforma WhatsApp é cobrado pela Meta, do seu cliente final, no método de pagamento dele. A Twilio é uma empresa independente, sem relação com a Helsen; este guia descreve o modelo de cada plataforma para quem migra e não é uma comparação comercial.
