Sign in
Live Notifications

Start a live notification

Start a live notification for a profile. Customer.io mints an instance_id for the new activity and returns it. You'll use this ID to update, end, or check the status of the activity.

On iOS, this delivers a push-to-start event through APNs, so the person's device must have a registered push-to-start token for the notification_type (the SDK registers one automatically when your app registers the activity type). Push-to-start requires iOS 17.2 or later. iOS starts also require a push_payload.alert with a title and body.

On Android, this delivers an FCM data message, which the SDK renders without your app being open.

post/v1/live_notifications/start

Request body

notification_typestring required

The reverse-DNS identifier of the activity type, like io.customer.livenotifications.segments. Must match a type your app registered with the SDK.

device_idstring

The device token identifying the device to start the activity on.

platform'ios' | 'android'

The device platform.

app_identifierstring

The identifier of the app to start the activity on—a bundle ID on iOS or a package name on Android. This only matters when your workspace has multiple apps: set it to target a device belonging to that app, or omit it to target the workspace's default app. Workspaces without multiple apps ignore this field. If you provide a value that doesn't match an app in your workspace, the request fails with a 400.

deep_linkstring

A link to open when the person taps the activity.

expirationinteger

A unix timestamp (in seconds) for when the activity should expire. Must be no more than 6 hours in the future—values outside the range between now and that 6-hour maximum are rejected with a 400. If you omit it (or pass 0), the activity expires 6 hours after it starts.

Response

The activity was queued. Returns the instance ID for the new activity.

instance_idstring

The unique identifier (ULID) for the new activity instance. Use it to update, end, or check the status of the activity.

Changes

No recorded changes to this endpoint across all 1 revision of this API.