POST
/
apps
/
{app_id}
/
activities
/
activity
/
{activity_type}
Start Live Activity
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.