> This page is part of the [Customer.io documentation](https://docs.customer.io). For the complete index, see [llms.txt](https://docs.customer.io/llms.txt). > Last updated: July 30, 2026 # Live notification payload reference [PremiumThis feature is available for Premium plans.](/accounts/billing/plan-features/) [EnterpriseThis feature is available for Enterprise plans.](/accounts/billing/plan-features/) When you [start](/integrations/api/app/#tag/live-notifications/startLiveNotification) or [update](/integrations/api/app/#tag/live-notifications/updateLiveNotification) a live notification through the API, you send two objects: `attributes` and `content_state`. Customer.io wraps them in the right platform payload and delivers them to the device. This page documents both layers: what you send and what arrives. ## Attributes and content state Every live notification splits its data into two parts, mirroring Apple’s ActivityKit model on both platforms: Object Set Contains `attributes` On start and every update Static fields that never change for the life of the activity. These are things like an order number, a flight’s origin and destination, or the teams in a match. `content_state` On start and every update Dynamic fields that change as the activity progresses. These are things like the current status, score, or ETA. Two conventions apply everywhere: * **Dates and timestamps are epoch seconds**, not milliseconds. Use the Unix format. * **Each update carries the full content state.** The device re-renders from the complete state on every push. There are no partial updates. ## Built-in templates You can use these built-in templates to send live notifications to both iOS and Android platforms. Or you can use them as starting points for your own custom templates. You send static fields in `attributes` and dynamic fields in `content_state`; each template below shows a complete example, followed by the schema for both objects. * Fields the templates render verbatim (`header`, `title`, `subtitle`, `status`) are freeform text. `statusColor` is a hex string like `#36AE3F`. * Image fields (`image`, `logo`) accept a bundled drawable name, a registered asset key, or an `https` URL. * `staleMessage` displays when an activity goes stale without an update. ### Countdown timer Use this template to create a countdown timer. You call this template with the [notification type identifier](/messaging/channels/live-notifications/how-it-works/#create-your-notification-types) `io.customer.liveactivities.countdowntimer`. ```json { "attributes": { "header": "Summer Sale" }, "content_state": { "title": "Flash sale ends in", "statusMessage": "30% off everything", "endTime": 1753603600 } } ``` #### Attributes * header string Required Top-row label of the notification. #### Content state * endTime integer Countdown target, in whole seconds since 1970 UTC. A time in the future renders a live countdown; omit it to render no timer. The countdown does not clear itself when it reaches zero — it rests at "0:00" until you send an update with a finished title and no endTime. * statusMessage string Secondary line under the title. * title string Required Primary status line. ### Multi-step tracker Use this template to create a delivery process tracker or any tracker with steps. You call this template with the [notification type identifier](/messaging/channels/live-notifications/how-it-works/#create-your-notification-types) `io.customer.liveactivities.segments`. ```json { "attributes": { "header": "Chica's Tacos" }, "content_state": { "status": "Preparing your order", "substatus": "We'll let you know when it's on the way", "segmentsTotal": 4, "segmentsComplete": 2, "trailingText": "25 min" } } ``` #### Attributes * header string Required Top-row label #### Content state * segmentsComplete integer Required How many segments are filled; the remainder render as incomplete. Values above segmentsTotal are capped at segmentsTotal. * segmentsTotal integer Required The total number of steps. Total number of segments in the progress bar. Values above 20 are capped at 20. Accepted values:`1..20` * status string Required Primary status line, like `Out for delivery`. * substatus string Secondary line under the status. * trailingText string Short text on the Dynamic Island trailing edge, e.g. "5 min". Keep it brief; the trailing region is narrow. ## What Customer.io sends to iOS (APNs) Customer.io delivers iOS live notifications as APNs pushes with the `liveactivity` push type at top priority. A start event looks like this: ```json { "aps": { "timestamp": 1721000000, "event": "start", "attributes-type": "DeliveryActivityAttributes", "attributes": { "orderNumber": "CIO-1234", "cioInstanceId": "01J4YQZC3GJ0S6RY4E5NW6H9AB" }, "content-state": { "title": "Order received", "progress": { "current": 1, "total": 4 }, "cioMetadata": { "deliveryId": "RPILAgUBcRhIBqSfeiIwdIYYKxTuwqSjjqQ=", "deliveryToken": "AbCdEfg...", "deepLink": "yourapp://orders/1234" } }, "alert": { "title": "Your order is on its way", "body": "Track it live on your Lock Screen" } } } ``` * `event` is `start`, `update`, or `end`. * `attributes-type` and `attributes` appear only on start events—attributes are immutable after the activity is created. Customer.io injects `cioInstanceId` so the SDK can correlate the activity. * `content-state` is your content state plus an injected `cioMetadata` object carrying the delivery ID, delivery token, and deep link. Declare `cioMetadata` on your `ContentState` type (the SDK’s `CIOMetadataCarrying` protocol) to get tap-through deep links and delivery attribution. * `alert` comes from the `push_payload.alert` you pass to the API. It normally appears only on start events. If your iOS app delivers push through Firebase (FCM), you must also include `push_payload.alert` on update and end calls, so it appears on those events too.  iOS apps that deliver push through Firebase If your iOS app delivers push through Firebase instead of directly through APNs, Customer.io nests this same APNs payload inside the FCM envelope—the content is identical. Firebase also requires an alert on every message, so you must include a `push_payload.alert` (with a title and body) on your update and end API calls as well as start—otherwise FCM rejects the delivery. ## What Customer.io sends to Android (FCM) Android live notifications arrive as FCM **data messages**—there’s no `notification` block, so the SDK renders them even when your app is in the background: ```json { "data": { "cioInstanceId": "01J4YQZC3GJ0S6RY4E5NW6H9AB", "event": "update", "notification_type": "io.customer.liveactivities.deliverytracking", "timestamp": 1721000000, "link": "yourapp://orders/1234", "payload": "{\"title\":\"Out for delivery\",\"progress\":{\"current\":3,\"total\":4}}" } } ``` * `cioInstanceId` identifies the activity; updates with the same ID replace the notification in place. * `notification_type` selects the template (or your custom renderer). * `payload` is a JSON string of your merged `attributes` and `content_state`. * * [Attributes and content state](#attributes-and-content-state) * [Built-in templates](#built-in-templates) * [Countdown timer](#countdown-timer) * [Attributes](#countdown-timer-attributes) * [Content state](#countdown-timer-content-state) * [Multi-step tracker](#multi-step-tracker) * [Attributes](#countdown-timer-attributes) * [Content state](#countdown-timer-content-state) * [What Customer.io sends to iOS (APNs)](#what-customerio-sends-to-ios-apns) * [What Customer.io sends to Android (FCM)](#what-customerio-sends-to-android-fcm) Copy page Copy page [Download .md](/messaging/channels/live-notifications/payload-reference.md) Is this page helpful? ![](https://docs.customer.io/images/export-success.png) ![](https://docs.customer.io/images/export-failure.png) # How can we make it better? Close Do you need help from Customer.io support? No Yes What part of Customer.io do you need help with? How can we improve this page? Email (optional): Please provide a valid email address I am not a bot We appreciate your feedback! Our support team will contact you as soon as possible