LunaDocs

Carregando a busca...

EnglishEntrar no console
Nesta página

Vindo da Z-API ou da Evolution API

Usar com IA

A Z-API e a Evolution API conectam um número como um aparelho; a Luna fala só com a WhatsApp Cloud API oficial da Meta. Este guia traduz o que você fazia lá para o que se faz aqui: como autenticar, enviar, receber, e o que cada estado e cada evento vira. Termina com a lista do que não existe na API oficial, para você não procurar o que não está aqui.

A referência da API traz o contrato de cada rota. Antes das tabelas, leia a diferença de modelo: a janela de 24 horas, o 202 sem wamid e a ausência de QR code são o que quebra uma migração no meio. As colunas da Z-API e da Evolution descrevem, com palavras nossas, o que a documentação pública de cada uma mostra.

O que muda antes de tocar no código#

  • Instância vira número. Em vez de criar uma instância e ler um QR code, você manda ao seu cliente um link de conexão (POST /v1/onboarding/links) e o dono do número entra com a conta dele na Meta. O número fica na conta do seu cliente, e é isso que evita o banimento por sessão. Veja Conectar um número.
  • Texto livre só dentro de 24 horas. Depois que o contato para de escrever por 24 horas, o caminho é um template aprovado. A Luna recusa o texto fora da janela com 409 window_closed antes de gastar a chamada. Veja a janela.
  • O envio responde 202. A resposta traz o id da Luna e status: "queued". O wamid e o estado de entrega chegam depois, pelo evento message.status. Os estados estão em Os estados da mensagem.
  • Só celulares do Brasil. to é o telefone com DDI e DDD, só dígitos, começando por 55. Outro formato responde 400 com campos: [{campo: "to"}], salvo para quem já escreveu para o seu número. O nono dígito não é problema: a Luna acha a conversa com e sem ele, e o texto vai para o wa_id que a Meta usou. Quem nunca escreveu recebe o telefone como você o escreveu.
  • A fila tem ritmo. Para o mesmo contato, saem 30 mensagens de uma vez e depois uma a cada 7 segundos. Você não configura isso, e o limite nunca volta como 429. Não há como cancelar uma mensagem que já está na fila, nem estimar a hora em que ela sai.
  • Template não é recusado em silêncio. Um template que a Luna conhece e que não está APPROVED responde 409 template_not_approved, e variável faltando ou sobrando responde 400 com campos. Um número que não consegue enviar agora (connection.canSend: false em GET /v1/numbers) ainda aceita o pedido com 202 e a falha chega em message.status: leia canSend antes de enviar.

Autenticar e enviar#

O que você faziaZ-APIEvolution APILuna
AutenticarO identificador da instância e um token, mais um token de segurança da conta.Uma chave da instalação.Authorization: Bearer hlsn_... com escopos. Uma chave por cliente, com externalId.
Criar a instância de um clienteCriar uma instância pelo parceiro.Criar uma instância.Link de conexão por cliente: POST /v1/onboarding/links.
Enviar textoUma chamada com o telefone e a mensagem; devolve dois identificadores na hora.Uma chamada por instância com o número e o texto.POST /v1/messages com from, to e text.body. Devolve id e status: "queued"; o wamid vem depois.
Pausa entre mensagensUm atraso por mensagem, de 1 a 15 segundos.Um atraso por mensagem.Fila automática: rajada de 30, depois uma a cada 7 segundos por contato.
Mostrar “digitando”Um atraso de digitação no envio.Uma chamada de presença.POST /v1/messages/{id}/typing, com o id da mensagem recebida. Também a marca como lida e some em cerca de 25 segundos.
Enviar mídiaA URL ou o arquivo em base64 no próprio envio.O arquivo no próprio envio.POST /v1/numbers/{id}/media e depois image.id, ou image.link com uma URL pública. Dois passos, porque a Meta trabalha com identificador de mídia.
Botões e listaBotões de ação e lista de opções.Enviar botões e enviar lista.interactive.type: button, list ou cta_url. A resposta volta em message.interactive.id, no evento message.received.
ReaçãoEnviar reação.Enviar reação.type: "reaction", com reaction.message_id (o wamid) e reaction.emoji.
Responder citandoResponder uma mensagem.Um campo de citação no envio.context.message_id, com o id da Luna ou o wamid.
Marcar como lidaLer mensagens.Marcar mensagem como lida.POST /v1/messages/{id}/read, por mensagem.
Apagar a instânciaApagar a instância.Apagar a instância.DELETE /v1/numbers/{id}. Libera a vaga na Luna e não derruba o número na Meta.

