Testing
Send testing phone message
- Base URL
https://api.polymorfa.com- Required permission
sandbox:write
Path parameters
sessionstringrequiredlength1–256Identifier of the connected Polymorfa session.
Body
tostringrequiredpattern^\+[1-9]\d{7,14}$Another Test number in the same project, in E.164 format.
textstringrequiredlength1–4096Text content carried by this object.
Responses
202The phone sent the message
sessionstringrequiredIdentifier of the connected Polymorfa session.
tostringrequiredSpecifies to for this native testing phone message.
messageIdstringrequirednullablePolymorfa message ID. Use the Polymorfa message's
idfor actions and replies.
Show 3 headers
400Invalid recipient, or the phone is offline
403Test numbers access required, or a client token was used
404Resource not found
429Testing rate limit reached
502The phone could not send the message. Retry later.
curl -X POST "https://api.polymorfa.com/messaging/<session>/phone/messages" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"to": "string",
"text": "string"
}'{
"session": "string",
"to": "string",
"messageId": "string"
}Create testing history fixture
- Base URL
https://api.polymorfa.com- Required permission
sandbox:write
Path parameters
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
Body
messagesarray of objectrequiredmax items100Messages associated with this schema.
Show 5 child fields
Responses
201Project-scoped history fixture
fixtureIdstring (uuid)requiredIdentifier for the fixture.
Show 3 headers
400Invalid fixture
403Test access required
404Project not found
502Test runtime unavailable
curl -X POST "https://api.polymorfa.com/messaging/projects/<projectId>/test-history-fixtures" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{
"id": "string",
"senderPhone": "string",
"text": "string",
"timestamp": 0,
"fromMe": true
}
]
}'{
"fixtureId": "00000000-0000-4000-8000-000000000000"
}List test event fixtures
- Base URL
https://api.polymorfa.com- Required permission
sandbox:read
Responses
200Available fixtures and the overrides each accepts
fixturesarray of objectrequiredFixtures associated with this native test event fixture list.
Show 3 child fields
Show 3 headers
403Read scope required; client tokens are not permitted
curl "https://api.polymorfa.com/messaging/test-events/fixtures" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"fixtures": [
{
"name": "message.received",
"description": "string",
"overrides": [
"string"
]
}
]
}Get testing phone
- Base URL
https://api.polymorfa.com- Required permission
sandbox:read
Path parameters
sessionstringrequiredlength1–256Identifier of the connected Polymorfa session.
Responses
200The simulated phone and its linked companions
sessionstringrequiredIdentifier of the connected Polymorfa session.
phonestringrequiredThe Test number, in E.164 format.
onlinebooleanrequiredTrue while the simulated phone is running.
devicesarray of objectrequiredCompanions linked to the phone, such as Polymorfa's own session and Inspector.
Show 1 child field
Show 3 headers
403Test numbers access required, or a client token was used
404Resource not found
502The simulated phone could not be read. Retry later.
curl "https://api.polymorfa.com/messaging/<session>/phone" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"session": "string",
"phone": "string",
"online": true,
"devices": [
{
"deviceId": 0
}
]
}Trigger test event
- Base URL
https://api.polymorfa.com- Required permission
sandbox:write
Path parameters
sessionstringrequiredlength1–128Identifier of the connected Polymorfa session.
Headers
idempotency-keystringpattern^[\x21-\x7e]{1,255}$Specifies idempotency key for this header parameter.
Body
eventstringrequiredFixture name. Each name is the event type it produces.
Allowed valuesmessage.receivedmessage.ackmessage.failedcall.receivedcall.missedcall.endedsession.statussession.restriction_updatedtemplate.statusoverridesobjectSpecifies overrides for this native trigger test event request.
Show 17 child fields
fromNumberstringlength1–128message.received only. Send a simulated text message from this other connected Test number in the same project instead of generating an event.
Responses
202Test event accepted for delivery
eventstringrequiredSpecifies event for this native trigger test event response.
Allowed valuesmessage.receivedmessage.ackmessage.failedcall.receivedcall.missedcall.endedsession.statussession.restriction_updatedtemplate.statussessionstringrequiredIdentifier of the connected Polymorfa session.
deliverystringrequiredSpecifies delivery for this native trigger test event response.
Allowed valuesgeneratedsimulatedeventIdstring (uuid)requirednullableIdentifier for the event.
sourcestringrequiredSpecifies source for this native trigger test event response.
Allowed valuestestruntime
Show 3 headers
400Invalid fixture or override
403Test numbers access required, or a client token was used
404Resource not found
429Test event rate limit reached
502Test event delivery unavailable. Retry with the same Idempotency-Key to avoid a second event.
curl -X POST "https://api.polymorfa.com/messaging/<session>/test-events" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"event": "message.received"
}'{
"event": "message.received",
"session": "string",
"delivery": "generated",
"eventId": "00000000-0000-4000-8000-000000000000",
"source": "test"
}Unlink testing phone device
- Base URL
https://api.polymorfa.com- Required permission
sandbox:write
Path parameters
sessionstringrequiredlength1–256Identifier of the connected Polymorfa session.
deviceIdintegerrequiredrange1–99Identifier for the device.
Responses
200The companion was unlinked and logged out
sessionstringrequiredIdentifier of the connected Polymorfa session.
deviceIdintegerrequiredIdentifier for the device.
unlinkedbooleanrequiredWhether unlinked.
Allowed valuestrue
Show 3 headers
400The phone is offline
403Test numbers access required, or a client token was used
404Project or companion not found
502The phone could not unlink the companion. Retry later.
curl -X POST "https://api.polymorfa.com/messaging/<session>/phone/devices/<deviceId>/unlink" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"session": "string",
"deviceId": 0,
"unlinked": true
}Set testing account mode
- Base URL
https://api.polymorfa.com- Required permission
sandbox:write
Changes how the Test number presents itself. A change unlinks every companion, including the Number's own session, so each must pair again. Repeating the current mode changes nothing.
Path parameters
sessionstringrequiredlength1–256Identifier of the connected Polymorfa session.
Body
accountTypestringrequiredHow the account uses WhatsApp.
whatsapp_app- WhatsApp app, connected as a linked device.
business_app- WhatsApp Business app, connected as a linked device.
meta_cloud- Meta Cloud API.
meta_coexistence- Meta Cloud API, with the WhatsApp Business app still active on the phone.
primaryPlatformstringPrimary phone platform the Test number emulates. Defaults to
android. Not accepted whenaccountTypeismeta_cloud.android- An Android phone.
ios- An iPhone.
Responses
200The account mode is set
sessionstringrequiredIdentifier of the connected Polymorfa session.
accountTypestringrequiredHow the account uses WhatsApp.
whatsapp_app- WhatsApp app, connected as a linked device.
business_app- WhatsApp Business app, connected as a linked device.
meta_cloud- Meta Cloud API.
meta_coexistence- Meta Cloud API, with the WhatsApp Business app still active on the phone.
primaryPlatformstringrequirednullableNull for
meta_cloud, which has no phone.android- An Android phone.
ios- An iPhone.
changedbooleanrequiredFalse when the Test number already used this mode. Nothing was unlinked.
unlinkedDevicesarray of integerrequiredCompanions the phone unlinked. Each must pair again, including Polymorfa's own session.
Show 3 headers
400Invalid mode, or the phone is offline
403Test numbers access required, or a client token was used
404Resource not found
409The Test number is claimed in Inspector, or another mode change is pending. Unclaim it or retry.
502The phone could not change mode. Retry later.
curl -X PUT "https://api.polymorfa.com/messaging/<session>/phone/account-mode" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"accountType": "whatsapp_app"
}'{
"session": "string",
"accountType": "whatsapp_app",
"primaryPlatform": "android",
"changed": true,
"unlinkedDevices": [
0
]
}