Push used to be the channel CPaaS platforms skipped: SMS, voice, WhatsApp, email — and a mobile engagement vendor bolted on for the app. That split is what fragments a customer record. On Devotel Orbit, push is a channel on the same account as every other channel, reachable through the same Messaging API, and it shares the contact, consent, and analytics surface with SMS, WhatsApp, RCS, and email. This guide walks through where push sits in one omnichannel flow, the lifecycle the push channel exposes end to end, how to think about push versus SMS as a fallback pair, and where AI agents fire push notifications.
Everything below references the shipped product surface: the push channel docs, the push-integration guide, and the flows recipes the docs site publishes. No capability named here is aspirational.
Where push fits next to SMS, WhatsApp, and RCS
The channel decision is per-message, not per-platform. SMS reaches any phone number with carrier-grade delivery and a per-message cost. WhatsApp and RCS carry rich, verified conversations where the user has opted into that app. Email owns long-form and receipts. Push owns one thing none of those do: reaching your own app's installed base with zero carrier fees, at the speed of an in-app event, with a deep link straight into the right screen.
In one omnichannel flow that means push is usually the first attempt for app-installed users, not a separate program:
- A flow's condition node checks whether the contact has a registered, opted-in device token, and routes the notification over push when it does.
- The same flow falls through to SMS or WhatsApp for contacts with no live token — one definition, one consent record, one analytics funnel.
- The Orbit push channel delivers to iOS (APNs), Android (FCM), Huawei (HMS Push Kit), and Web Push (VAPID) from a single
POST /api/v1/push/sendcall, so the fallback logic never forks per mobile OS.
Because targeting, suppression, and opt-out filtering happen server-side across channels, a STOP the user sent on the SMS side also holds on the push side — a fragmented stack can't give you that guarantee without a custom sync job.
The lifecycle Orbit exposes end to end
The push-integration guide walks the full loop; here is the same lifecycle as five checkpoints to design against.
1. Device token registration
A device becomes reachable once it registers a token against an Orbit user via POST /api/v1/push/device-tokens. The Web SDK's OrbitPush surface handles the browser path — VAPID key resolution, pushManager.subscribe, and the registration POST — and returns the deviceTokenId you can target directly. Native clients pass the APNs, FCM, or HMS token with a platform of ios, android, huawei, or web. Pass a stable app_install_id so a token rotation retires the predecessor instead of double-registering, and re-register on the OS refresh callback. Tokens scoped per (org, app, user); opt-out and disabled tokens get filtered server-side before any fan-out.
2. Targeting
POST /api/v1/push/send takes exactly one of three shapes: device_token_ids for specific devices, user_ids to reach a user wherever they registered (the transactional shape — "order ready for pickup"), or user_ids: ["*"] to broadcast to every opted-in device in the tenant, capped at 100,000 deliverable tokens. Omitting both fails validation with a 422.
3. Send — immediate or scheduled
An immediate send returns 201 with a per-device result list; a future send_at returns 202 with a scheduled-push id and replays through the identical targeting, caps, and suppression gates at send time. The scheduled surface (GET/DELETE /api/v1/push/scheduled[/:id]) lists, inspects, and cancels queued sends.
4. Per-device delivery results
A top-level 201 is not a delivery guarantee — read notifications[] per device. sent means the provider accepted it; failed carries a per-device error string (expired token, mis-shapen payload, unconfigured platform credentials); skipped means the platform gated the device (frequency cap, suppression). Permanently-gone tokens retire automatically, so the next send skips them.
5. Engagement
Once the SDK or service worker is integrated, push.delivered and push.opened webhook events close the loop. The client acks POST /api/v1/push/notifications/:id/ack with event: "delivered" | "opened"; the ack is idempotent, so duplicate acks never re-emit the webhook. GET /api/v1/push/notifications exposes the per-notification delivered_at / opened_at timestamps for analytics reconciliation.
Push vs SMS as fallback channels: an honest read
Push is not "free SMS." The trade-off is real and worth stating plainly:
- Cost. Push delivery carries no carrier fees — Orbit charges a flat per-1M platform fee for fan-out (see the pricing page). SMS bills per message segment. For high-frequency transactional traffic to an installed app base, push is materially cheaper per notification.
- Reach. Push only reaches registered, opted-in devices of your app. SMS reaches any phone number. A fallback chain that starts with push must keep SMS (or WhatsApp) behind it, or the non-app audience goes dark.
- Compliance posture. Push consent is handled at the OS prompt and your own preference center; there is no carrier-mandated
STOPvocabulary. Orbit still filters STOP / channel-level suppression server-side on push, and tenant-owned controls (frequency caps, quiet-hours policy) apply the same way as on messaging channels — the entities remain yours to set. The point: cheaper per send does not mean exempt from your own consent record. - Delivery semantics. APNs/FCM give you accepted/not-accepted; carriers give you DLRs. Orbit normalizes both into per-device result rows and webhook events, so the fallback chain can be measured on one funnel instead of two vendor dashboards.
That consolidation argument — one provider across the channel layers versus a mobile-engagement vendor bolted onto a CPaaS — is the same frame we apply to the whole stack in the one-provider vs multi-vendor PaaS analysis: the multi-vendor cost is paid in integration maintenance and reconciliation, not as a visible line item.
AI agents as push triggers
Push rarely fires from a marketing calendar alone. On Orbit the two shipped trigger surfaces that send push are:
- Flows. A business-event trigger (
contact.created, an inbound-message event,call.completed), a schedule, or an external webhook starts a run; a condition node gates on consent or device presence; the send node fires push alongside or instead of SMS and email. The flows recipes page ships working definitions for the five automations every team asks for, and its survey recipe acceptspushas a delivery channel alongsidesms,whatsapp,email,viber, andrcs. - AI agents. A flow's
aiClassifynode routes an inbound message by intent, anaiAgentnode answers it, and the push step notifies the customer (or your on-call team) on the outcome — for example, an order-exception agent that pushes a "your delivery needs attention" notification with a deep link into the resolution screen.
Either way, the push send inherits the same suppression, frequency-cap, and scheduled-send machinery as an API-initiated send — nothing about an agent origin bypasses the tenant-owned gates.
Before you ship: the rough edges to design for
- Token lifecycle is the real work. Registration, rotation with
app_install_id, re-registration on refresh, and handling theregister() === nullbranch in onboarding UI are the actual integration. The send call is the easy part. - Credential groups fail atomically. APNs needs its key/trio set together; VAPID needs public + private + subject; HMS needs app id + secret. A partial group fails every device on that transport with a per-device
failed— the production checklist enumerates each group. - Sandbox vs production APNs is a routing decision. Sandbox tokens only resolve against the sandbox host, and a production deployment always targets the production host — test sandbox tokens against a non-production deployment.
- VAPID rotation invalidates every browser subscription. Rotate only on compromise; clients must re-subscribe.
Frequently asked questions
Does push on Orbit cost per message like SMS?
No. Push delivery carries no carrier fees; Orbit charges a flat platform fee per 1M fan-out. Per-message carrier cost is exactly the trade push makes against SMS's reach-any-number property.
Can I target by topic or device group instead of users?
No to / topic field exists. POST /api/v1/push/send takes exactly one of device_token_ids, user_ids, or user_ids: ["*"] for a broadcast capped at 100,000 deliverable tokens. Segment your audience into explicit user_ids batches rather than topics.
What happens when a user opts out on SMS — does push still reach them?
Suppression is server-side across channels. A STOP or channel-level opt-out filters that user's push devices before fan-out, so a broadcast only reaches deliverable devices. Your tenant's own frequency caps and preference rules apply to push the same way they apply to messaging.
How do I know a push actually landed, not just that the API accepted it?
Read the per-device notifications[] result for sent / failed / skipped, and wire the push.delivered and push.opened webhook events once the SDK or service worker is integrated. GET /api/v1/push/notifications gives the per-notification delivered/opened timestamps for reconciliation.
Is there a test path that doesn't pollute campaign stats?
Yes — POST /api/v1/push/test-send fires against the calling user's own devices and validates the whole credential chain end to end without touching campaign metrics.
Where do AI agents push from?
From a flow: a business-event, schedule, webhook, or AI-classify/agent node chain ends in a push send with the same targeting shapes as the API. The docs' flows-recipes page has the pattern, and its survey recipe lists push as a delivery channel next to SMS, WhatsApp, email, Viber, and RCS.