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.
Trigger an event#
Send the fixture name as event. my-test-number is the test number's session value:
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:
{
"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 API Get project event; see Event history. 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 API List test event fixtures. The list is the same for every project, so the request names no project or Number:
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:
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. 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 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.
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. |