Test mode
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:
externalIdtogether withmode: "test"answers400. - It only uses two routes:
POST /v1/messagesandPOST /v1/test-mode/inbound-messages. On any other, the answer is403witherror: "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. Theagentprofile 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.
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: trueon 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
wamidstarts withwamid.TESTE_, so it is never mistaken for a Meta one. Thenumber.idis a made-up identifier, stable for the samephone_number_id, andnumber.external_idis null. pricingis 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:failedwith error131026(message undeliverable: the number has no WhatsApp, or has not accepted the terms).5511900009902:failedwith error131047(the 24-hour window is closed: only a template works).5511900009903:failedwith error131049(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. Theidexists 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,400or422passes 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,deliveredandread. For any otherfailed, usePOST /v1/webhooks/endpoints/{id}/testwitheventType: "message.status"or build the event from the examples in Receive events. - It is not idempotent. The
Idempotency-Keyheader is ignored: each send produces a newidand 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
429withRetry-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.