Starts a Live Activity and delivers it to the specified audience via push notification.
Audience targeting (exactly one required):
contactKeys— specific contacts by their contact keydeviceIds— specific devices by their device IDsegmentGuid— a segment GUID
Note on segment targeting: When using
segmentGuid, the audience is resolved asynchronously in the push layer. Processing may be slower thandeviceIdsorcontactKeystargeting, especially for large segments.
App filtering (appGuids):
Required. Only devices from the listed apps are targeted. Devices from unlisted apps are excluded at query time and do not appear in the Live Activity Report. Maximum 10 items.
Delivery behavior:
Some conditions cannot be validated at the REST layer because they depend on per-device state resolved during push processing (e.g. whether a contact has registered a device, whether the device has a valid push-to-start token). For these cases the request returns 200 OK and the per-device result is reported as Delivered or Error in the Live Activity Report.
activityId rules:
- Optional. If omitted, the system generates one and returns it in the response.
- Max 100 characters.
- Once used, an
activityIdis blocked for 13 hours. No further start requests with the sameactivityIdare accepted during this period.
REST-layer validations — HTTP 400, internal code 11:
| Field | Rule | Error message |
|---|---|---|
activityType | Required | ActivityType is required |
activityType | Max 100 characters | ActivityType cannot exceed 100 characters |
activityId | Max 100 characters | ActivityId cannot exceed 100 characters |
activityId | Already used — blocked for 13 hours | ActivityId '{activityId}' has already been used. It cannot be reused until the activity is completed. |
activityId | Ended and scheduled to expire | ActivityId '{activityId}' has been ended and is scheduled to close on {endDateUtc} (UTC). No further operations are allowed until it expires. |
activityId | Concurrent lock held — retryable | Another operation is currently in progress for ActivityId '{id}'. Please try again shortly. |
appGuids | Required | AppGuids is required |
appGuids | All provided GUIDs must exist and be active | Some apps not found or inactive: {guids} |
appGuids | All apps must be iOS or Android type | Live activities are only supported for iOS and Android apps |
appGuids | Max 10 items | The length of the AppGuid list must be less than or equal to 10. |
| Targeting | At least one of segmentGuid, deviceIds, contactKeys must be provided | One of SegmentId, DeviceIds, or ContactKeys must be provided |
| Targeting | Only one of segmentGuid, deviceIds, contactKeys can be provided | Only one of SegmentId, DeviceIds, or ContactKeys can be provided |
deviceIds | Max 5000 items | The length of the DeviceId list must be less than or equal to 5000. |
contactKeys | Max 5000 items | The length of the ContactKey list must be less than or equal to 5000. |
onlyLastUsedDevice | Cannot be true when deviceIds is provided | OnlyLastUsedDevice cannot be true when DeviceIds is provided |
iosPayload / androidPayload | At least one must be provided | At least one of IOSPayload or AndroidPayload must be provided |
Push-layer validations — logged as ERROR in Send Logs (not HTTP errors):
| Condition | Error message in Send Logs |
|---|---|
| Contact key not found in device registry | No device found for ContactKey: {contactKey} |
| Device ID not found | Device not found |
| Device's platform is not iOS or Android | Unsupported AppType: {appType} |
| iOS device has no push-to-start token | No valid push-to-start token found for this device. |
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||