LunaDocs

Carregando a busca...

EnglishEntrar no console
Nesta página

Modo de teste

Usar com IA

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: externalId junto com mode: "test" responde 400.
  • Ela só usa duas rotas: POST /v1/messages e POST /v1/test-mode/inbound-messages. Em qualquer outra, a resposta é 403 com error: "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 perfil agent já 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())
Resposta 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.

O evento 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: true no 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 wamid começa com wamid.TESTE_, para nunca se confundir com um da Meta. O number.id é um identificador de mentira, estável para o mesmo phone_number_id, e number.external_id é nulo.
  • pricing vem 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: failed com o erro 131026 (mensagem não entregável: o número não tem WhatsApp, ou não aceitou os termos).
  • 5511900009902: failed com o erro 131047 (a janela de 24 horas está fechada: só vale um template).
  • 5511900009903: failed com o erro 131049 (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())
Resposta 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. O id existe 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, 400 ou 422 passa 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, delivered e read. Para outro failed, use POST /v1/webhooks/endpoints/{id}/test com eventType: "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 um id novo 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 é 429 com Retry-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.