Vindo da Z-API ou da Evolution API
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_closedantes de gastar a chamada. Veja a janela. - O envio responde
202. A resposta traz oidda Luna estatus: "queued". Owamide o estado de entrega chegam depois, pelo eventomessage.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 por55. Outro formato responde400comcampos: [{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 owa_idque 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á
APPROVEDresponde409 template_not_approved, e variável faltando ou sobrando responde400comcampos. Um número que não consegue enviar agora (connection.canSend: falseemGET /v1/numbers) ainda aceita o pedido com202e a falha chega emmessage.status: leiacanSendantes de enviar.
Autenticar e enviar#
| O que você fazia | Z-API | Evolution API | Luna |
|---|---|---|---|
| Autenticar | O 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 cliente | Criar uma instância pelo parceiro. | Criar uma instância. | Link de conexão por cliente: POST /v1/onboarding/links. |
| Enviar texto | Uma 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 mensagens | Um 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ídia | A 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 lista | Botõ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ção | Enviar reação. | Enviar reação. | type: "reaction", com reaction.message_id (o wamid) e reaction.emoji. |
| Responder citando | Responder uma mensagem. | Um campo de citação no envio. | context.message_id, com o id da Luna ou o wamid. |
| Marcar como lida | Ler mensagens. | Marcar mensagem como lida. | POST /v1/messages/{id}/read, por mensagem. |
| Apagar a instância | Apagar 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:
{
"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ê ouvia | Z-API | Evolution API | Luna |
|---|---|---|---|
| Mensagem recebida | Webhook “ao receber”. | MESSAGES_UPSERT | message.received |
| Mensagem que o dono mandou pelo celular | “Ao receber”, com as enviadas por mim. | SEND_MESSAGE | message.echo, só em número em coexistência. |
| Estado da mensagem | Webhook de status, com os estados de envio, recebimento, leitura e reprodução. | MESSAGES_UPDATE | message.status: sent, delivered, read, played e failed. A Meta não manda delivered quando entrega e leitura coincidem. |
| Conectou | Webhook “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. |
| Desconectou | Webhook “ao desconectar”. | CONNECTION_UPDATE | number.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 pareamento | Nã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 enviar | A 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 chats | O 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 aparelho | A 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 stories | A API oficial não publica nem responde status. |
| Enquetes, eventos e fixar mensagem | Use botões ou lista, que o contato responde e volta em message.received, em message.interactive. |
| Editar, apagar e encaminhar mensagem enviada | A 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 Business | Etiqueta é 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 último | A 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 contato | Bloquear existe, em POST /v1/numbers/{id}/blocked-users. O resto das configurações de privacidade é do aplicativo. |
| Listas de transmissão, canais, comunidades | A 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). |
| Grupos | Grupo 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, desbanimento | Nã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 hora | Fora 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 voz | A 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#
- Crie a conta e uma chave por cliente: Conta e chaves.
- Troque a criação da instância pelo link de conexão: SaaS com N clientes.
- Cadastre o webhook e troque o seu tratamento de eventos pela tabela acima: Receber eventos.
- Teste o envio sem ir à Meta, com a chave de teste: Modo de teste.