> ## Documentation Index
> Fetch the complete documentation index at: https://moengage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Start Broadcast Live Activity
> This API initiates a shared, real-time activity for a large audience, such as a live sporting match or real-time election result tracking.
You can start live activities for only push campaigns created with the BROADCAST\_LIVE\_ACTIVITY delivery type using the [Create Push Campaigns API](https://www.moengage.com/docs/api/create-campaigns/create-campaign), not campaigns created through the MoEngage UI.
#### Rate Limit
The rate limit for this endpoint is 5 requests per minute per workspace.
## OpenAPI
````yaml /api/live-activities/live-activities.yaml post /live-activity/broadcast/start
openapi: 3.0.3
info:
title: MoEngage Broadcast Live Activities API
version: '1.0'
description: >-
API for starting, updating, and ending broadcast Live Activities for iOS
Push Campaigns. Live Activities must be created via the Create Push
Campaigns API with the `BROADCAST_LIVE_ACTIVITY` delivery type.
servers:
- url: https://api-{dc}.moengage.com/v1.0
description: Live Activities API Server
variables:
dc:
default: '01'
description: >-
The ‘dc’ in the API Endpoint URL refers to the MoEngage Data Center
(DC). MoEngage hosts each customer in a different DC. You can find
your DC number and replace the value of ‘dc’ in the URL by referring
to the DC and API endpoint mapping
[here](/api/introduction#data-centers). Your MoEngage Data Center (DC)
can be 01, 02, 03, 04, 05, 06, or 101.
security:
- basicAuth: []
moeAppKey: []
tags:
- name: Live Activities
description: Operations to manage broadcast Live Activities for iOS.
paths:
/live-activity/broadcast/start:
post:
tags:
- Live Activities
summary: Start Broadcast Live Activity
description: >
This API initiates a shared, real-time activity for a large audience,
such as a live sporting match or real-time election result tracking.
parameters:
- name: X-MOE-APPKEY
in: header
required: true
schema:
type: string
description: >
This is the Workspace ID of your MoEngage account that must be
passed with the request. You can find it in the MoEngage dashboard
at **Settings** > **Account** > **APIs** > **Workspace ID (earlier
app id)**.
example: YOUR_WORKSPACE_ID_XXXX
requestBody:
required: true
description: >
The configuration for starting the Live Activity, including the
initial content and alert message.
content:
application/json:
schema:
$ref: '#/components/schemas/StartLiveActivityRequest'
responses:
'200':
description: Success. The live activity instance was created.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Bad Request - Mandatory fields are missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseWithDetails'
example:
error:
code: PayloadError
message: Mandatory fields are missing or invalid
details:
- code: extra_forbidden
target: ios.alert.metrics
message: Extra inputs are not permitted
'401':
description: Unauthorized - Invalid credentials or missing headers.
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorResponse'
examples:
invalid-app-key:
summary: Invalid App Key
value:
error:
code: AuthError
message: Invalid App Key
invalid-data-key:
summary: Invalid Data Key
value:
error:
code: AuthError
message: Invalid Data Key
missing-headers:
summary: Missing Authorization Headers
value:
error:
code: AuthError
message: Authorization header or X-MOE-APPKEY is missing
'403':
description: >-
Forbidden - Operation not allowed due to logic or permission
constraints.
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorResponse'
examples:
campaign-not-found:
summary: Campaign Not Found
value:
error:
code: OperationNotAllowed
message: Campaign not found for
ios-token-required:
summary: iOS Token Required
value:
error:
code: OperationNotAllowed
message: Only IOS token auth is allowed, please upload .p8 file
duplicate-request:
summary: Duplicate Request
value:
error:
code: OperationNotAllowed
message: Duplicate Request, please use different instance_id
limit-reached:
summary: Max Instances Limit Reached
value:
error:
code: OperationNotAllowed
message: Max Instances Limit Reached
'413':
description: >-
Payload Too Large - The payload exceeds the limit (e.g., 5120 bytes
for iOS).
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorResponse'
example:
error:
code: PayloadSizeError
message: Payload size exceeded for IOS. Max size is 5120 bytes
'429':
description: Too Many Requests.
content:
application/json:
schema:
type: array
items: {}
example: []
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorResponse'
example:
error:
code: ServerError
message: Internal Server Error, something went wrong
components:
schemas:
StartLiveActivityRequest:
type: object
required:
- broadcast_live_activity_id
- ios
properties:
broadcast_live_activity_id:
type: string
description: >-
This field denotes the unique identifier for the broadcast Live
Activity campaign. It links the broadcast request to a specific
campaign previously created via the [Create Push Campaigns
API](/api/create-campaigns/create-campaign) with the
`BROADCAST_LIVE_ACTIVITY` delivery type.
instance_id:
type: string
description: >-
This field denotes a unique, optional identifier for a specific
instance of the Live Activity. It can be used to differentiate
between multiple broadcasts of the same activity or to avoid
duplicate requests. For example, '1749822841120-57c5c617'.
ios:
$ref: '#/components/schemas/IOSStartPayload'
description: >-
This field denotes a JSON object containing iOS-specific content,
configuration details, and metadata necessary for managing the Live
Activity on iOS devices.
SuccessResponse:
type: object
properties:
data:
type: object
properties:
instance_id:
type: string
example: 1749822841120-57c5c617
description: This field denotes the instance ID.
message:
type: string
example: success
description: This field denotes the success message.
ErrorResponseWithDetails:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: PayloadError
description: >-
Each error code is unique and serves as a shorthand
representation for the type of error, providing a quick
reference that can be used to diagnose, troubleshoot, and
address the problem based on a predefined set of error
conditions.
message:
type: string
example: Mandatory fields are missing or invalid
description: This field contains the message that denotes the type of error.
details:
type: array
description: >-
This object contains the error details. This field is applicable
only for 400 error responses.
items:
$ref: '#/components/schemas/ErrorDetail'
BasicErrorResponse:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: AuthError
description: >-
Each error code is unique and serves as a shorthand
representation for the type of error, providing a quick
reference that can be used to diagnose, troubleshoot, and
address the problem based on a predefined set of error
conditions.
message:
type: string
example: Invalid App Key
description: This field contains the message that denotes the type of error.
IOSStartPayload:
type: object
required:
- attribute_type
- attribute_info
- content_state
- alert
properties:
dismissal_date:
type: integer
format: int64
description: >-
This field denotes the epoch timestamp (in seconds) at which the
Live Activity should be automatically dismissed from the device. If
omitted, the activity will persist until dismissed manually or
replaced.
attribute_type:
type: string
description: >-
This field denotes the attribute type defined in your iOS
application’s Live Activity schema. It represents the data model or
struct registered in your app that dictates the format of the Live
Activity’s attributes. This value must exactly match the class or
struct name used in the app to ensure compatibility.
example: LiveActivityAttributes
attribute_info:
type: object
additionalProperties: true
description: >-
This field denotes a JSON object containing the values for the
attributes declared in the `attribute_type`. It defines the static
or contextual information to be displayed when the Live Activity
starts, for example, match name, participants, or scorecard details.
content_state:
type: object
additionalProperties: true
description: >-
This field denotes a JSON object representing the dynamic, real-time
state of the Live Activity. It contains the content that will update
in real time on the user’s device, such as live scores, countdowns,
or player stats. The keys and structure must correspond to the
content state struct in your app’s Live Activity configuration.
alert:
$ref: '#/components/schemas/AlertObject'
description: >-
This field denotes a JSON object containing the textual content for
the Live Activity’s push notification alert. This controls the
user-facing message elements such as the title, subtitle, and body
displayed when the activity is triggered.
ErrorDetail:
type: object
properties:
code:
type: string
example: extra_forbidden
description: This field denotes a computer-readable identifier of the error type.
target:
type: string
example: ios.alert.metrics
description: >-
This field denotes the specific key parameter that triggered the
validation error.
message:
type: string
example: Extra inputs are not permitted
description: This field denotes a human-readable explanation of the error.
AlertObject:
type: object
required:
- title
- body
properties:
title:
type: string
description: >-
This field denotes the primary heading of the Live Activity alert
shown on the device. It captures the user’s attention and conveys
the core event or message.
subtitle:
type: string
description: >-
This field denotes the defined additional context or information for
the alert.
body:
oneOf:
- type: string
- type: object
description: >-
This field denotes the main message content of the alert. The value
can be a string or JSON object depending on the widget UI
configuration in your iOS app.
sound:
type: string
description: >-
This field denotes the name of the sound file in your app's main
bundle or in the Library/Sounds folder of your app's container
directory. Specify the string as 'default' to play the system sound.
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >
Authentication is done via Basic Auth. This requires a base64-encoded
string of your credentials in the format 'username:password'.
- **Username**: Use your MoEngage workspace ID (also known as the App
ID). You can find it in the MoEngage dashboard at **Settings** >
**Account** > **APIs** > **Workspace ID (earlier app id)**.
- **Password**: Use your API Key, which you can find within the **Push**
tile.
For more information on authentication and getting your credentials,
refer
[here](https://www.moengage.com/docs/api/introduction#getting-your-credentials).
````