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.

A transactional push message 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 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. The Platform setting only appears on transactional push messages after you set up web push in your workspace.

Choose a platform

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.
4. Configure your message settings and activate your message, the same way as any 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. It has the same notification fields and 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. 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 for how to get it.

Send with the API

Send a transactional web push with POST /v1/send/push, 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:

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.
• 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 as other web push: Sent, Delivered, and Opened. See 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.