# Trigger test events

> Send signed test events for a test number to your webhooks and event history.

Trigger a named test event for a test number to check how your integration
handles it. Polymorfa delivers the event to your webhooks and event history in
the same format as other events, signed with your endpoint's signing secret.
You don't need a phone, a second person or a WhatsApp account.

Test events work only for test numbers. The request names the test number in
its path, and the Number decides the project. A real Number, or a test number
outside your key's project, returns `404 resource_not_found` and sends nothing.

> **Note**
>
> **Before you begin.** Your team needs [test numbers access](https://docs.polymorfa.com/testing) and the
> project needs a test number; use its `session` value in the request path.
> Triggering needs `sandbox:write` and listing fixtures needs `sandbox:read`. Use
> the project's Test key, or a project token or team key with those scopes.
> Client tokens can't trigger test events or list fixtures.

## Trigger an event

Send the fixture name as `event`. `my-test-number` is the test number's
`session` value:

```bash
curl -X POST "https://api.polymorfa.com/messaging/my-test-number/test-events" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "message.received",
    "overrides": { "text": "hi", "from": "+15550100001" }
  }'
```

The API returns `202 Accepted`:

```json
{
  "event": "message.received",
  "session": "my-test-number",
  "delivery": "generated",
  "eventId": "0199f1c2-7a4e-7c55-9d1e-3f0b8a2c6d10",
  "source": "test"
}
```

## Verify the event

Webhook endpoints subscribed to the event type receive it with the same
envelope and signature headers as any other event. Look it up by `eventId`
with `GET /platform/projects/{projectId}/events/{eventId}`; see
[Event history](https://docs.polymorfa.com/development/events). Test events carry `source: "test"` and
`environment: "development"`, so you can tell them apart from events caused by
WhatsApp activity.

## Fixtures

Each fixture name is the event type it produces. List the fixtures and the
overrides each accepts with `GET /messaging/test-events/fixtures`. The list is
the same for every project, so the request names no project or Number:

```bash
curl "https://api.polymorfa.com/messaging/test-events/fixtures" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

| Fixture | Simulates | Overrides | Default without overrides |
| --- | --- | --- | --- |
| `message.received` | An inbound text or media message | `text`, `from`, `pushName`, `mediaType`, `caption` | A text message from `+15550100001` |
| `message.ack` | A receipt for an outbound message | `from`, `ackStatus`, `messageId` | `ackStatus` is `delivered` |
| `message.failed` | An outbound send that failed | `from`, `failureReason` | `failureReason` is `send_failed` |
| `call.received` | An incoming call offer | `from`, `video` | A voice call |
| `call.missed` | An unanswered incoming call | `from` | Missed after the call timed out |
| `call.ended` | A finished call | `from`, `video`, `durationSeconds`, `callEndReason` | A 42-second voice call ended with `user_hangup` |
| `session.status` | A connection status change | `status`, `statusReason` | `DISCONNECTED` with `STREAM_ERROR` |
| `session.restriction_updated` | A WhatsApp restriction on starting new conversations and calls | `restrictionActive` | The restriction starts and ends in 24 hours |
| `template.status` | A template approval or rejection | `templateName`, `templateStatus`, `reason` | `APPROVED` |

A fixture rejects an override it doesn't list with `400`.

## Scenarios

| To test | Send |
| --- | --- |
| An inbound image with a caption | `message.received` with `mediaType: "image"` and `caption` |
| A read receipt | `message.ack` with `ackStatus: "read"` |
| A played voice message | `message.ack` with `ackStatus: "played"` |
| A receipt error | `message.ack` with `ackStatus: "error"` |
| A failed send | `message.failed`, optionally with `failureReason` |
| An incoming video call | `call.received` with `video: true` |
| A dropped connection | `session.status` with no overrides |
| A restriction that ends | `session.restriction_updated` with `restrictionActive: false` |
| A rejected template | `template.status` with `templateStatus: "REJECTED"` and an optional `reason` |

`mediaType` accepts `image`, `video`, `audio`, `document` and `sticker`.
`caption` applies to images, videos and documents. Generated media events
describe the media but contain no downloadable file.

## What test events don't change

A test event reaches your webhooks and event history only. It doesn't change
the test number: a `session.status` event doesn't disconnect it, a
`session.restriction_updated` event doesn't restrict it, and call events don't
ring Calls clients. Test events don't count toward campaign reply metrics.

Contact and message IDs in generated events are random. They don't belong to a
conversation, so you can't reply to them.

## Send a real simulated message instead

To test a full round trip, including replies, have another connected test
number in the same project send the message. Set `fromNumber` to the sender's
`session` value on a `message.received` request. The test number in the path
receives the message:

```bash
curl -X POST "https://api.polymorfa.com/messaging/my-test-number/test-events" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "message.received",
    "fromNumber": "my-other-test-number",
    "overrides": { "text": "hi" }
  }'
```

The response has `"delivery": "simulated"` and `"eventId": null`. The
`message.received` event follows as ordinary test number activity, with
`source: "runtime"`, and you can reply to it. Both test numbers must be
connected, and `fromNumber` accepts only the `text` override.

## Limits

Each project can trigger 30 test events per minute, shared with
[phone controls](https://docs.polymorfa.com/testing/phone-controls). Further requests return `429` with a
`Retry-After` header that gives the seconds to wait. Every trigger is recorded
in your team's [audit history](https://docs.polymorfa.com/teams/audit-history) as `testing.event.trigger`.

## Retry safely

Send an `Idempotency-Key` header, 1 to 255 printable ASCII characters, to make
a trigger safe to retry. A repeated request with the same key and body gets
the same `eventId`, so the event is delivered once. A different body with the
same key creates a separate event. This does not apply to `fromNumber`
requests.

```bash
curl -X POST "https://api.polymorfa.com/messaging/my-test-number/test-events" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Idempotency-Key: order-flow-check-1" \
  -H "Content-Type: application/json" \
  -d '{"event": "message.received"}'
```

## Errors

| Status | Cause |
| --- | --- |
| `400` | The fixture or an override is invalid. With `fromNumber`: the event isn't `message.received`, an override other than `text` was sent, `fromNumber` names the test number in the path, or either test number isn't connected. |
| `403` | Your team doesn't have test numbers access, the key lacks the scope, or the request used a client token. |
| `404` | `resource_not_found`: the Number in the path, or `fromNumber`, is a real Number or isn't a test number in your key's project. |
| `429` | The project reached 30 test events per minute. |
| `502` | Test event delivery or the access check is temporarily unavailable. Retry with the same `Idempotency-Key`. |

## See also

- [Trigger test event](https://docs.polymorfa.com/api/testing/trigger-test-event)
- [List test event fixtures](https://docs.polymorfa.com/api/testing/list-test-event-fixtures)
- [Webhooks](https://docs.polymorfa.com/development/webhooks)
- [Event history](https://docs.polymorfa.com/development/events)
