Manage devices

If you want to send push notifications, you can register your users devices with us. Our SDKs automatically associate device tokens with people when you identify a person, but you can also use our API to add devices.

You’ll find a person’s devices by going to the People page, selecting a person, and going to their Devices tab.

For each device, we show the device platform platform, token, and when the device was “last used”. Last used indicates the last time you identified a device—something you typically do when someone logs into your app, or opens your app and is already logged in!

The devices list
The devices list

You can hover over the truncated token to see the full string and copy it to your clipboard. This is especially useful when you need a device token for sending a test push notification from the composer.


And in the activity stream, you can click on each individual row for more details. Here’s an example with an initial API call to add a device:

Add and Delete devices

In general, we suggest that you integrate with our SDKs to add and delete devices. They can help you associate device tokens with people you identify and remove tokens when you stop identifying them.

Otherwise, you can integrate directly with our API to add and delete devices.

You can’t add devices in the UI, but you can delete as many as you like.

We automatically delete unregistered devices

Device tokens are ephemeral: they become invalid when a person logs out of your app, and a push service can change them at any time. Beginning January 31, 2023, when a device token becomes unregistered, it is invalid and will never become valid again; if a person logs into your app again, they’ll get a new device token.

To prevent invalid tokens from stacking up on people in your workspace, we automatically remove devices when they’re invalidated by your push services. If, when you send a push notification, your push service (FCM or APNs) responds with an unregistered message, we’ll automatically remove the token from your workspace.

flowchart LR a[send push]-->b{Is the push sent?} b-->|yes|c[display push] b-.->|no, device token
is unregistered|d[delete device] class d mermaid-error classDef mermaid-error fill: #ffedf0,color: #69002c, stroke:#69002c

Device attributes

Devices have their own attributesA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages. Attributes are analogous to traits in Data Pipelines.. We collect last_status automatically. We also set a last_used attribute based on either the timestamp in your request to add or update a device, or the time of the request itself. When you add or update a device using our SDKs, we’ll set the platform automatically for you; otherwise, you must send the platform with each request to our API.

If you use our SDKs, you’ll automatically collect additional device attributes by default. Whether or not you use our SDKs, you can also set custom attributes for each device—similar to attributes you set for people, but specific to each mobile device token.

When you go to a person’s Devices tab, you’ll see each device’s PLATFORM, DEVICE LAST USED and LAST RESULT attributes. Click a device to reveal additional information and attributes attached to it.

You can use device attributes anywhere you would otherwise use a person’s other attributes—True/False branches, Action Conditions, or segmentsA segment is a group of people in your audience that you want to target with campaigns, messages, etc. You can join groups of people manually, or by attribues and event data.. But you cannot use device attributes with Liquid today.

See device attributes on the devices tab of a person's page
See device attributes on the devices tab of a person's page

Custom device attributes

When you identify or update a device, you can pass an attributes object containing additional attributes specific to a device. If you use our SDKs, we capture a number of predefined attributes automatically—unless you disable automatic attribute collection.

You can segment and filter audience members based on these attributes. However, device tokens can change—sometimes based on user behavior, like when a person uninstalls and reinstalls your app, and sometimes based on your messaging service (FCM or APNs). When you set attributes on a device, consider wether you need to retain an attribute past the life of the device token, and if an attribute is truly relevant to the device.

The following attributes are automatically collected by alpha versions of the SDK, set automatically by, or available to our APIs. If you disable automatic attribute collection in the SDK, we’ll stop automatically collecting properties other than platform, last_used, and last_status.

  • id string
    Required The device token.
    • _last_status string
      The delivery status of the last message sent to the device—sent, bounced, or suppressed. An empty string indicates that that the device hasn’t received a push yet.

      Accepted values:,bounced,sent,suppressed

    • app_version string
      The version of your app that a customer uses. You might target app versions to let people know when they need to update, or expose them to new features when they do.
    • cio_sdk_version string
      The version of the SDK in the app.
    • device_locale string
      The four-letter IETF language code for the device. For example, en-MX (indicating an app in Spanish formatted for a user in Mexico) or es-ES (indicating an app in Spanish formatted for a user in Spain).
    • device_model string
      The model of the device a person uses.
    • device_os string
      The operating system, including the version, on the device.
    • push_enabled string
      If "true", the device is opted-in and can receive push notifications.

      Accepted values:true,false

    • Custom Device Attributes* string
      Custom properties that you want to associate with the device.
  • last_used integer  (unix timestamp)
    The timestamp when you last identified this device. If you don’t pass a timestamp when you add or update a device, we use the time of the request itself. Our SDKs identify a device when a person launches their app.
  • platform string
    Required The device/messaging platform.

    Accepted values:ios,android

Segment people based on their devices

When you create segments, you can segment people based on their device attributes—their platform, the status of their last message, or when devices were last_used.

Segment people by device platform
Segment people by device platform
Copied to clipboard!
Is this page helpful?