Live Activities API

Mobile Live Activities exposes Apple's Live Activity framework to Insider One customers through a SaaS API. For dynamic on-device notifications (e.g., live match scores, live order status, package tracking, flight status, and navigation), the customer sends start/update/end commands from its own backend to the Insider API; Insider One acts as a proxy for the content and delivers it to the device via Apple. Rendering on the device occurs via Apple's ActivityKit framework; the content schema and rendering responsibility are entirely the customer application's responsibility.

Two integration flows are supported:

• Push-to-Start flow (iOS 17.2+): The customer calls /register → /start → /update* → /end. Insider One prepares the segment and starts the live activity via push.

• SDK-First flow (iOS 16.1+): The device application starts the Live Activity itself. The Insider One’s Mobile SDK collects the token and forwards it to Insider One together with the activity_type. The customer can then manage the activity via the API using /update and /end. The validity period on Insider One's side for a device-started activity is 1 week; if /end is not called within this period, no additional data is retained.

https://gw.useinsider.com

Integration overview

You will follow these four main steps to complete the integration:

1. Create an OAuth 2.0 credential

Your existing Insider API key must be renewed. After renewal, the key becomes authorized for Live Activity. Contact the Insider One team for details.

2. Activate the Live Activity product

The product must be activated on your account. Contact the Insider One team for activation. Activation permanently consumes 1 unit of your active orchestration limit.

3. Integrate the SDK

iOS 17.2+ for the Push-to-Start flow, iOS 16.1+ for the SDK-First flow. Token collection/synchronization is handled by the SDK automatically.

4. API flow

• POST /register: Register the target insider_ids segment for an activity_type, receive an activity_id.

• POST /add-users / POST /remove-users: update the segment before /start. (Optional)

• POST /start: Start the segment, send the first push message.

• POST /update: Update the content as often as you need.

• POST /end: Send the final message and close the activity when done.

Keep in mind before production

• activity_type must match the ActivityAttributes class name on the device exactly (case-sensitive). On a mismatch, the push is sent, but the device fails silently.

• The enum values in content_state must exactly match the enum cases in the iOS application.

• Content responsibility belongs entirely to the customer. Insider One does not validate or modify the content.

• Insider One is not liable for any user-experience issues that may arise from Live Activities.

Authentication

Live Activities is served over the Insider API Gateway and authenticates with OAuth 2.0. Create a credential once in the panel, exchange it for a bearer token, and send that token with every request. See OAuth 2.0 Credentials.

POST https://gw.useinsider.com/api/mob/v2/live-activity/{action}
Authorization: Bearer {access_token}
Content-Type: application/json

Scopes

One scope authorizes exactly one endpoint. Grant only what your backend calls.

A token that lacks the scope of the endpoint it calls is rejected with 403, not 401. The token is valid; it simply carries no authority for that action.

Two authentication modes

The legacy path continues to work and accepts the same request bodies. The two paths are independent: a bearer token is not accepted on the legacy host, and an API key is not accepted on the gateway.

Keep in mind for activity identity

The ActivityAttributes type named by activity_type must conform to InsiderLiveActivitiesAttributes and carry a property named exactly insiderLiveActivityId (type InsiderLiveActivityIdentifier, never nil), unique per activity. If it is renamed, empty, or reused, the SDK cannot match the activity and your API calls target nothing.