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

Send your first test message

Create two test numbers, send a message between them and trigger a test event.

View as Markdown

Create two test numbers in one project, send a message from one to the other and trigger a test event. Everything runs on the simulated WhatsApp network, so you don't need a phone or a second person.

Create a test number#

Console

  1. Open the project and go to Numbers.
  2. Under Test numbers, select Add test number.
  3. Choose a country for the generated phone number.
  4. Leave Profile and behavior, Test history and Recipient customization closed to keep their defaults, then select Create setup link.

The dialog shows the new setup link.

API

Create a QuickLink with a configuration.testing object. country is optional; the other options are in Simulated setup scenarios.

Shell
curl -X POST "https://api.polymorfa.com/messaging/quicklinks" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "'"$PROJECT_ID"'",
    "configuration": { "testing": { "country": "US" } }
  }'
JSON
{
  "success": true,
  "data": {
    "id": "ql_0c1d8f2a3b4c5d6e7f80",
    "url": "https://www.polymorfa.com/connect/<token>",
    "session": "739182640518203",
    "expiresAt": null
  }
}

Save session: it names the test number in Messaging API paths. A project token can omit projectId. A team key must include it when the team has more than one project.

Complete the simulated setup#

Creating the QuickLink reserves the test number. Completing its setup creates the simulated account and connects it.

Console

  1. Select Open test setup. The setup page opens in a new tab.
  2. Select Create simulated account. The page shows the generated phone number when the account is ready.
  3. Select Finish setup.

The Console dialog shows the link as connected, and the test number appears under Test numbers on the Numbers page.

API

The QuickLink token is the last path segment of url. Start the simulated account:

Shell
curl -X POST "https://api.polymorfa.com/quicklink/$QUICKLINK_TOKEN/testing/start"

The response is the link's state. When data.testing.state is ready, data.testing.phone holds the generated phone number. If the state is still starting, repeat the request; it is safe to retry. Then finish the link:

Shell
curl -X POST "https://api.polymorfa.com/quicklink/$QUICKLINK_TOKEN/confirm" \
  -H "Content-Type: application/json" \
  -d '{}'
JSON
{
  "data": {
    "status": "connected",
    "phone": "+15550100001",
    "historySync": false,
    "redirectUrl": null
  }
}

These two requests use the token instead of an API key. Treat the token as a secret and don't log it.

Create a second test number#

Repeat the two steps above. Note the second test number's session value and phone number: it is the recipient in the next steps. Both test numbers must be in the same project.

Check the phone#

Every test number has a simulated phone that acts as its main device.

Console

On the Numbers page, under Test numbers, choose Phone controls beside the first test number. The dialog shows whether the phone is online and lists its linked devices.

API

From here on, use the project's Test key. It calls only operations on the project's test numbers, so it can't reach a real Number. It can't create QuickLinks, which is why the steps above need a team key or project token. In the API reference, open the Test key menu at the top of its navigation (in the menu on phones), sign in and select Reveal Test key. Code samples on methods marked as available with the Test key then use it. See Test key for what it can call.

Read the first test number's phone. $SESSION is its session value and $POLYMORFA_KEY is the Test key:

Shell
curl "https://api.polymorfa.com/messaging/$SESSION/phone" \
  -H "Authorization: Bearer $POLYMORFA_KEY"

online is true once setup has finished, and devices lists the linked devices. See Phone controls.

Send a message#

Console

  1. On the Numbers page, under Test numbers, choose Phone controls beside the first test number.
  2. Under Send from phone, choose the second test number in To.
  3. Enter a message and select Send.

The message is sent from the first test number's phone, the same way a person types on their phone.

API

Send from the first test number to the second one's phone number:

Shell
curl -X POST "https://api.polymorfa.com/messaging/$SESSION/messages/send" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": { "phoneNumber": "+15550100002" },
    "content": { "text": "Hello from a test number" }
  }'

A successful response has "success": true and the sent message in data.

To send as the person holding the first test number's phone instead, use the phone:

Shell
curl -X POST "https://api.polymorfa.com/messaging/$SESSION/phone/messages" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+15550100002", "text": "Hello from the phone" }'

See the message arrive#

List the second test number's chats. $SESSION_2 is its session value:

Shell
curl "https://api.polymorfa.com/messaging/$SESSION_2/chats" \
  -H "Authorization: Bearer $POLYMORFA_KEY"

The list includes the chat with the first test number. If you registered a webhook for message.received, it receives the event for the second test number.

With Inspector, select the project and choose Open beside the second test number. The message appears in a chat with the first test number. Reply from Inspector, and the reply reaches the first test number like any incoming message.

ScenarioResult
Recipient is another connected test number in the projectThe message is delivered
Recipient is in another project, is a real Number, is stopped or is not a test number404 resource_not_found; nothing is created
Sender was created with failureScenario: "reject-send"The send fails, so you can test your error handling
Recipient was created with replyBehavior: "echo"The recipient sends your text back to the sender

Trigger a test event#

A test event delivers a signed webhook event without WhatsApp activity. List the fixtures, then trigger one for the second test number:

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

curl -X POST "https://api.polymorfa.com/messaging/$SESSION_2/test-events" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event": "message.ack", "overrides": { "ackStatus": "read" } }'

The API returns 202 Accepted with an eventId. Your webhooks and event history receive the event with source: "test". See Trigger test events for every fixture.

Your two test numbers now exchange messages through the same Messaging API methods and events as real Numbers.

Next steps#