O telefone vai como o cliente o escreveu, com ou sem o nono dígito. O corpo mínimo de um envio de texto:

JSON
{
  "from": "YOUR_PHONE_NUMBER_ID",
  "to": "5531990009991",
  "text": { "body": "Olá! Sua consulta está confirmada." }
}

Campos que pertencem ao tipo vão dentro do objeto do tipo, e não no topo do corpo: image.caption, location.latitude. Um campo desconhecido responde 400 com o nome dele. Mande sempre o Idempotency-Key: veja Idempotência.

Eventos e estados#

Na Luna há um endpoint de webhook para a conta inteira, ou um por cliente com externalIds. Todo evento traz o objeto number, com o external_id do cliente dono do número, então um endpoint só atende todos os seus clientes. A entrega é assinada e pode repetir: deduplique pelo event_id. Veja Receber eventos.

Webhook por número (como a “instância”)#

Lá cada instância tinha a sua URL de webhook. Aqui o número é a instância e o endpoint aceita phoneNumberIds: ele recebe só os eventos desses números (o UUID da Luna, o id de GET /v1/numbers, ou o metaPhoneNumberId).

curl -X POST "https://api.lunahia.com.br/v1/webhooks/endpoints" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhooks/numero-1",
  "phoneNumberIds": [
    "YOUR_PHONE_NUMBER_ID"
  ]
}'
const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "url": "https://example.com/webhooks/numero-1",
    "phoneNumberIds": [
      "YOUR_PHONE_NUMBER_ID"
    ]
  }),
});
console.log(res.status, await res.json());
import os
import requests

res = requests.post(
    "https://api.lunahia.com.br/v1/webhooks/endpoints",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    json={
        "url": "https://example.com/webhooks/numero-1",
        "phoneNumberIds": [
            "YOUR_PHONE_NUMBER_ID",
        ],
    },
    timeout=10,
)
print(res.status_code, res.json())

Para trocar a URL só desse número, use PATCH /v1/webhooks/endpoints/{id} com o novo url. Para números que ainda vão ser conectados, cadastre o endpoint com externalIds (o externalId que você dá ao cliente): ele recebe de todo número com esse externalId, inclusive os conectados depois. Detalhes na seção “Webhook por número” de Receber eventos.

curl -X PATCH "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhooks/numero-1-novo"
}'
const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "url": "https://example.com/webhooks/numero-1-novo"
  }),
});
console.log(res.status, await res.json());
import os
import requests

res = requests.patch(
    "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    json={
        "url": "https://example.com/webhooks/numero-1-novo",
    },
    timeout=10,
)
print(res.status_code, res.json())
O que você ouviaZ-APIEvolution APILuna
Mensagem recebidaWebhook “ao receber”.MESSAGES_UPSERTmessage.received
Mensagem que o dono mandou pelo celular“Ao receber”, com as enviadas por mim.SEND_MESSAGEmessage.echo, só em número em coexistência.
Estado da mensagemWebhook de status, com os estados de envio, recebimento, leitura e reprodução.MESSAGES_UPDATEmessage.status: sent, delivered, read, played e failed. A Meta não manda delivered quando entrega e leitura coincidem.
ConectouWebhook “ao conectar”.QRCODE_UPDATED e CONNECTION_UPDATE.onboarding.link.completed quando o cliente termina o link, e number.connected quando o número fica pronto.
DesconectouWebhook “ao desconectar”.CONNECTION_UPDATEnumber.disconnected, number.action_required e number.credential_expiring. O estado fica em connection de GET /v1/numbers/{id}.
Aprovação de template--template.status

