Push Notifications API | OmniChannels.ai Docs

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#

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
  }'

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

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

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

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: track delivery statuses.
Email: reach users outside the app.
Errors and limits: retries and rate limits.

Ready to send your first message?

Request test credentials. An engineer sets up your account, and test sends go to your own verified numbers.

Request test access