POST
/
apps
/
{app_id}
/
activities
/
activity
/
{activity_type}
curl --request POST \
  --url https://api.onesignal.com/apps/{app_id}/activities/activity/{activity_type} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '{
  "include_aliases": {
    "external_id": [
      "<string>"
    ],
    "onesignal_id": [
      "<string>"
    ]
  },
  "include_subscription_ids": [
    "<string>"
  ],
  "included_segments": [
    "<string>"
  ],
  "excluded_segments": [
    "<string>"
  ],
  "filters": [
    {
      "field": "first_session",
      "key": "<string>",
      "relation": ">",
      "value": "1"
    }
  ],
  "event": "start",
  "activity_id": "<string>",
  "event_attributes": {},
  "event_updates": {},
  "name": "<string>",
  "contents": {
    "en": "<string>"
  },
  "headings": {
    "en": "<string>"
  },
  "stale_date": 123,
  "priority": 5,
  "ios_relevance_score": 123,
  "idempotency_key": "<string>"
}'
{
  "notification_id": "<string>"
}

Overview

Remotely start an iOS Live Activity using OneSignal’s REST API. Live Activities provide real-time updates directly on the lock screen and Dynamic Island (on supported devices), enhancing user engagement with ongoing events like sports games, deliveries, or countdowns.


How to use this API

  1. Define a Live Activity in your app. See Live Activities developer setup to get started.
  2. Use the activity_type parameter to specify the type of the Live Activity UI to use.
  3. Select your target audience to receive the Live Activity. Target all or individual users.
  4. Generate a unique activity_id to track and manage your Live Activity.
  5. Use the event_attributes parameter to initialize the Live Activity with static data.
  6. Use the event_updates parameter to update the Live Activity with dynamic content.

Select your target audience

Before sending a message, you need to determine who should receive it. OneSignal offers three targeting options:

  1. Aliases & Subscription IDs: Send messages to specific users using unique identifiers such as External ID (recommended), OneSignal ID, custom alias, or subscription ID.
  2. Segments: Target predefined user groups based on attributes and behavior.
  3. Filters: Create custom targeting rules using user properties, such as tags, location, or activity.

You can only use one targeting method per message. For example, you cannot combine alias-based targeting with filters in the same request.

See Select your target audience for more information.

Set a unique activity_id

  • Set a unique activity_id to track and manage the Live Activity. This value is crucial for maintaining a consistent reference to the Live Activity across different devices and sessions. Consider using a UUID, CUID, or NanoID for this parameter.

  • Ensure that the activity_id is unique and consistently used for each Live Activity to avoid conflicts and ensure accurate tracking.

    Example
    {
      "activity_id": "217aae2b-42ee-4097-bc3f-b7a6e9d15b9b",
      ...
    }
    

See Live Activities developer setup guide for more information.

Set event_attributes to initialize the Live Activity

Set default/static data to display in the Live Activity upon start.

Example
{
  "event_attributes": {
  	"awayTeam": "Away Team Name",
    "homeTeam": "Home Team Name"
  }
}

Set event_updates for dynamic content

The content used to update a running Live Activity. The object must conform to the ContentState interface defined within your app’s Live Activity. See Live Activities developer setup.

Ensure that the event_updates object matches the ContentState interface exactly as defined in your Live Activity implementation. Inconsistencies can cause Live Activities to fail to display.

Example
{
  "event_updates": {
    "quarter": 1,
    "homeScore": 70,
    "awayScore": 78,
    "inTimeout": false
  }
}

Headers

Authorization
string
default:Key YOUR_APP_API_KEY
required

Your App API key with prefix Key. See Keys & IDs.

Path Parameters

app_id
string
required

Your OneSignal App ID in UUID v4 format. See Keys & IDs.

activity_type
string
required

The name of the Live Activity defined in your app. This should match the your-nameAttributes struct used in your app code. See Live Activities developer setup. Example: If your app defines a Live Activity as OneSignalWidgetAttributes, then activity_type should be OneSignalWidgetAttributes.

Body

application/json

Response

201
application/json

201

The response is of type object.