Skip to content
Shortcut: /, ⌘K or Ctrl+K

Trigger test events

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

View as Markdown

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:

Shell
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 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:

Shell
curl "https://api.polymorfa.com/messaging/test-events/fixtures" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
FixtureSimulatesOverridesDefault without overrides
message.receivedAn inbound text or media messagetext, from, pushName, mediaType, captionA text message from +15550100001
message.ackA receipt for an outbound messagefrom, ackStatus, messageIdackStatus is delivered
message.failedAn outbound send that failedfrom, failureReasonfailureReason is send_failed
call.receivedAn incoming call offerfrom, videoA voice call
call.missedAn unanswered incoming callfromMissed after the call timed out
call.endedA finished callfrom, video, durationSeconds, callEndReasonA 42-second voice call ended with user_hangup
session.statusA connection status changestatus, statusReasonDISCONNECTED with STREAM_ERROR
session.restriction_updatedA WhatsApp restriction on starting new conversations and callsrestrictionActiveThe restriction starts and ends in 24 hours
template.statusA template approval or rejectiontemplateName, templateStatus, reasonAPPROVED

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

Scenarios #

To testSend
An inbound image with a captionmessage.received with mediaType: "image" and caption
A read receiptmessage.ack with ackStatus: "read"
A played voice messagemessage.ack with ackStatus: "played"
A receipt errormessage.ack with ackStatus: "error"
A failed sendmessage.failed, optionally with failureReason
An incoming video callcall.received with video: true
A dropped connectionsession.status with no overrides
A restriction that endssession.restriction_updated with restrictionActive: false
A rejected templatetemplate.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:

Shell
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.

Shell
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#

StatusCause
400The 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.
403Your team doesn't have test numbers access, the key lacks the scope, or the request used a client token.
404resource_not_found: the Number in the path, or fromNumber, is a real Number or isn't a test number in your key's project.
429The project reached 30 test events per minute.
502Test event delivery or the access check is temporarily unavailable. Retry with the same Idempotency-Key.

See also#