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.
tags:
  - name: Live Activities
    description: Operations to manage broadcast Live Activities for iOS.
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: []

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:
  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).

  schemas:
    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."

    # For 400 Bad Request - Includes details array
    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'

    # For 401, 403, 413, 500 - Does NOT include details array
    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."
    
    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."

    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."
    
    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."

    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."

    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."
           
    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."