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

> **Note**
>
> **Before you begin.** Your team needs [test numbers access](https://docs.polymorfa.com/testing). You need
> a project, and either Console access to it or a team key or project token with
> `quicklink:manage` to create the test numbers. After that, every API step works
> with the project's Test key. A team key or project token with `messages:write`,
> `chats:read`, `sandbox:read` and `sandbox:write` also works. Keep keys on a
> trusted server. [Inspector](https://docs.polymorfa.com/testing/inspector/install) is optional.

## 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](https://docs.polymorfa.com/testing#simulated-setup-scenarios).

```bash
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:

```bash
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:

```bash
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](https://docs.polymorfa.com/testing/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:

```bash
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](https://docs.polymorfa.com/testing/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:

```bash
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:

```bash
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:

```bash
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](https://docs.polymorfa.com/development/webhooks) 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:

```bash
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](https://docs.polymorfa.com/testing/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

- **[Trigger test events](https://docs.polymorfa.com/testing/test-events)**
Send signed webhook events without WhatsApp activity.

- **[Phone controls](https://docs.polymorfa.com/testing/phone-controls)**
Check linked devices and unlink one as the phone would.

- **[Test numbers](https://docs.polymorfa.com/testing/test-numbers)**
Stop, start and remove test numbers, and review their limits.

- **[Send a message](https://docs.polymorfa.com/api/messages/send-message)**
Every message type the send method accepts.
