> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendrealm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Push Notification

Send a push notification to Sendrealm push devices, contacts, external IDs,
email addresses, raw push tokens, or audiences.

## Targeting

Use one Sendrealm targeting style per request:

* `tokens`: raw Android FCM or iOS APNs push tokens with their platform.
* `web_subscriptions`: raw browser `PushSubscription.toJSON()` objects for direct Web Push sends.
* `device_ids`: Sendrealm push device IDs created by the SDK.
* `contact_ids`: Sendrealm contact IDs.
* `external_ids`: stable IDs set with SDK login or the server API.
* `emails`: contact email addresses.
* `audiences`: audience IDs for queued or scheduled audience sends.

Use `excluded_audiences` with contact, external ID, email, or audience sends to
remove contacts that belong to specific audiences. Use `platforms` to limit
delivery to `android`, `ios`, or `web`. Web devices registered by the React SDK
can be targeted through device, contact, external ID, email, audience, or
`platforms: ["web"]` filters.

Set `environment` to `development` to target devices registered by development
SDK builds. Omit it, or set `production`, for production devices. This is
separate from iOS `apns_environment`.

Audience sends are queued through the push broadcast delivery pipeline. Direct
device, token, contact, external ID, and email sends are delivered immediately.

## Body

```json theme={null}
{
  "app_id": "push_app_short_id",
  "environment": "development",
  "audiences": ["018f5b8d-2e2d-7a9b-9000-1c24e8a3b2c1"],
  "excluded_audiences": ["018f5b91-8f46-7f1d-a111-df39fd4b98a0"],
  "platforms": ["ios", "android"],
  "scheduled_at": "2026-06-21T20:30:00.000Z",
  "notification": {
    "title": "Order update",
    "body": "Your order is ready.",
    "launch_url": "myapp://orders/123",
    "image_url": "https://example.com/order.png"
  },
  "buttons": [
    {
      "id": "view_order",
      "text": "View order",
      "launch_url": "myapp://orders/123"
    }
  ],
  "data": {
    "order_id": "123"
  },
  "ios": {
    "sound": "default",
    "badge": 1,
    "apns_environment": "sandbox"
  },
  "android": {
    "channel_id": "orders",
    "sound": "default",
    "ttl": "3600"
  }
}
```

For direct browser sends, pass browser subscriptions separately from mobile
tokens:

```json theme={null}
{
  "app_id": "push_app_short_id",
  "web_subscriptions": [
    {
      "endpoint": "https://fcm.googleapis.com/fcm/send/...",
      "expirationTime": null,
      "keys": {
        "p256dh": "base64url-key",
        "auth": "base64url-secret"
      }
    }
  ],
  "notification": {
    "title": "New message",
    "body": "Open the inbox."
  }
}
```

Use `buttons` to attach up to three notification actions. Android renders the
button text directly. iOS sends Sendrealm's default action category and includes
the button payload for SDK action tracking and deep-link handling.

For localized messages, send `messages` with locale codes:

```json theme={null}
{
  "app_id": "push_app_short_id",
  "contact_ids": ["018f5b8d-2e2d-7a9b-9000-1c24e8a3b2c1"],
  "messages": [
    {
      "code": "en-US",
      "label": "English",
      "title": "Welcome back",
      "body": "You have a new update."
    },
    {
      "code": "pt-BR",
      "label": "Portuguese",
      "title": "Bem-vindo de volta",
      "body": "Voce tem uma nova atualizacao."
    }
  ],
  "notification": {
    "title": "Welcome back",
    "body": "You have a new update."
  }
}
```

## Tags And Contact Properties

SDK tags are client-sourced key/value data used for app behavior, preferences,
audience targeting, and personalization. They are useful for values the app can
observe directly, such as onboarding status, selected interests, locale, or app
version.

Server contact properties are authoritative backend data. Use the Contacts API
for account, billing, compliance, lifecycle, verified profile, and CRM values.
SDK tag writes cannot overwrite server-owned or system-owned contact
properties.

Protected SDK tag keys include identity and Sendrealm/system fields. Keys that
start with `sendrealm_`, `sys_`, `billing_`, `security_`, or `account_` are
reserved. Audience properties are server-owned by default; set
`sdk_writable: true` on an audience property only when the mobile app is allowed
to manage that value.

## Reporting

Each send records push notification rows and events for provider accepted sends,
failures, opens, clicks, and SDK-tracked custom events. Provider accepted means
the push provider accepted the request; it is not the same as confirmed display
on the physical device.