​

Push Notifications

​

Send a push

curl -X POST https://api.orbit.devotel.io/api/v1/push/send \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["user_8a1f2c"],
    "title": "New order",
    "body": "Order #12345 is ready for pickup",
    "data": {
      "order_id": "12345"
    },
    "image_url": "https://cdn.example.com/orders/12345.png",
    "deep_link": "myapp://orders/12345",
    "badge": 1,
    "notification_channel": "orders",
    "mutable_content": true,
    "interruption_level": "active",
    "apns_priority": 10,
    "actions": [
      { "id": "view", "title": "View order" },
      { "id": "dismiss", "title": "Dismiss", "destructive": true }
    ],
    "ios": {
      "sound": "default",
      "thread_id": "orders"
    },
    "android": {
      "channel_id": "orders",
      "priority": "high"
    },
    "webpush": {
      "icon_url": "https://cdn.example.com/icon.png",
      "require_interaction": true
    }
  }'

​

Targeting

• device_token_ids — array of registered device-token ids to deliver to specific devices.
• user_ids — array of Orbit user ids; pass ["*"] to broadcast to every opted-in device in the tenant (subject to the broadcast recipient cap).

​

Fields

• ios — sound, badge, category, thread_id, interruption_level, relevance_score, mutable_content, image_url, apns_collapse_id, apns_priority, apns_expiration.
• android — channel_id, priority (normal · high), ttl_seconds, image_url, notification_count, color (#RRGGBB).
• webpush — icon_url, image_url, actions ({ action, title }, at most 2, each string ≤ 64 chars), urgency, ttl_seconds, topic (must match ^[A-Za-z0-9_-]{1,32}$ — letters, digits, _ or -, 1–32 chars), require_interaction, tag (≤ 64 chars). A topic with disallowed characters or more than 2 actions is rejected with HTTP 422.

​

Scheduled send

​

Response

{
  "data": {
    "notifications": [
      {
        "id": "push_3f9c1a2b4d6e8f0a1b2c3d4e5f60718a",
        "deviceTokenId": "dtk_9f2c1a0b3d4e5f60718293a4b5c6d7e8",
        "status": "sent"
      }
    ],
    "total": 1,
    "sent": 1,
    "devices_targeted": 1
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-05-09T00:00:00Z"
  }
}

{
  "data": {
    "id": "spush_7a1f2c3d4e5b6a7980c1d2e3f4a5b6c7",
    "status": "scheduled",
    "send_at": "2026-05-09T12:00:00Z"
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-05-09T00:00:00Z"
  }
}

​

Capabilities

• Multi-platform — APNs (iOS, macOS, watchOS, tvOS, visionOS), FCM (Android), HMS Push Kit (Huawei devices without Google Play Services), and Web Push (VAPID).
• Device tokens or users — target explicit device_token_ids, a set of user_ids, or broadcast to every opted-in device with user_ids: ["*"].
• Rich content — title, body, image, action buttons, deep-link data payload, badge, sound, channel id (Android), thread id (iOS).
• Custom data payload — attach a data object (< 4 KB) that rides alongside the notification so your app can act on tap or on receipt.
• Live Activities (iOS 16.1+) — start, update, and end Live Activity notifications with the activity-specific endpoint variant.
• Delivery + open events — push.delivered and push.opened webhook events when SDK is integrated.
• Auto-token rotation on GKE — FCM service-account tokens are auto-refreshed via the GCE metadata server; no manual key management required.

​

Apple Push setup (APNs)

1. Create an APNs Auth Key — in the Apple Developer portal, go to Certificates, Identifiers & Profiles → Keys, create a key with the Apple Push Notifications service (APNs) capability, and download the AuthKey_<KEY_ID>.p8 file. Apple lets you download it once — store it in your secret manager immediately.
2. Configure the environment — set all four variables. DEVOTEL_APNS_KEY_ID, DEVOTEL_APNS_TEAM_ID, and DEVOTEL_APNS_PRIVATE_KEY must be set together; if any is missing every targeted iOS device returns status: "failed".

   Variable	Required	Where to source it
   DEVOTEL_APNS_KEY_ID	yes (iOS)	The 10-character Key ID shown next to the Auth Key under Keys when you created it.
   DEVOTEL_APNS_TEAM_ID	yes (iOS)	Your 10-character Apple Developer Team ID, on the Membership page.
   DEVOTEL_APNS_PRIVATE_KEY	yes (iOS)	The full contents of the AuthKey_<KEY_ID>.p8 file, including the -----BEGIN PRIVATE KEY----- / -----END PRIVATE KEY----- lines. Secret — provision via your secret store, never commit it.
   DEVOTEL_APNS_BUNDLE_ID	yes (iOS)	Your app’s bundle identifier (e.g. io.devotel.orbit); sent as the APNs apns-topic.
   DEVOTEL_APNS_PRODUCTION	no	Forces the production APNs host (api.push.apple.com) when set to true. This variable only takes effect under a non-production NODE_ENV — a deployment running with NODE_ENV=production always uses the production host regardless of this value, so the sandbox host (api.sandbox.push.apple.com) is only reachable when NODE_ENV is not production.

   When the trio is unset, each targeted iOS device returns status: "failed" with code MESSAGE_SEND_FAILED and the message APNs credentials not configured ….
3. Register device tokens — the mobile SDK registers each device’s APNs token (see Token onboarding); no per-device key setup is needed.

Sandbox vs production tokens are not interchangeable. A token minted by a development build only resolves against the sandbox host, while App Store / TestFlight tokens only resolve against the production host. APNs routing is driven by NODE_ENV first: when NODE_ENV=production the platform always targets the production host, and DEVOTEL_APNS_PRODUCTION has no effect. DEVOTEL_APNS_PRODUCTION=true only forces the production host under a non-production NODE_ENV. Consequently you cannot test a sandbox (development-build) token against a production deployment — it will be misrouted to the production host and rejected with BadDeviceToken. Test sandbox tokens against a non-production deployment instead.

​

Web Push setup (VAPID)

1. Generate the keypair — run once and keep the output:
   npx web-push generate-vapid-keys
   
   This prints a base64url public key and a private key.
2. Configure the environment — set the three variables on the API / push worker:

   Variable	Required	Notes
   DEVOTEL_VAPID_PUBLIC_KEY	yes (web push)	base64url public key; shared with the browser at pushManager.subscribe time.
   DEVOTEL_VAPID_PRIVATE_KEY	yes (web push)	Signs the VAPID JWT in the Authorization header on every delivery. Secret — provision via your secret store, never commit it.
   DEVOTEL_VAPID_SUBJECT	yes (web push)	A mailto: URI (or https URL) push services use to contact the app owner about abuse / outage, e.g. mailto:push-ops@orbit.devotel.io.

   When these are unset the native channels still work, but a web-push delivery cannot complete: the send still returns 201, and that device’s entry in notifications[] comes back with status: "failed" and an error noting Web Push is not configured. Native (APNs / FCM) targets in the same send are unaffected.
3. Browser registration — the web SDK calls OrbitPush.isSupported() and then pushManager.subscribe with the public key, registering the resulting subscription as a device token (see Token onboarding).

Rotating keys invalidates every existing browser subscription — clients must re-subscribe. Rotate only when the private key is compromised.

​

Huawei Push setup (HMS)

1. Create an AppGallery Connect app — in AppGallery Connect, create (or open) your project and Android app, then enable Push Kit under Grow → Push Kit. The app’s App ID and App secret are shown on the project’s General information page.
2. Configure the environment — set both variables on the API / push worker. They must be set together; if either is missing the HMS path is treated as unconfigured and the Huawei send fails (see details below).

   Variable	Required	Where to source it
   DEVOTEL_HMS_APP_ID	yes (Huawei)	The app’s App ID from AppGallery Connect → General information. It is the OAuth2 client_id and the <appId> path segment in the Push Kit send URL.
   DEVOTEL_HMS_APP_SECRET	yes (Huawei)	The app’s App secret from the same page. Used as the OAuth2 client_secret to mint a Push Kit access token. Secret — provision via your secret store, never commit it.

   When both are unset the native and web channels still work, but a Huawei send fails with Huawei Push Kit not configured — DEVOTEL_HMS_APP_ID and DEVOTEL_HMS_APP_SECRET are required. iOS / Android / Web targets in the same send are unaffected.
3. Register device tokens — register each Huawei device with platform: "huawei" and the raw HMS Push Kit registration token returned by the HMS SDK on the device (see Token onboarding). Push Kit access tokens are cached and refreshed automatically; no manual token management is needed.

​

Token onboarding

1. Integrate the Devotel mobile SDK (@devotel/orbit-mobile) or the web SDK (@devotel/orbit-web).
2. The SDK requests notification permission and registers the device token with POST /api/v1/push/device-tokens (alias: POST /api/v1/push/register) against the user’s Orbit identity.
3. Tokens are scoped per (org, app, user) and rotated automatically on platform-token refresh.

​

Common errors

​

Pricing