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

20

Create & send live notifications

Learn how to create notification types and manage activities for live notifications.

Everything on this page applies to both iOS and Android, except where noted.

Creating notification types

Every live notification belongs to a notification type. Each type has an identifier that uses reverse-DNS notation, like io.customer.order-tracking, to ensure the id is unique. Identifiers are great for code but hard to scan in a list, so you can also assign a friendly name that appears in your activity logs.

We log new identifiers automatically the first time you send a new live notification type. You can find them in > Workspace settings > Live notifications.

Start an activity

You can start an activity in two ways:

• App-initiated. Your app starts the activity on the device—for example, the moment a customer places an order. This works while your app is in the foreground.
• Push-to-start (server-driven). Your server asks Customer.io to start an activity. Customer.io delivers a push to the device’s push-to-start token, and the OS creates the activity. Your app doesn’t need to be open. You use the start endpoint to start these activities.

The SDK detects the new activity, registers its instance token with Customer.io, and begins reporting lifecycle events. From here, Customer.io can push updates to the activity.

Keep in mind, for iOS you have to capture ActivityKit’s push-to-start token and each activity’s instance token from the SDK and forward them for a successful delivery; for Android you only need the device’s normal FCM registration token, which you likely already have for regular push. Learn more about token registration.

Update a running activity

Once an activity is running, your server sends updates through the update endpoint, referencing the activity by its instance ID. Customer.io looks up the activity’s token and pushes the new content state to the device. The OS re-renders the activity without launching your app.

Each update must contain the full content state; you can’t send partial updates with only the information that’s changed.

Your app can also update an activity locally. When it does, the SDK reports the new state to Customer.io so the activity’s history stays complete.

End an activity

There are three ways to end an activity:

• Your server sends an end request to Customer.io, which delivers a final push that transitions the activity to its ended state and removes it from the Lock Screen or notification shade.
• Your app ends the activity locally, and the SDK reports the end to Customer.io.
• Automatic expiration: Customer.io ends an activity 6 hours after it starts by default. You can set an earlier expiration with the expiration field on the start request, but 6 hours is the maximum.

On iOS, you can set a dismissal time that keeps the final state visible on the Lock Screen for a short while before the system removes it. This might help if you want to make sure someone has time to see a final score or that their order was delivered.

Review & report on activities

Live notifications are a delivery channel in Customer.io. Every start, update, and end operation is a separate delivery, so a single activity produces a timeline of deliveries over its lifespan. Each delivery moves through the standard statuses—queued, sent, attempted, failed, or undeliverable.

You can see every live notification sent to a person—and drill into each instance’s full delivery timeline—on the person’s profile. See Monitor live notifications for more.