MoEngage Live Activities API

openapi: 3.2.0
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.

        '
      x-mint:
        content: '<Note>

          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.

          </Note>

          #### Rate Limit

          The rate limit for this endpoint is 5 requests per minute per workspace.

          '
      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 <broadcast live activity id>
                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
  /live-activity/broadcast/update:
    post:
      tags:
      - Live Activities
      summary: Update Broadcast Live Activity
      description: 'This API pushes a single, unified update to all subscribed Live Activities, such as an updated game score or a new development in a breaking news story.

        '
      x-mint:
        content: '#### Rate Limit

          The rate limit for this endpoint is 500 requests per minute per workspace and 5 requests per minute per live activity ID.

          '
      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 payload containing the updated content state and optional alert for the Live Activity.

          '
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLiveActivityRequest'
      responses:
        '200':
          description: Success. The live activity was updated.
          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 <broadcast live activity id>
                ios-token-required:
                  summary: iOS Token Required
                  value:
                    error:
                      code: OperationNotAllowed
                      message: Only IOS token auth is allowed, please upload .p8 file
                invalid-action:
                  summary: Invalid Action
                  value:
                    error:
                      code: OperationNotAllowed
                      message: Invalid Action
                duplicate-request:
                  summary: Duplicate Request
                  value:
                    error:
                      code: OperationNotAllowed
                      message: Duplicate Request, please use different instance_id
                dismissal-passed:
                  summary: Dismissal Date Passed
                  value:
                    error:
                      code: OperationNotAllowed
                      message: Dismissal date is already passed
                limit-reached:
                  summary: Max Instances Limit Reached
                  value:
                    error:
                      code: OperationNotAllowed
                      message: Max Instances Limit Reached
        '413':
          description: Payload Too Large.
          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
  /live-activity/broadcast/end:
    post:
      tags:
      - Live Activities
      summary: End Broadcast Live Activity
      description: 'This API terminates a broadcast Live Activity across all subscribed devices simultaneously, with options for a final state update or immediate dismissal.

        '
      x-mint:
        content: '#### Rate Limit

          The rate limit for this endpoint is 500 requests per minute per workspace and 5 requests per minute per live activity ID.

          '
      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 payload containing the final content state and dismissal information for the Live Activity.

          '
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndLiveActivityRequest'
      responses:
        '200':
          description: Success. The live activity was ended.
          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 <broadcast live activity id>
                ios-token-required:
                  summary: iOS Token Required
                  value:
                    error:
                      code: OperationNotAllowed
                      message: Only IOS token auth is allowed, please upload .p8 file
                invalid-action:
                  summary: Invalid Action
                  value:
                    error:
                      code: OperationNotAllowed
                      message: Invalid Action
                duplicate-request:
                  summary: Duplicate Request
                  value:
                    error:
                      code: OperationNotAllowed
                      message: Duplicate Request, please use different instance_id
                dismissal-passed:
                  summary: Dismissal Date Passed
                  value:
                    error:
                      code: OperationNotAllowed
                      message: Dismissal date is already passed
                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:
    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.
    IOSUpdatePayload:
      type: object
      required:
      - 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.


            **Note:** If the specified time stamp is in the past, the live activity ends immediately.

            '
        stale_date:
          type: integer
          format: int64
          description: 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:
          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.
    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.
    EndLiveActivityRequest:
      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. Sample value:1749822841120-57c5c617. Optional unique identifier for this specific broadcast instance.
        ios:
          $ref: '#/components/schemas/IOSUpdatePayload'
          description: This field denotes a JSON object containing iOS-specific content, configuration details, and metadata necessary for managing the Live Activity on iOS devices.
    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.
    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'
    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.
    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.
    UpdateLiveActivityRequest:
      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. Sample value:1749822841120-57c5c617.
        ios:
          $ref: '#/components/schemas/IOSUpdatePayload'
          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.
  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).

        '