> This page is part of the [Customer.io documentation](https://docs-customerio.netlify.app). For the complete index, see [llms.txt](https://docs-customerio.netlify.app/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 Send Contains `attributes` On start Static fields used to create the activity. They don’t change after start. These are things like an order number, a flight’s origin and destination, or the teams in a match. `content_state` Required on start. For Android, include them again on update or end when the renderer needs those static fields; iOS uses them only at start. The complete dynamic state the device should render—the current status, score, or ETA. Updates replace the previous state rather than patching it. 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`, `status`, `substatus`) are freeform text. The supported fields are the ones in each template’s schema below—the bundled templates don’t expose generic status-color, image, or logo fields. ### 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/#creating-notification-types) `io.customer.livenotifications.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.livenotifications.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 segments in the progress bar. Values above 20 are capped at 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. An iOS start requires `push_payload.alert`. Updates and ends can be silent, whether Customer.io delivers directly through APNs or relays through Firebase. If you include an alert on an update or end, provide both its `title` and `body`.  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. You still only need `push_payload.alert` on the start; updates and ends can be silent on either delivery path. ## 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.livenotifications.segments", "timestamp": "1721000000", "link": "yourapp://orders/1234", "payload": "{\"header\":\"Order\",\"status\":\"Out for delivery\",\"segmentsTotal\":4,\"segmentsComplete\":3}" } } ``` * `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