Skip to main content

Documentation Index

Fetch the complete documentation index at: https://orbit-docs.devotel.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Push Notifications

Orbit’s Push channel delivers notifications to iOS (APNs), Android (FCM), and Web Push (VAPID) subscribers from a single API surface. Token registration, capability flags (sound, badge, mutable-content), and per-device delivery results are surfaced through the same Messaging API used for every other channel.

​
Send a push

curl -X POST https://orbit-api.devotel.io/api/v1/messages/push \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "<device_token_or_topic>",
    "from": "<app_id>",
    "title": "New order",
    "body": "Order #12345 is ready for pickup",
    "data": {
      "deep_link": "myapp://orders/12345"
    },
    "ios": {
      "sound": "default",
      "badge": 1
    },
    "android": {
      "channel_id": "orders",
      "priority": "high"
    }
  }'

​
Response

{
  "data": {
    "message_id": "msg_push_abc123",
    "status": "queued",
    "channel": "push",
    "platforms": ["apns", "fcm"]
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-05-09T00:00:00Z"
  }
}

​
Capabilities

  • Multi-platform — APNs (iOS, macOS, watchOS, tvOS, visionOS), FCM (Android), and Web Push (VAPID).
  • Tokens or topics — target a specific device token or fan out to a topic / segment.
  • Rich content — title, body, image, action buttons, deep-link data payload, badge, sound, channel id (Android), thread id (iOS).
  • Silent / data-only push — flag content_available (iOS) / data only (Android) for background sync.
  • 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.

​
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 /v1/push/devices against the user’s Orbit identity.
  3. Tokens are scoped per (org, app, user) and rotated automatically on platform-token refresh.

​
Common errors

CodeHTTPCauseFix
PUSH_INVALID_TOKEN422Token format is malformed for the requested platform.Verify the SDK is registering the platform-specific token.
PUSH_TOKEN_EXPIRED410APNs / FCM has marked the token as unregistered (app uninstalled, token rotated).Remove the token from your audience; SDK will re-register on next launch.
PUSH_NO_CERT_OR_KEY412The org has not uploaded the APNs auth key (.p8) or the FCM service account JSON.Upload credentials in Channels → Push → Setup.
PUSH_PAYLOAD_TOO_LARGE413Payload exceeds the platform limit (4KB APNs, 4KB FCM).Move large data into your backend and pass an id in data.
PUSH_RATE_LIMITED429Burst rate exceeded for APNs (per-topic) or FCM (per-project).Back off and respect Retry-After; campaigns API will pace automatically.

​
Pricing

Push delivery itself is free of carrier fees. Orbit charges a per-1M flat platform fee for fan-out. See the pricing page.