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

Testing

View as Markdown

Send testing phone message

POST/messaging/{session}/phone/messagesMessaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
sandbox:write

Path parameters

  • sessionstringrequiredlength1–256

    Identifier of the connected Polymorfa session.

Body

  • tostringrequiredpattern^\+[1-9]\d{7,14}$

    Another Test number in the same project, in E.164 format.

  • textstringrequiredlength1–4096

    Text content carried by this object.

Responses

  • 202The phone sent the message
    • sessionstringrequired

      Identifier of the connected Polymorfa session.

    • tostringrequired

      Specifies to for this native testing phone message.

    • messageIdstringrequirednullable

      Polymorfa message ID. Use the Polymorfa message's id for 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.
POST /messaging/{session}/phone/messagescURL
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"
}'
Response
{
  "session": "string",
  "to": "string",
  "messageId": "string"
}

Create testing history fixture

POST/messaging/projects/{projectId}/test-history-fixturesMessaging API
Base URL
https://api.polymorfa.com
Required permission
sandbox:write

Path parameters

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

Body

  • messagesarray of objectrequiredmax items100

    Messages associated with this schema.

    Show 5 child fields

Responses

POST /messaging/projects/{projectId}/test-history-fixturescURL
Not available with the Test key. Use a team key or project token.
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
    }
  ]
}'
Response
{
  "fixtureId": "00000000-0000-4000-8000-000000000000"
}

List test event fixtures

GET/messaging/test-events/fixturesMessaging API
Base URL
https://api.polymorfa.com
Required permission
sandbox:read

Responses

  • 200Available fixtures and the overrides each accepts
    • fixturesarray of objectrequired

      Fixtures associated with this native test event fixture list.

      Show 3 child fields
    Show 3 headers
  • 403Read scope required; client tokens are not permitted
GET /messaging/test-events/fixturescURL
curl "https://api.polymorfa.com/messaging/test-events/fixtures" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "fixtures": [
    {
      "name": "message.received",
      "description": "string",
      "overrides": [
        "string"
      ]
    }
  ]
}

Get testing phone

GET/messaging/{session}/phoneMessaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
sandbox:read

Path parameters

  • sessionstringrequiredlength1–256

    Identifier of the connected Polymorfa session.

Responses

  • 200The simulated phone and its linked companions
    • sessionstringrequired

      Identifier of the connected Polymorfa session.

    • phonestringrequired

      The Test number, in E.164 format.

    • onlinebooleanrequired

      True while the simulated phone is running.

    • devicesarray of objectrequired

      Companions 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.
GET /messaging/{session}/phonecURL
curl "https://api.polymorfa.com/messaging/<session>/phone" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "session": "string",
  "phone": "string",
  "online": true,
  "devices": [
    {
      "deviceId": 0
    }
  ]
}

Trigger test event

POST/messaging/{session}/test-eventsMessaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
sandbox:write

Path parameters

  • sessionstringrequiredlength1–128

    Identifier of the connected Polymorfa session.

Headers

  • idempotency-keystringpattern^[\x21-\x7e]{1,255}$

    Specifies idempotency key for this header parameter.

Body

  • eventstringrequired

    Fixture name. Each name is the event type it produces.

    Allowed valuesmessage.receivedmessage.ackmessage.failedcall.receivedcall.missedcall.endedsession.statussession.restriction_updatedtemplate.status
  • overridesobject

    Specifies overrides for this native trigger test event request.

    Show 17 child fields
  • fromNumberstringlength1–128

    message.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
    • eventstringrequired

      Specifies event for this native trigger test event response.

      Allowed valuesmessage.receivedmessage.ackmessage.failedcall.receivedcall.missedcall.endedsession.statussession.restriction_updatedtemplate.status
    • sessionstringrequired

      Identifier of the connected Polymorfa session.

    • deliverystringrequired

      Specifies delivery for this native trigger test event response.

      Allowed valuesgeneratedsimulated
    • eventIdstring (uuid)requirednullable

      Identifier for the event.

    • sourcestringrequired

      Specifies 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.
POST /messaging/{session}/test-eventscURL
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"
}'
Response
{
  "event": "message.received",
  "session": "string",
  "delivery": "generated",
  "eventId": "00000000-0000-4000-8000-000000000000",
  "source": "test"
}

Set testing account mode

PUT/messaging/{session}/phone/account-modeMessaging APILinked Device API
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–256

    Identifier of the connected Polymorfa session.

Body

  • accountTypestringrequired

    How 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.
  • primaryPlatformstring

    Primary phone platform the Test number emulates. Defaults to android. Not accepted when accountType is meta_cloud.

    android
    An Android phone.
    ios
    An iPhone.

Responses

  • 200The account mode is set
    • sessionstringrequired

      Identifier of the connected Polymorfa session.

    • accountTypestringrequired

      How 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.
    • primaryPlatformstringrequirednullable

      Null for meta_cloud, which has no phone.

      android
      An Android phone.
      ios
      An iPhone.
    • changedbooleanrequired

      False when the Test number already used this mode. Nothing was unlinked.

    • unlinkedDevicesarray of integerrequired

      Companions 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.
PUT /messaging/{session}/phone/account-modecURL
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"
}'
Response
{
  "session": "string",
  "accountType": "whatsapp_app",
  "primaryPlatform": "android",
  "changed": true,
  "unlinkedDevices": [
    0
  ]
}