This page is part of the Customer.io documentation. For the complete documentation index, see llms.txt.

40

Live notification payload reference

When you start or update 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:

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 io.customer.liveactivities.countdowntimer.

{
    "attributes": {
        "header": "Summer Sale"
    },
    "content_state": {
        "title": "Flash sale ends in",
        "statusMessage": "30% off everything",
        "endTime": 1753603600
    }
}

Attributes

Content state

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 io.customer.liveactivities.segments.

{
    "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

Content state

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:

{
    "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.

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:

{
    "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.