# Test mode

Fonte: https://lunahia.com.br/en/docs/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](https://lunahia.com.br/en/docs/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.

```bash
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"
}'
```

```js
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());
```

```python
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.

```bash
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."
  }
}'
```

```js
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());
```

```python
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 send

```json
{
  "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` event

```json
{
  "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](https://lunahia.com.br/en/docs/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.

```bash
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"
}'
```

```js
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());
```

```python
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` response

```json
{
  "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](https://lunahia.com.br/en/docs/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](https://lunahia.com.br/en/docs/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](https://lunahia.com.br/en/docs/sdk-and-n8n).
