LunaDocs

Carregando a busca...

EnglishEntrar no console
Nesta página

Vindo de outro parceiro oficial (360dialog, Gupshup)

Usar com IA

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 e event_id para 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

360dialogLuna
Cabeçalho de chave, uma chave por canalAuthorization: Bearer hlsn_.... Uma chave por cliente, com externalId e profile: "agent".
Enviar mensagemPOST /v1/messages: 202 assíncrono e Idempotency-Key.
Cadastrar a URL do webhook por canal, com cabeçalhosPOST /v1/webhooks/endpoints com url, eventTypes e externalIds. Sem cabeçalhos próprios; a assinatura é X-Luna-Signature.
Listar clientesNão há objeto “cliente”: o externalId é o seu cliente.
Listar canaisGET /v1/numbers, com os filtros externalId, state e canSend.
Criar chave de um canalPOST /v1/api-keys com externalId.
Endereço de integração e retorno com o cliente e os canaisPOST /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 criadoonboarding.link.completed
Evento de canal em execuçãonumber.connected
Evento de qualidade do númeronumber.quality_changed
Estado de saúde: disponível, limitado, bloqueadoconnection.status e connection.reasons em GET /v1/numbers/{id}, e GET /v1/numbers/{id}/health. Veja Saúde da conta.
Listar, criar e apagar templatesGET /v1/templates?wabaId=, POST /v1/templates e DELETE /v1/templates/{id}. Veja Templates.
Replicar um template para outro clienteNã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 clienteGET /v1/usage?numberId=, só para exibir. Não há saldo nem recarga.
Limite de canaisGET /v1/subscription: capacity e capacityLeft. Veja Plano e números.
Pedido de cancelamento do canalDELETE /v1/numbers/{id}, que dispara number.disconnected. Não desregistra o número na Meta.

Para quem vem da Gupshup

GupshupLuna
Criar um aplicativo por clienteNão há aplicativo: a instância é o número. Crie um link de conexão com POST /v1/onboarding/links.
Link de incorporação assinadoO link de conexão: uma url com token, válida por 72 horas.
Assinaturas de callback por aplicativoPOST /v1/webhooks/endpoints.
Templates por aplicativo/v1/templates, por WABA.
Carteira e saldoNão existe, por desenho: cada negócio paga a Meta direto. GET /v1/usage só exibe o consumo.
Uso diário por aplicativoGET /v1/usage, por número.
Perfil comercial e nome de exibiçãoGET 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 de t + . + 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 objeto number com o external_id do 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, com lastFailure e reason: "abandoned". O evento onboarding.link.failed chega depois.

Mover um número que já está no outro parceiro#

  1. 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.
  2. Mande o link de conexão (POST /v1/onboarding/links). Se o número ficar em PIN_REQUIRED, informe o PIN em POST /v1/numbers/{id}/pin. O PIN errado gasta uma das tentativas de registro que a Meta concede.
  3. Espere o evento number.connected e confira connection.canSend em GET /v1/numbers/{id}. Só então desligue o número no parceiro anterior, para não ficar sem canal no intervalo.
  4. 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.