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.

Body
application/json
  • attributes
    required

    Static fields set once at start. They can't change after you start the activity. The attributes' shape depends on your notification_type. For iOS or a free form Android activity, pick the free form variant. For other Android notification types, pick the matching variant below. See the payload reference for details.

    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 shape depends on your notification_type—pick the matching 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.