Vindo de outro parceiro oficial (360dialog, Gupshup)
Se você já opera clientes por outro parceiro oficial, o modelo é familiar: o negócio é dono da conta de WhatsApp Business, o número está na Cloud API da Meta e você conecta um cliente por um fluxo da Meta. O que muda são os nomes das coisas, o webhook e a forma de pagar a Meta. Este guia faz o de-para e diz o que fazer com um número que já está no outro parceiro.
A referência da API traz o contrato de cada rota. As colunas dos outros parceiros descrevem, com palavras nossas, o que a documentação pública de cada um mostra; se algo mudou por lá, vale a documentação deles.
O que muda e o que fica igual#
- Fica igual: o seu cliente continua dono da conta de WhatsApp Business (a WABA) e da forma de pagamento dele na Meta. A Luna não é dona de nada disso.
- Muda a forma de pagar a Meta. A Luna é Tech Provider e não tem linha de crédito com a Meta, então não existe carteira, saldo nem recarga. Cada negócio paga a Meta direto, e a Luna só exibe o consumo de cada número em
GET /v1/usage. Você repassa esse valor ao seu cliente como achar melhor, fora da Luna. - Não há objeto “cliente” nem “aplicativo”. O seu cliente é o
externalId, um rótulo que você põe na chave, no link de conexão, no endpoint e que volta em todo evento. A instância é o número. - Muda o webhook. Um endpoint para a conta inteira (ou um por cliente com
externalIds), entrega assinada, ordem preservada dentro de cada conversa eevent_idpara deduplicar. Não há cabeçalhos próprios na chamada: a autenticação da entrega é a assinatura. Veja Receber eventos.
De-para por parceiro#
Para quem vem da 360dialog
| 360dialog | Luna |
|---|---|
| Cabeçalho de chave, uma chave por canal | Authorization: Bearer hlsn_.... Uma chave por cliente, com externalId e profile: "agent". |
| Enviar mensagem | POST /v1/messages: 202 assíncrono e Idempotency-Key. |
| Cadastrar a URL do webhook por canal, com cabeçalhos | POST /v1/webhooks/endpoints com url, eventTypes e externalIds. Sem cabeçalhos próprios; a assinatura é X-Luna-Signature. |
| Listar clientes | Não há objeto “cliente”: o externalId é o seu cliente. |
| Listar canais | GET /v1/numbers, com os filtros externalId, state e canSend. |
| Criar chave de um canal | POST /v1/api-keys com externalId. |
| Endereço de integração e retorno com o cliente e os canais | POST /v1/onboarding/links com redirectUrl, que recebe status e numberId na query. O link vale 72 horas. Veja Conectar um número. |
| Evento de canal criado | onboarding.link.completed |
| Evento de canal em execução | number.connected |
| Evento de qualidade do número | number.quality_changed |
| Estado de saúde: disponível, limitado, bloqueado | connection.status e connection.reasons em GET /v1/numbers/{id}, e GET /v1/numbers/{id}/health. Veja Saúde da conta. |
| Listar, criar e apagar templates | GET /v1/templates?wabaId=, POST /v1/templates e DELETE /v1/templates/{id}. Veja Templates. |
| Replicar um template para outro cliente | Não há. Crie o template em cada WABA com POST /v1/templates. GET /v1/templates/{id} traz o conteúdo e o wabaId, o que ajuda a copiar à mão. |
| Saldo do cliente | GET /v1/usage?numberId=, só para exibir. Não há saldo nem recarga. |
| Limite de canais | GET /v1/subscription: capacity e capacityLeft. Veja Plano e números. |
| Pedido de cancelamento do canal | DELETE /v1/numbers/{id}, que dispara number.disconnected. Não desregistra o número na Meta. |
Para quem vem da Gupshup
| Gupshup | Luna |
|---|---|
| Criar um aplicativo por cliente | Não há aplicativo: a instância é o número. Crie um link de conexão com POST /v1/onboarding/links. |
| Link de incorporação assinado | O link de conexão: uma url com token, válida por 72 horas. |
| Assinaturas de callback por aplicativo | POST /v1/webhooks/endpoints. |
| Templates por aplicativo | /v1/templates, por WABA. |
| Carteira e saldo | Não existe, por desenho: cada negócio paga a Meta direto. GET /v1/usage só exibe o consumo. |
| Uso diário por aplicativo | GET /v1/usage, por número. |
| Perfil comercial e nome de exibição | GET e PATCH /v1/numbers/{id}/profile, sem o nome de exibição. Esse nome o negócio vê e pede no WhatsApp Manager, da Meta. Veja Perfil do negócio. |
O que muda no webhook#
- Assinatura. Cada entrega traz
X-Luna-Signature: t=...,v1=..., o HMAC-SHA256 det+.+ corpo bruto. Veja Verifique a assinatura. - Ordem e repetição. A ordem vale dentro de uma conversa, e a entrega pode repetir. Deduplique pelo
event_id, que é estável. - Qual conta e qual cliente. Os eventos de conexão e de template trazem o
waba_id, e todo evento traz o objetonumbercom oexternal_iddo seu cliente. Você não precisa cruzar listas para saber de quem é o evento. - Link abandonado. Um cliente que fecha a janela da Meta deixa o link
open, comlastFailureereason: "abandoned". O eventoonboarding.link.failedchega depois.
Mover um número que já está no outro parceiro#
- O negócio precisa ser dono da conta de WhatsApp Business e ter o número liberado no parceiro anterior. Os pré-requisitos e o PIN da verificação em duas etapas estão em Número que vem de outro provedor.
- Mande o link de conexão (
POST /v1/onboarding/links). Se o número ficar emPIN_REQUIRED, informe o PIN emPOST /v1/numbers/{id}/pin. O PIN errado gasta uma das tentativas de registro que a Meta concede. - Espere o evento
number.connectede confiraconnection.canSendemGET /v1/numbers/{id}. Só então desligue o número no parceiro anterior, para não ficar sem canal no intervalo. - Troque o webhook do seu sistema: os eventos e a assinatura são outros, como na tabela acima.
Capacidade e links#
O plano da Luna define quantos números você mantém ativos. O link de conexão não reserva vaga: se você mandar mais links do que há vagas, os últimos clientes ficam com o número em "conectando" até haver vaga. Antes de entregar cada link, confira as vagas, como explica Plano e números.