Não existe evento de ligação recebida, e não existe configuração de rejeitar chamada. Se o seu agente depende de uma delas, trate no seu lado. A leitura automática existe: ligue autoRead no número, com PATCH /v1/numbers/{id}, e a Luna marca como lida cada mensagem que o número recebe, sem indicador de digitando. Para marcar só as que você processa, deixe autoRead desligado e use POST /v1/messages/{id}/read.

O que não existe na API oficial#

Não são faltas da Luna: são recursos de quem conecta um número como aparelho. Cada linha diz o que fazer no lugar.

O que existia láAqui
QR code e código de pareamentoNão há QR code. A conexão é pelo link de conexão, e o dono do número entra com a conta dele na Meta. É isso que impede o banimento.
Conferir se um número tem WhatsApp antes de enviarA API oficial não responde isso. Envie normalmente: se o número não tem WhatsApp, chega message.status com failed e o código 131026, e repetir o envio não muda o resultado.
Agenda de contatos, foto e recado de quem escreve, lista de chatsO número de negócio não tem agenda nem lista de chats. Guarde os contatos no seu banco a partir de message.received (wa_id e profile_name).
Mensagens antigas do aparelhoA Luna só tem o que passou por ela depois da conexão. Em número em coexistência, a Meta importa o histórico dentro de um prazo: veja Conectar um número.
Status e storiesA API oficial não publica nem responde status.
Enquetes, eventos e fixar mensagemUse botões ou lista, que o contato responde e volta em message.received, em message.interactive.
Editar, apagar e encaminhar mensagem enviadaA API de mensagens da Meta não oferece essas operações ao negócio. Corrija mandando outra mensagem; context.message_id cita a original.
Etiquetas e anotações do aplicativo BusinessEtiqueta é do aplicativo no celular e não existe na API. Marque a conversa no seu sistema, pelo conversationId ou pelo wa_id.
Presença do contato: online, “digitando”, visto por últimoA Meta não entrega a presença do contato. O “digitando” do seu agente sai por POST /v1/messages/{id}/typing.
Privacidade da conta e bloqueio de contatoBloquear existe, em POST /v1/numbers/{id}/blocked-users. O resto das configurações de privacidade é do aplicativo.
Listas de transmissão, canais, comunidadesA API oficial não tem. Para falar com muita gente, use template, e respeite o limite de qualidade e a preferência de marketing do contato (contact.preferences_changed).
GruposGrupo comum de WhatsApp não existe na API oficial. A Meta tem uma API de grupos própria, com limites e requisitos, que a Luna ainda não expõe.
Proxy por instância, IP dedicado, desbanimentoNão há sessão para proteger: o número é registrado na Meta, e o risco é de qualidade, não de IP. Veja GET /v1/numbers/{id}/health e Saúde da conta.
Texto livre a qualquer horaFora de 24 horas, só template. É a regra da Meta, e a Luna a aplica antes de gastar a chamada (409 window_closed).
Áudio em MP3 como mensagem de vozA Meta exige OGG com OPUS e a Luna não converte. Converta antes: ffmpeg -i entrada.mp3 -c:a libopus -b:a 32k -ar 48000 -ac 1 saida.ogg.

Por onde começar#

  1. Crie a conta e uma chave por cliente: Conta e chaves.
  2. Troque a criação da instância pelo link de conexão: SaaS com N clientes.
  3. Cadastre o webhook e troque o seu tratamento de eventos pela tabela acima: Receber eventos.
  4. Teste o envio sem ir à Meta, com a chave de teste: Modo de teste.