> This page is part of the [Customer.io documentation](https://docs.customer.io). For the complete index, see [llms.txt](https://docs.customer.io/llms.txt).
> Last updated: October 27, 2026
> To take actions in Customer.io from an agent, use the [Customer.io CLI](https://docs.customer.io/ai/cli/get-started.md) or the [MCP server](https://docs.customer.io/ai/mcp/get-started.md).

# Send transactional web push

Send a transactional push message to people's browsers, or to their phones and browsers together, by choosing the message's platform in the UI or in your API request.

Contact us to turn on web push

Web push is in alpha. If you don’t see a **Web** tab under [**Settings > Push**](https://fly.customer.io/env/last/settings/actions/push/web), contact us to turn it on for your account.

A [transactional push message](https://docs.customer.io/messaging/send/transactional/push/) can send to a person’s browsers as well as their iOS and Android devices. Each transactional push message has a **Platform** that decides which of a person’s devices it sends to. A new message starts on **iOS & Android**, which never sends to browsers, so the transactional push messages you already send keep going to phones only.

## Before you begin

*   [Set up web push](https://docs.customer.io/messaging/channels/web-push/set-up/) on your website, so that the people you want to reach have web devices on their profiles.
*   Generate your web push keys under [**Settings > Push > Web**](https://fly.customer.io/env/last/settings/actions/push/web). The **Platform** setting only appears on transactional push messages after you set up web push in your workspace.

Wait a couple of minutes after web push is turned on

After we turn on web push for your account, allow a couple of minutes before you choose **Web** on a message or send `platform: "web"` in an API request. Until then, Customer.io can still tell you that web push isn’t enabled for your workspace.

## Choose a platform

Platform

Sends to

**iOS & Android** (default)

The person’s iOS and Android devices. It never sends to browsers.

**iOS**

The person’s iOS devices only.

**Android**

The person’s Android devices only.

**Web**

The person’s browsers only.

**iOS, Android & Web**

The person’s iOS devices, Android devices, and browsers.

1.  Go to the **Transactional** page and create a message, or open an existing push message.
2.  In the **Content** step, choose **Push**, then choose a **Platform** before you add content. The platform decides which fields the composer shows.
3.  Click **Add content** and write your notification. See [write your notification](#composer).
4.  Configure your message settings and activate your message, the same way as any [transactional push](https://docs.customer.io/messaging/send/transactional/push/). You can change the platform later in the **Settings** step.

When you change a message from a native platform to **Web** or **iOS, Android & Web**, Customer.io clears its **App** if it matches the workspace’s current default app. A different app stays selected. When you change back to a native platform, Customer.io restores the default app only if the message has no app selected. Your **Device** choice stays the same.

If web push is later turned off for your workspace, a message set to **Web** or **iOS, Android & Web** keeps its platform, but Customer.io stops sending it to browsers. The **Platform** setting then only lets you change the message to a native platform.

## Write your notification

A message set to **Web** opens the same composer as a [web push action](https://docs.customer.io/messaging/channels/web-push/send/). It has the same [notification fields](https://docs.customer.io/messaging/channels/web-push/send/#fields) and [**Advanced options**](https://docs.customer.io/messaging/channels/web-push/send/#advanced-options), and it hides settings that only apply to mobile apps, like **Notification Sound** and **Message Priority**. Use the **Rich Push** editor; Customer.io doesn’t send **Custom Payload** messages to browsers.

A message set to **iOS, Android & Web** shows the mobile fields and the web fields together. **Title**, **Message**, **Image**, **Link**, and **Custom Data** go to every device. The browser-only fields, like **Notification icon**, **Badge**, **Action buttons**, and **Advanced options**, only affect browsers. **Notification Sound** and **Message Priority** only affect phones. If you switch this message to the **Custom Payload** editor, Customer.io sends it to the person’s phones and skips their browsers.

### App

If your composer shows an **App** setting, it decides which of your apps the message belongs to.

*   On a **Web** message, **App** starts with **All browsers (no app)**, which sends to all of a person’s browsers.
*   On an **iOS, Android & Web** message, **App** starts with **All apps and browsers (no app)**, which sends to the person’s devices in all of your apps and to all of their browsers.

Keep the no-app choice unless you have a reason to choose an app. If you choose an app, a browser only receives the message if it belongs to that app, or if the browser has no app and the app you chose is your workspace’s default app. There is no website selector.

### Device

**Device** (**To** in workspaces without the **App** setting) decides which of the person’s eligible devices receive the message. Customer.io only picks among devices on the message’s platform.

*   **Last used device** sends to the person’s most recently used device on the message’s platform. On a **Web** message, that’s their most recently used browser, so their phone never takes its place. On an **iOS, Android & Web** message, it’s the newest of all their phones and browsers.
*   **All profile devices** sends to every eligible device on the message’s platform.
*   **Custom device token** sends to one device. For a browser, use its device token, the push address that starts with `https://`.

### Preview your notification

On a **Web** message, the preview shows the browser notification, with a menu of browsers and operating systems to preview. See [preview your notification in each browser](https://docs.customer.io/messaging/channels/web-push/send/#preview). On an **iOS, Android & Web** message, the composer’s preview shows the browser notification below the phone notification. Outside the composer, the message’s content preview shows them side by side.

### Test your message

Click **Send test…**. If the dialog shows a **Device** menu, choose **Web**, then paste your browser’s subscription JSON. See [test a web push action](https://docs.customer.io/messaging/channels/web-push/send/#test) for how to get it.

## Send with the API

Send a transactional web push with [`POST /v1/send/push`](https://docs.customer.io/integrations/api/app/tag/send-messages/sendPush/), like any transactional push. If the message’s platform is **Web** or **iOS, Android & Web**, you don’t need to change your request.

To choose the platform for one send, add `platform` to your request. It accepts the same platforms as the UI:

`platform`

Sends to

`all`

iOS and Android devices.

`ios`

iOS devices only.

`android`

Android devices only.

`web`

Browsers only.

`all_and_web`

iOS devices, Android devices, and browsers.

The request’s `platform` applies to that send only, and it takes precedence over the platform you saved on the message. It doesn’t change the saved message. If you leave `platform` out, Customer.io uses the message’s platform.

Use `https://api.customer.io/v1/send/push` for US accounts or `https://api-eu.customer.io/v1/send/push` for EU accounts. The example below uses the US endpoint.

For example, this request sends a message to the person’s most recently used browser:

```
curl --request POST \
  --url https://api.customer.io/v1/send/push \
  --header "Authorization: Bearer $APP_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "transactional_message_id": "booking_confirmed",
    "platform": "web",
    "to": "last_used",
    "identifiers": { "id": "user_123" },
    "title": "Your booking is confirmed",
    "message": "See you on March 14.",
    "link": "https://www.example.com/bookings/8812"
  }'
```

What to know when you send to browsers with the API:

*   **`to`** picks within the platform. `last_used` sends to the person’s most recently used device on that platform, `all` sends to every device on it, and a device token sends to that one device. A browser’s device token is the push address that starts with `https://`.
*   **Content from your request reaches browsers.** `title`, `message`, `link`, `image_url`, and `custom_data` build the browser notification, even when the message has no saved web content. `sound` only applies to iOS. If your request includes `custom_payload`, Customer.io doesn’t send the message to browsers.
*   **`auto_create`** creates the message with the platform of your first request. If your first request sends `"platform": "web"`, the new message sends to browsers, with no app, and later requests for it don’t need `platform`. If your first request has no `platform`, the new message is **iOS & Android**. See [auto-create push records](https://docs.customer.io/messaging/send/transactional/push/#auto-create-push-records).
*   **`disable_message_retention`** works the same way for browsers as for phones: Customer.io doesn’t keep the notification content in delivery history.

### Errors

If web push isn’t turned on for your account, a request that sets `platform` to anything other than `all` fails with `400 Bad Request`:

```
{
  "meta": {
    "error": "\"platform\" is only available when web push is enabled for the workspace."
  }
}
```

If `platform` isn’t one of these values, the request fails with `400 Bad Request` and the error `"platform" must be one of all, ios, android, web or all_and_web.`

## Metrics

Transactional web push uses the same [push metrics](https://docs.customer.io/messaging/channels/push/notifications-tracking/) as other web push: **Sent**, **Delivered**, and **Opened**. See [metrics](https://docs.customer.io/messaging/channels/web-push/send/#metrics).

When web push is enabled and a message has delivery activity for **Web** and at least one other platform, its **Overview** shows a **Platform** menu next to the metrics chart. It starts on **All platforms** and lists only the platforms with activity. Created, failed, suppressed, and undeliverable deliveries count as activity too. If the menu isn’t shown, a message set to **Web** shows a **Web** label. Platform breakdowns are available for deliveries created after this feature’s release on October 26, 2026. Earlier deliveries aren’t backfilled.