Update Live Activities

Overview

The Update Broadcast Live Activities API allows brands to push a single, unified update to all subscribed Live Activities, such as an updated game score or a new development in a breaking news story. Furthermore, the API provides the functionality to send an alert with the content update to draw immediate user attention. For more info on broadcast live activities, refer here.

info	Note You can update live activities for campaigns created using the Start Live Activities API.

API Endpoint

Method: POST

https://api-0X.moengage.com/v1.0/live-activity/broadcast/update

The 'X' 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 (value of X) and replace the value of 'X' in the URL by referring to the DC and API endpoint mapping here.

Authentication

The API request will be authenticated through Basic Authentication. Basic Authentication sends a Base64-encoded string containing your username and password with every API request. It encodes a 'username: password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the authorization header as shown below:

{"Authorization":"Basic Base64_ENCODED_APPKEY_APIKEY=="}

You can obtain the username and password details from the MoEngage UI.

On the left navigation menu in the MoEngage UI, go to Settings > Account > APIs.
Copy the following details:
- Username: Under Workspace ID (earlier app id), click the copy icon to copy the username.
- Password: In the API keys section, click the copy icon in the Push tile to copy the API key.
Use these details to authenticate the API requests.

Request Headers

Key	Required	Sample Values	Description
Content-Type	Required	{"Content-Type": "application/json"}	Set the Content-Type header to application/json.
AUTHORIZATION	Required	{"Authorization":"Basic Base64_ENCODED_APPKEY_APIKEY=="}	This authentication parameter, used for access control, must be passed in the request. For more information on generating the authentication header, refer to Authentication.
X-MOE-APPKEY	Required	{“X-MOE-APPKEY”: “Workspace ID”}	This is the workspace ID (earlier APP ID) of your MoEngage workspace. The X-MOE-APPKEY must be passed in the request. You can find your MoEngage Workspace ID in the MoEngage UI: Settings > Account > APIs -> Workspace ID (earlier app id) For more information, refer to Authentication.
X-Broadcast-Live-Activity-Id	Required	{"X-Broadcast-Live-Activity-Id":"Broadcast Live Activity ID"}	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 with the `BROADCAST_LIVE_ACTIVITY` delivery type.

Request Body

Key

Required

Sample Values

Description

broadcast_live_activity_id

Required

String

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 with the `BROADCAST_LIVE_ACTIVITY` delivery type.

instance_id

Optional

String

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. Sample value:

"1749822841120-57c5c617"

ios

Required

JSON Object

This field denotes a JSON object containing iOS-specific content, configuration details, and metadata necessary for managing the Live Activity on iOS devices. For more information, refer to iOS.

iOS

Key	Required	Values	Description
dismissal_date	Optional	Int	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. Note: If the specified time stamp is in the past, the live activity ends immediately.
stale_date	Optional	Int	This field denotes the time at which the Live Activity’s content is considered outdated. The value must be specified as an epoch timestamp (in seconds). After this time, the system may choose to deprioritize or visually de-emphasize the Live Activity on the user’s device, but it will not dismiss it.
content_state	Required	JSON Object	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	Required	JSON Object	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. For more information, refer to Alert.

Alert

Key	Required	Values	Description
title	Required	String	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	Optional	String	This field denotes the defined additional context or information for the alert.
body	Required	String/JSON Object	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	Optional	String	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.

Response Body

Status

Key

Data Type

Description

success

instance_id

String

This field denotes the instance ID.

message

String

This field denotes the success message.

Failure

error

JSON Object

This field contains error details.

Key	Data Type	Description
code	String	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	String	This field contains the message that denotes the type of error.
details	JSON Object	This object contains the error details. For more info, refer Details. This field is applicable only for 400 error responses.

Details

Key	Data Type	Description
code	String	This field denotes a computer-readable identifier of the error type.
target	String	This field denotes the specific key parameter that triggered the validation error.
message	String	This field denotes a human-readable explanation of the error.

Refer to the Sample Response section for examples.

Response Codes

Status Code	Request State	Description
200	Success	This response is returned when the request is processed successfully.
400	Bad Request	This response is returned when the required parameters are missing from the request, attributes are not found, or incorrect values are passed.
401	Unauthorized	This response is returned when the request does not have valid authentication credentials.
403	Forbidden	This response is returned when the Live Activities feature is not enabled for the workspace.
429	Too Many Requests	Too Many requests, there won't be any response body for this.
500	Internal Server Error	This response is returned when the system runs into an unexpected error.

Rate Limit

You can create:

500 requests per minute per workspace.
5 requests per minute per live activity ID.

Sample cURL Request

curl --location curl --location https://api-0X.moengage.com/v1.0/live-activity/broadcast/update' \
--header 'X-MOE-APPKEY: {{Workspace_ID or APP_ID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{Authorization_Key}}' \
--header 'X-Broadcast-Live-Activity-Id: {{Broadcast_Live_Activity_ID}}'\
--data '{
    "broadcast_live_activity_id": "2",
     "instance_id": "instance_id112w1",
    "ios": {
        "dismissal_date": 1703505600,
        "stale_date": 1695760785,
        "content_state": {
            "emoji": "ffdfssdffdfsdfsThank you, Indian beat England by 50 runs"
             },
        "alert": {
            "title": "India won!",
            "subtitle": "India vs. England!!",
            "body": "India Score is 300/4, 20.3",
            "sound": "default"
        }
    }
}'

Sample Response

{
		    "data": {
		        "instance_id": {{instance_id}},
		        "message": "success"
		    }
}

Response Code Structure

{
		    "data": {
		        "instance_id": {{instance_id}},
		        "message": "success"
}

{
	    "error": {
	        "code": "PayloadError",
	        "message": "Mandatory fields are missing or invalid",
	        "details": [
	            {
	                "code": "extra_forbidden",
	                "target": "ios.alert.metrics",
	                "message": "Extra inputs are not permitted"
	            }
	        ]
	    }
}

{
    "error": {
        "code": "AuthError",
        "message": "Invalid App Key",
    }
}
--------------------------------------------------------------------------------

{
    "error": {
        "code": "AuthError",
        "message": "Invalid Data Key",
    }
}
-------------------------------------------------------------------------------
{
    "error": {
        "code": "AuthError",
        "message": "Authorization header or X-MOE-APPKEY is missing",
    }
}

{
    "error": {
        "code": "OperationNotAllowed",
        "message": "Campaign not found for <broadcast live activity id>",
    }
}
--------------------------------------------------------------------------------
{
    "error": {
        "code": "OperationNotAllowed",
        "message": "Only IOS token auth is allowed, please upload .p8 file",
    }
}
-------------------------------------------------------------------------------
{
    "error": {
        "code": "OperationNotAllowed",
        "message": "Invalid Action",
    }
}
--------------------------------------------------------------------------------
{
    "error": {
        "code": "OperationNotAllowed",
        "message": "Duplicate Request, please use different instance_id",
    }
}
--------------------------------------------------------------------------------
{
    "error": {
        "code": "OperationNotAllowed",
        "message": "Dismissal date is already passed",
    }
}
--------------------------------------------------------------------------------
{
    "error": {
        "code": "OperationNotAllowed",
        "message": "Max Instances Limit Reached",
    }
}

{
    "error": {
        "code": "PayloadSizeError",
        "message": "Payload size exceeded for IOS. Max size is 5120 bytes",
    }
}

[]

{
    "error": {
        "code": "ServerError",
        "message": "Internal Server Error, something went wrong",
    }
}

Postman Collection

We have made it easy for you to test the APIs. Click here to view it in Postman.