Send your first test message
Create two test numbers, send a message between them and trigger a test event.
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
- Open the project and go to Numbers.
- Under Test numbers, select Add test number.
- Choose a country for the generated phone number.
- 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.
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" } }
}'{
"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
- Select Open test setup. The setup page opens in a new tab.
- Select Create simulated account. The page shows the generated phone number when the account is ready.
- 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:
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:
curl -X POST "https://api.polymorfa.com/quicklink/$QUICKLINK_TOKEN/confirm" \
-H "Content-Type: application/json" \
-d '{}'{
"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:
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
- On the Numbers page, under Test numbers, choose Phone controls beside the first test number.
- Under Send from phone, choose the second test number in To.
- 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:
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:
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:
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.
| Scenario | Result |
|---|---|
| Recipient is another connected test number in the project | The message is delivered |
| Recipient is in another project, is a real Number, is stopped or is not a test number | 404 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:
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.