---
title: "Push Notifications API"
description: "Send push notifications to your app's users by user reference, device token, topic or segment, with images, deep links, actions, templates and dry runs."
canonical: "https://omnichannels.ai/developers/push/"
language: "en"
updated: "2026-10-10"
publisher: "BroadNet Technologies"
brand: "OmniChannels.ai"
section: "Messaging channels"
---

# Push Notifications API

Canonical: https://omnichannels.ai/developers/push/
Language: en
Publisher: OmniChannels.ai by BroadNet Technologies

The Push API sends notifications to users of your mobile app. You call `POST /push/message/send` with a JSON body that names the audience (users, device tokens, topics or a segment) and the content.

## Before you send

Your app is registered for push during onboarding: our team connects your Firebase Cloud Messaging (FCM) project and, for iOS, your APNs credentials, and gives you your app ID. Your app then registers each device against your own user identifier, the **userRef**.

To see which userRefs and tokens are registered on your account, call `GET /push/template/device-tokens`.

## Send a notification

```bash title="cURL"
curl -X POST https://api.broadnet.me/push/message/send \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userRefs": ["user-10293"],
    "title": "Your order has shipped",
    "body": "Tap to track your parcel.",
    "deepLink": "https://example.com/orders/8842",
    "category": "UTILITY",
    "priority": "HIGH",
    "ttl": 3600
  }'
```

```js title="Node.js"
const res = await fetch("https://api.broadnet.me/push/message/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BROADNET_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userRefs: ["user-10293"],
    title: "Your order has shipped",
    body: "Tap to track your parcel.",
    deepLink: "https://example.com/orders/8842",
    category: "UTILITY",
    priority: "HIGH",
    ttl: 3600,
  }),
});
console.log(res.status, await res.text());
```

```python title="Python"
import os
import requests

r = requests.post(
    "https://api.broadnet.me/push/message/send",
    headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
    json={
        "userRefs": ["user-10293"],
        "title": "Your order has shipped",
        "body": "Tap to track your parcel.",
        "deepLink": "https://example.com/orders/8842",
        "category": "UTILITY",
        "priority": "HIGH",
        "ttl": 3600,
    },
    timeout=15,
)
print(r.status_code, r.text)
```

```php title="PHP"
<?php
$ch = curl_init("https://api.broadnet.me/push/message/send");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BROADNET_TOKEN"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "userRefs" => ["user-10293"],
        "title" => "Your order has shipped",
        "body" => "Tap to track your parcel.",
        "deepLink" => "https://example.com/orders/8842",
        "category" => "UTILITY",
        "priority" => "HIGH",
        "ttl" => 3600,
    ]),
]);
echo curl_exec($ch);
curl_close($ch);
```

## Choose the audience

Use one targeting option per request:

| Field | Type | Description |
| --- | --- | --- |
| `userRefs` | array of strings | Your own user identifiers. The platform resolves them to devices. Recommended. |
| `tokens` | array of strings | Explicit FCM device tokens. |
| `topics` | array of strings | FCM topics, for broadcast to subscribed devices. |
| `segment` | object | Criteria such as `country`, `city`, `language` and `tags`, with your `appId`. |

## Content and delivery fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string | Yes, unless data-only or template | Notification title. |
| `body` | string | Yes, unless data-only or template | Notification text. |
| `category` | string | Recommended | For example `UTILITY`, `MARKETING` or `AUTHENTICATION`. |
| `priority` | string | No | `HIGH` for time-sensitive messages. |
| `image` | string | No | HTTPS image URL for a big-picture notification. |
| `deepLink` | string | No | Link opened on tap. |
| `actions` | array | No | Action buttons, each with `id`, `title` and `action`. |
| `data` | object | No | Custom key-value data for your app. |
| `dataOnly` | boolean | No | Deliver as a data message that your app handles, even in the background. |
| `silent` | boolean | No | Background sync with no visible notification. |
| `ttl` | integer | No | Time to live, in seconds. |
| `collapseKey` | string | No | Newer notifications with the same key replace older ones. |
| `channel` | string | No | Android notification channel. |
| `templateId` | string | No | Send a stored template; `data` fills its variables. |
| `dryRun` | boolean | No | Validate the request without delivering anything. |
| `appId` | string | For campaigns and segments | Your app ID. |
| `campaignName` | string | No | Your label for reporting. |
| `schedule` | object | No | `scheduled`, `scheduleTime`, `gmt` and `campaignType` (for example `BROADCAST`). |

Use `dryRun: true` to check a payload end to end before sending to real users.

### Notification with actions

```json title="Request body"
{
  "userRefs": ["user-10293"],
  "title": "Appointment tomorrow at 10:00",
  "body": "Please confirm or reschedule.",
  "category": "UTILITY",
  "priority": "HIGH",
  "actions": [
    { "id": "confirm", "title": "Confirm", "action": "omnidemo://appt/confirm/12" },
    { "id": "reschedule", "title": "Reschedule", "action": "omnidemo://appt/reschedule/12" }
  ],
  "ttl": 3600
}
```

## Templates

| Method | Path | Description |
| --- | --- | --- |
| POST | `/push/template/create` | Create a template. |
| POST | `/push/template/list` | List templates. |
| POST | `/push/template/{TEMPLATE_ID}/preview` | Preview with sample data. |
| POST | `/push/template/{TEMPLATE_ID}/test-send` | Send a test to your own device. |
| POST | `/push/template/{TEMPLATE_ID}/publish` | Publish a template version. |
| GET | `/push/template/{TEMPLATE_ID}/history` | Version history. |

## Batches

| Method | Path | Description |
| --- | --- | --- |
| POST | `/push/message/batches` | List or filter batches. |
| GET | `/push/message/edit?batchId=…` | Batch details. |
| GET | `/push/message/pause?batchId=…` | Pause a batch. |
| GET | `/push/message/resume?batchId=…` | Resume a batch. |
| DELETE | `/push/message/abort?batchId=…` | Abort a batch. |

Push batch endpoints take `batchId` (like RCS), not `batch_Id`.

## Geofences

The Push API can also trigger notifications by location. Geofences are managed under `/push/geofence` (create, list, enable, disable and audit). Ask our team to enable geofencing for your app.

## Next steps

- [Webhooks](/developers/webhooks/): track delivery statuses.
- [Email](/developers/email/): reach users outside the app.
- [Errors and limits](/developers/errors-and-limits/): retries and rate limits.