Customer.io
v1.0.0
OpenAPI 3.1.0

Start a live notification

US region

Client Libraries
Shell Curl

Start a live notification

​

Start a live notification for a profile. Customer.io mints an instance_id for the new activity and returns it. You'll use this ID to update, end, or check the status of the activity.

On iOS, this delivers a push-to-start event through APNs, so the person's device must have a registered push-to-start token for the notification_type (the SDK registers one automatically when your app registers the activity type). Push-to-start requires iOS 17.2 or later. iOS starts also require a push_payload.alert with a title and body.

On Android, this delivers an FCM data message, which the SDK renders without your app being open.

Body
application/json
  • attributes
    required

    Static fields used to create the activity—an order number, a flight's origin and destination, or the teams in a match. On iOS they can't change after start. On Android, include the static fields your renderer needs on update and end calls too, because the SDK renders from a merged payload. The shape depends on your notification_type: pick the free form variant for iOS or a free form Android activity, or the matching bundled-template variant below. Template fields are documented for iOS and Android.

    Your own static fields. On iOS, field names must match the ActivityAttributes type in your app. For Android custom types, fields pass through to your app's renderer as-is.

    • propertyName
      Type: anything
  • content_state
    required

    The initial dynamic content for the activity—the status, score, or ETA the device renders. Send the complete state on every call; partial updates aren't supported. The shape depends on your notification_type: pick the free form variant for iOS or a free form Android activity, or the matching bundled-template variant below. Date fields are epoch seconds.

    Your own dynamic fields. On iOS, field names must match your ContentState type. For Android custom types, fields pass through to your app's renderer as-is. Date fields are epoch seconds.

    • propertyName
      Type: anything
  • identifiers
    Type: object
    required

    Identifies the profile you want to start the activity for. You must provide exactly one of id, email, phone, or internal (our internal identifier, cio_ followed by an alphanumeric string). You cannot target anonymous profiles.

  • notification_type
    Type: string
    required

    The reverse-DNS identifier of the activity type, like io.customer.livenotifications.segments. Must match a type your app registered with the SDK.

  • app_identifier
    Type: string

    The identifier of the app to start the activity on—a bundle ID on iOS or a package name on Android. This only matters when your workspace has multiple apps: set it to target a device belonging to that app, or omit it to target the workspace's default app. Workspaces without multiple apps ignore this field. If you provide a value that doesn't match an app in your workspace, the request fails with a 400.

  • Type: string

    A link to open when the person taps the activity.

  • device_id
    Type: string

    The device token identifying the device to start the activity on.

  • expiration
    Type: integer

    A unix timestamp (in seconds) for when the activity should expire. Must be no more than 6 hours in the future—values outside the range between now and that 6-hour maximum are rejected with a 400. If you omit it (or pass 0), the activity expires 6 hours after it starts.

  • platform
    Type: stringenum

    The device platform.

    values
    • ios
    • android
  • push_payload
    Type: object

    The alert shown when the activity starts. Required for iOS.

Responses
  • application/json
  • 400

    The request was malformed—a missing required field, an invalid platform, more or fewer than one identifier, or a missing iOS alert.

  • 404

    Live notifications aren't enabled for this workspace.

Request Example for post/v1/live_notifications/start
curl https://api.customer.io/v1/live_notifications/start \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "identifiers": {
    "id": "",
    "email": "",
    "phone": "",
    "internal": ""
  },
  "notification_type": "",
  "device_id": "",
  "platform": "ios",
  "app_identifier": "",
  "attributes": {
    "additionalProperty": "anything"
  },
  "content_state": {
    "additionalProperty": "anything"
  },
  "push_payload": {
    "alert": {
      "title": "",
      "body": "",
      "sound": ""
    }
  },
  "deep_link": "",
  "expiration": 1
}'

{
  "instance_id": "string"
}

The activity was queued. Returns the instance ID for the new activity.