LunaDocs

Loading search...

PortuguêsSign in to the console
On this page

Test mode

Use with AI

To build and test your integration without sending a real message, create a test key. With it, sending a message does not go to Meta, does not use a number of yours and does not count against the plan capacity: Luna returns the same 202 and delivers to your webhook the events Meta would send, simulated, signed and marked test: true.

The API reference carries every route and field. This guide explains what it cannot fit in a few lines: what the test key reaches, what comes out and when, and what test mode does not simulate.

Create the test key#

POST /v1/api-keys with mode: "test". The response carries the secret once, as with any key. The mode field also shows in the key list (live or test) and does not change afterwards: to leave test mode, use another key.

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())
  • The test key belongs to the whole account: externalId together with mode: "test" answers 400.
  • It only uses two routes: POST /v1/messages and POST /v1/test-mode/inbound-messages. On any other, the answer is 403 with error: "test_key_not_allowed", before the body is validated. That is what guarantees it never reads or changes a number, account or template, and never reaches Meta.
  • Scopes work as on any key: sending asks for messages:write. The agent profile already has it.
  • The test key is not a number and does not count against the plan capacity.

Send and receive the states#

Send as usual, with the test key. The body is validated by the same contract as a real send (an invalid body answers 400), and from is free text: Luna does not look the number up, so use the phone_number_id your code will use in production.

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 response, the same as a real sendJSON
{
  "id": "ae60f288-7565-4315-a440-3663e9c231e1",
  "status": "queued"
}

After the 202, Luna delivers three message.status events to your webhook endpoints, in order: sent (about 0.3 second later), delivered (about 1 second) and read (about 2 seconds). The times are approximate. The event id is the one the 202 returned.

The sent eventJSON
{
  "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 on the envelope. It is what separates the simulated event from a real one. If your code acts on the event, check that field.
  • It goes out signed with your endpoint’s secret, with the same headers and the same signature as a real delivery. Whoever verifies the signature for real verifies this event’s. See Receive events.
  • The wamid starts with wamid.TESTE_, so it is never mistaken for a Meta one. The number.id is a made-up identifier, stable for the same phone_number_id, and number.external_id is null.
  • pricing is null: the message did not go to Meta, so nobody classified it.

Who receives: active endpoints, with no customer or number filter, that accept the event type. A paused endpoint, or one restricted to customers or numbers, does not receive the simulated event. Delivery is one attempt only: there is no resend, the event does not go to the rejected queue and a failure does not pause the endpoint. With no endpoint at all, the 202 goes out the same and nothing arrives.

Simulate a send failure#

Three numbers in to make the test send end in failed, so you can see your code handle the refusal without spending a real number. For them a single message.status goes out, with status: "failed", error_code and error (code, title and message) in the format of the error Meta reports. No sent, delivered or read goes out.

  • 5511900009901: failed with error 131026 (message undeliverable: the number has no WhatsApp, or has not accepted the terms).
  • 5511900009902: failed with error 131047 (the 24-hour window is closed: only a template works).
  • 5511900009903: failed with error 131049 (Meta did not deliver it to keep the ecosystem healthy, the per-person marketing limit).

Only the test key behaves this way. With the production key these numbers are nothing special: the send follows the usual path.

Simulate a received message#

POST /v1/test-mode/inbound-messages delivers one example message.received to your endpoints, in about half a second, so you can exercise the support flow without waiting for a contact to write. The body is optional: text (the text), waId (the phone of whoever "wrote", digits only) and phoneNumberId (what shows in the event). When absent, an example text, 5511900000000 and 123456789012345 apply.

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())
202 responseJSON
{
  "id": "3f6a1c52-9d4e-4b87-a1f0-5e2c7b9d8a14",
  "wamid": "wamid.TESTE_3f6a1c529d4e4b87a1f05e2c7b9d8a14",
  "endpoints": 1
}

endpoints says how many of your endpoints will receive the event. Zero means nothing will arrive: register an endpoint. This route also accepts the regular key, and then does the same as POST /v1/webhooks/endpoints/{id}/test with eventType: "message.received", only for all endpoints at once. To exercise the other event types, use that endpoint test route, which accepts any type.

What test mode does not do#

  • It stores nothing. The message does not show in GET /v1/messages, and the test key cannot even read that route. The id exists only in the events.
  • It does not check the 24-hour window, the approved template, its variables, the recipient phone (+55) or the number. That is why a send that production would refuse with 409, 400 or 422 passes in test mode. Test those paths with a real number.
  • It only simulates the three failures of the magic numbers. Outside them the states are sent, delivered and read. For any other failed, use POST /v1/webhooks/endpoints/{id}/test with eventType: "message.status" or build the event from the examples in Receive events.
  • It is not idempotent. The Idempotency-Key header is ignored: each send produces a new id and three new events.
  • The states come from a timer in Luna’s process. If the process restarts between one state and the next, the missing ones do not go out. Repeat the send.
  • There is a technical ceiling on simulated deliveries scheduled at the same time, the same for everyone. Past it, the answer is 429 with Retry-After. Wait the indicated time.
  • A suspended account refuses the test send the way it refuses a real one (403, see Plan and numbers).

Go to production#

Swap the test key for a regular one. The rest of the code is the same, because sending and the events have the same shape. While both environments coexist, drop or separate what comes with test: true. To use test mode in n8n or with the SDK, see SDK and n8n.