Modo de teste
Para montar e testar a sua integração sem mandar mensagem de verdade, crie uma chave de teste. Com ela, enviar uma mensagem não vai à Meta, não usa número seu e não conta na capacidade do plano: a Luna devolve o mesmo 202 e entrega ao seu webhook os eventos que a Meta mandaria, simulados, assinados e marcados com test: true.
A referência da API traz cada rota e cada campo. Este guia explica o que ela não cabe em poucas linhas: o que a chave de teste alcança, o que sai e quando, e o que o modo de teste não simula.
Criar a chave de teste#
POST /v1/api-keys com mode: "test". A resposta traz o segredo uma única vez, como em qualquer chave. O campo mode aparece também na lista de chaves (live ou test) e não muda depois: para sair do modo de teste, use outra chave.
curl -X POST "https://api.lunahia.com.br/v1/api-keys" \
-H "Authorization: Bearer $LUNA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"label": "teste da integração",
"profile": "agent",
"mode": "test"
}'const res = await fetch('https://api.lunahia.com.br/v1/api-keys', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"label": "teste da integração",
"profile": "agent",
"mode": "test"
}),
});
console.log(res.status, await res.json());import os
import requests
res = requests.post(
"https://api.lunahia.com.br/v1/api-keys",
headers={
"Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
},
json={
"label": "teste da integração",
"profile": "agent",
"mode": "test",
},
timeout=10,
)
print(res.status_code, res.json())- A chave de teste é da conta inteira:
externalIdjunto commode: "test"responde400. - Ela só usa duas rotas:
POST /v1/messagesePOST /v1/test-mode/inbound-messages. Em qualquer outra, a resposta é403comerror: "test_key_not_allowed", antes de validar o corpo. É isso que garante que ela nunca lê nem muda número, conta ou template, e que nunca chega à Meta. - Os escopos valem como em qualquer chave: o envio pede
messages:write. O perfilagentjá o tem. - A chave de teste não é um número e não conta na capacidade do plano.
Enviar e receber os estados#
Envie como sempre, com a chave de teste. O corpo é validado pelo mesmo contrato do envio de verdade (um corpo inválido responde 400), e from é um texto livre: a Luna não procura o número, então use o phone_number_id que o seu código usará em produção.
curl -X POST "https://api.lunahia.com.br/v1/messages" \
-H "Authorization: Bearer $LUNA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "1000000000000001",
"to": "5511900000000",
"type": "text",
"text": {
"body": "Olá! Esta mensagem é de teste."
}
}'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',
},
body: JSON.stringify({
"from": "1000000000000001",
"to": "5511900000000",
"type": "text",
"text": {
"body": "Olá! Esta mensagem é de teste."
}
}),
});
console.log(res.status, await res.json());import os
import requests
res = requests.post(
"https://api.lunahia.com.br/v1/messages",
headers={
"Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
},
json={
"from": "1000000000000001",
"to": "5511900000000",
"type": "text",
"text": {
"body": "Olá! Esta mensagem é de teste.",
},
},
timeout=10,
)
print(res.status_code, res.json())202, igual à do envio de verdadeJSON{
"id": "ae60f288-7565-4315-a440-3663e9c231e1",
"status": "queued"
}Depois do 202, a Luna entrega aos seus endpoints de webhook três eventos message.status, na ordem: sent (cerca de 0,3 segundo depois), delivered (cerca de 1 segundo) e read (cerca de 2 segundos). Os tempos são aproximados. O id do evento é o que o 202 devolveu.
sentJSON{
"version": "2026-11-10",
"event_id": "bda40971d61ae76b36ab297565598f9427fd64ef16af8a62d201c8f596eb1006",
"event_type": "message.status",
"occurred_at": "2026-11-03T15:00:00.300Z",
"phone_number_id": "1000000000000001",
"test": true,
"number": {
"id": "03af3f4b-3a6f-4867-880f-eb5e847a6a8f",
"phone_number_id": "1000000000000001",
"external_id": null
},
"message": {
"id": "ae60f288-7565-4315-a440-3663e9c231e1",
"wamid": "wamid.TESTE_ae60f28875654315a4403663e9c231e1",
"wa_id": "5511900000000",
"user_id": null,
"parent_user_id": null,
"username": null,
"status": "sent",
"error_code": null,
"error": null,
"pricing": null
}
}test: trueno envelope. É o que separa o evento simulado de um de verdade. Se o seu código age sobre o evento, confira esse campo.- Sai assinado com o segredo do seu endpoint, com os mesmos cabeçalhos e a mesma assinatura de uma entrega real. Quem verifica a assinatura de verdade verifica a deste evento. Veja Receber eventos.
- O
wamidcomeça comwamid.TESTE_, para nunca se confundir com um da Meta. Onumber.idé um identificador de mentira, estável para o mesmophone_number_id, enumber.external_idé nulo. pricingvem nulo: a mensagem não foi à Meta, então ninguém a classificou.
Quem recebe: os endpoints ativos, sem filtro de cliente nem de número, que aceitam o tipo do evento. Um endpoint pausado, ou restrito a clientes ou a números, não recebe o evento simulado. A entrega é de uma tentativa só: não há reenvio, o evento não vai para a fila de rejeitados e uma falha dele não pausa o endpoint. Sem nenhum endpoint, o 202 sai do mesmo jeito e nada chega.
Simular uma falha de envio#
Três números em to fazem o envio de teste terminar em failed, para você ver o seu código tratar a recusa sem gastar um número de verdade. Para eles sai um único message.status, com status: "failed", error_code e error (code, title e message) no formato do erro que a Meta informa. Não saem sent, delivered nem read.
5511900009901:failedcom o erro131026(mensagem não entregável: o número não tem WhatsApp, ou não aceitou os termos).5511900009902:failedcom o erro131047(a janela de 24 horas está fechada: só vale um template).5511900009903:failedcom o erro131049(a Meta não entregou para preservar a saúde do ecossistema, o limite de marketing por pessoa).
Só a chave de teste tem esse comportamento. Com a chave de produção, esses números não têm nada de especial: o envio segue o caminho de sempre.
Simular uma mensagem recebida#
POST /v1/test-mode/inbound-messages entrega aos seus endpoints uma message.received de exemplo, em cerca de meio segundo, para você exercitar o fluxo de atendimento sem esperar um contato escrever. O corpo é opcional: text (o texto), waId (o telefone de quem "escreveu", só dígitos) e phoneNumberId (o que aparece no evento). Ausentes, valem um texto de exemplo, 5511900000000 e 123456789012345.
curl -X POST "https://api.lunahia.com.br/v1/test-mode/inbound-messages" \
-H "Authorization: Bearer $LUNA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Quero a segunda via do boleto"
}'const res = await fetch('https://api.lunahia.com.br/v1/test-mode/inbound-messages', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"text": "Quero a segunda via do boleto"
}),
});
console.log(res.status, await res.json());import os
import requests
res = requests.post(
"https://api.lunahia.com.br/v1/test-mode/inbound-messages",
headers={
"Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
},
json={
"text": "Quero a segunda via do boleto",
},
timeout=10,
)
print(res.status_code, res.json())202JSON{
"id": "3f6a1c52-9d4e-4b87-a1f0-5e2c7b9d8a14",
"wamid": "wamid.TESTE_3f6a1c529d4e4b87a1f05e2c7b9d8a14",
"endpoints": 1
}endpoints diz quantos dos seus endpoints vão receber o evento. Zero quer dizer que nada vai chegar: cadastre um endpoint. Esta rota aceita também a chave comum, e então faz o mesmo que POST /v1/webhooks/endpoints/{id}/test com eventType: "message.received", só que para todos os endpoints de uma vez. Para exercitar os outros tipos de evento, use essa rota de teste do endpoint, que aceita qualquer tipo.
O que o modo de teste não faz#
- Não grava nada. A mensagem não aparece em
GET /v1/messages, e a chave de teste nem lê essa rota. Oidexiste só nos eventos. - Não confere a janela de 24 horas, o template aprovado, as variáveis dele, o telefone do destinatário (+55) nem o número. Por isso um envio que a produção recusaria com
409,400ou422passa no modo de teste. Teste esses caminhos com um número de verdade. - Só simula as três falhas dos números mágicos. Fora deles os estados são
sent,deliverederead. Para outrofailed, usePOST /v1/webhooks/endpoints/{id}/testcomeventType: "message.status"ou construa o evento a partir dos exemplos de Receber eventos. - Não é idempotente. O cabeçalho
Idempotency-Keyé ignorado: cada envio gera umidnovo e três eventos novos. - Os estados saem de um temporizador do processo da Luna. Se o processo reiniciar entre um estado e outro, os que faltavam não saem. Repita o envio.
- Há um teto técnico de entregas simuladas agendadas ao mesmo tempo, igual para todos. Passou dele, a resposta é
429comRetry-After. Espere o tempo indicado. - Conta suspensa recusa o envio de teste como recusa o de verdade (
403, veja Plano e números).
Passar para produção#
Troque a chave de teste por uma chave comum. O resto do código é o mesmo, porque o envio e os eventos têm a mesma forma. Enquanto os dois ambientes convivem, descarte ou separe o que vem com test: true. Para usar o modo de teste no n8n ou com o SDK, veja SDK e n8n.