openapi: 3.0.3
info:
  title: MoEngage Inform API
  version: '1.0'
  description: |-
    API for MoEngage Inform, a unified messaging infrastructure for building and managing transactional alerts across multiple channels like SMS, Email, and Push.
tags:
  - name: Transactional Alerts
    description: Send transactional alerts using pre-configured templates.
servers:
  - url: 'https://api-{dc}.moengage.com/v1.0'
    description: Live Alerts Endpoint
    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.' 
  - url: 'https://sandbox-api-{dc}.moengage.com/v1.0'
    description: Test/Sandbox Alerts Endpoint
    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. '
paths:
  /alerts/send:
    post:
      tags:
        - Transactional Alerts
      summary: Send Transactional Alert
      description: "This API is used to trigger a transactional message/alert to the user via one or more configured channels."
      x-mint:
        content: |
          #### Rate Limit
          The default rate limit is 10K RPM.
      security:
        - basicAuth: []
          moeAppKey: []
      requestBody:
        required: true
        description: The payload containing the alert identifier, transaction details, and recipient information for each channel.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InformRequest'
            examples:
              singleChannelWithoutPersonalization:
                summary: Single Channel (SMS) without Personalization
                value:
                  alert_id: "636b77e6e2cf83277195fb60"
                  alert_reference_name: "Demo_ID"
                  user_id: "USER_12345"
                  transaction_id: "TXN_ABCDEF123"
                  payloads:
                    SMS:
                      recipient: "1234567890"
              multichannelWithoutPersonalization:
                summary: Multichannel Without Personalization
                value:
                  alert_id: "636b77e6e2cf83277195fb60"
                  alert_reference_name: "Demo_ID"
                  user_id: "USER_ID"
                  transaction_id: "YOUR_TRANSACTION_ID_VAL_HERE"
                  payloads:
                    PUSH:
                      recipient: "<push-token>"
                    EMAIL:
                      recipient: "john.doe@moengage.com"
              singleChannelWithPersonalization: 
                summary: Single Channel With Personalization (SMS)
                value:
                  alert_id: "636b77e6e2cf83277195fb60"
                  alert_reference_name: "Demo_ID"
                  user_id: "USER_ID"
                  transaction_id: "YOUR_TRANSACTION_ID_VAL_HERE"
                  payloads:
                    SMS:
                      recipient: "123456789"
                      personalized_attributes:
                        firstname: "YOUR_firstname_ATTRIBUTE_VAL_HERE"
                        orderid: "YOUR_orderid_ATTRIBUTE_VAL_HERE"
                        deliverydate: "YOUR_deliverydate_ATTRIBUTE_VAL_HERE"
                        deliveryslot_starttime: "YOUR_deliveryslot_starttime_ATTRIBUTE_VAL_HERE"
                        deliveryslot_endtime: "YOUR_deliveryslot_endtime_ATTRIBUTE_VAL_HERE"
              multiChannelWithPersonalization:
                summary: Multi-Channel with Personalization
                value:
                  alert_id: "636b77e6e2cf83277195fb60"
                  alert_reference_name: "Demo_ID"
                  user_id: "USER_12345"
                  transaction_id: "TXN_987654321"
                  payloads:
                    PUSH:
                      recipient: "<push-token>"
                      personalized_attributes:
                        firstname: "John"
                        orderid: "ORD_554433"
                    EMAIL:
                      recipient: "john.doe@moengage.com"
                      personalized_attributes:
                        firstname: "John"
                        orderid: "ORD_554433"
              liveActivity:
                summary: iOS Live Activity (PUSH)
                value:
                  alert_id: "696737255def18872642f9d2"
                  alert_reference_name: "Live Activity Only Test"
                  user_id: "USER_ID"
                  transaction_id: "YOUR_TRANSACTION_ID_VAL_HERE"
                  payloads:
                    PUSH:
                      recipient: "<push-token>"
                      personalized_attributes:
                        stale_date: "YOUR_stale_date_VAL_HERE"
                        dismissal_date: "YOUR_dismissal_date_VAL_HERE"
                      live_activity_attributes:
                        la_type: "start"
                        attribute_info:
                          order_id: "ORD_554433"
                        content_state:
                          delivery_status: "Out for delivery"
                          eta_minutes: 12
              
      responses:
        '200':
          description: | 
            Request has been received and processed. The response body contains the status for the overall request and for each individual channel.

            **Note**: Reach out to your Customer Success Manager to enable sending the channel level details as part of your API response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InformSuccessResponse'
        '400':
          description: Bad Request. Invalid payload format, incorrect JSON, or invalid Alert ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InformErrorResponse'
              example:
                message: "Invalid Alert ID"
                err_code: "BAD_REQUEST"
                status_code: 120002
        '401':
          description: Unauthorized. Invalid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InformErrorResponse'
              example:
                message: "Invalid App Key or Basic Auth"
                err_code: "UNAUTHORIZED"
                status_code: 120001
        '409':
          description: Duplicate Request. A request with the same `transaction_id` was received within 5 minutes of a previously successful or in-progress request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InformErrorResponse'
              example:
                message: "Duplicate Transaction ID"
                err_code: "DUPLICATE_REQUEST_RECEIVED"
                status_code: 120105
        '429':
          description: Rate Limit Reached. The number of requests per minute has exceeded the rate limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InformErrorResponse'
              example:
                message: "Too many requests"
                err_code: "Rate Limit"
                status_code: 140110
        '500':
          description: Internal Server Error. The system ran into an unexpected error. You can retry the request up to 3 times with exponential backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InformErrorResponse'
              example:
                message: "Unexpected error occurred"
                err_code: "Internal Server Error"
                status_code: 140109

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 **Inform** tile.

        **Note**: After you generate and save the Inform API Key (SECRET KEY), DO NOT generate a new key unless there is a security breach. After you generate a different key and save it, API calls using the older key won't work.
        
        For more information on authentication and getting your credentials, refer [here](https://www.moengage.com/docs/api/introduction#getting-your-credentials).
    moeAppKey:
      type: apiKey
      in: header
      name: MOE-APPKEY
      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)**.

  schemas:
    PayloadChannel:
      type: object
      required:
        - recipient
      properties:
        recipient:
          type: string
          description: 'The target for the notification. This should be a mobile number for SMS, an email address for EMAIL, or a push token for PUSH.'
        personalized_attributes:
          type: object
          additionalProperties: true
          description: |
            Key-value map for personalization. Personalization attributes are sent by the brand when invoking the Inform API and are used to resolve the content of the message.

            For iOS Live Activities (PUSH channel), the following keys are also recognized here:

            - `stale_date`: Timestamp at which the system considers the activity outdated.
            - `dismissal_date`: Timestamp at which the system automatically removes the activity from the user's screen.
        sender_attributes:
          type: array
          items:
            type: string
          description: A list of API attributes for evaluating which sender to use. If not passed, the alert will not be sent out.
        personalized_attachments:
          type: object
          additionalProperties:
            type: string
            format: byte
            description: 'A map where keys are attachment identifiers (defined in the template) and values are Base64-encoded strings of the attachment content.'
        live_activity_attributes:
          type: object
          description: |
            List of attributes used to manage the lifecycle, static data, and dynamic state of an iOS Live Activity. Applicable to the `PUSH` channel only.

            Live Activities are supported starting from MoEngage SDK version `10.09.0`.
          properties:
            la_type:
              type: string
              enum:
                - start
                - update
                - end
              description: 'The lifecycle stage of the activity: `start` (initiate), `update` (refresh content), or `end` (terminate).'
            attribute_info:
              type: object
              additionalProperties: true
              description: JSON object containing static data that remains constant throughout the activity (for example, Order ID or Flight Number).
            content_state:
              type: object
              additionalProperties: true
              description: JSON object containing the dynamic data that updates in real-time (for example, Delivery Status or ETA). Values can be set as key-value pairs using personalization tags to fetch values from the event.
    InformRequest:
      type: object
      required:
        - transaction_id
        - payloads
      properties:
        alert_id:
          type: string
          description: This field uniquely identifies the Alert to be sent to the user. For the staging endpoint, use the test alert id and for the live endpoint, use the alert id. For more information, refer to [Live and Test Alerts](#live-vs-test-environments).
        alert_reference_name:
          type: string
          description: This field is used to identify the Alert using your reference Name and can be used to identify the alert as an alternative to Alert ID.
        user_id:
          type: string
          description: This is the unique user identifier information you maintain. This information should be passed in the request to facilitate the mapping of the channel events back to the user profile to which this user_id is associated in MoEngage.
        transaction_id:
          type: string
          description: |
            This is the unique identifier denoting the transaction for which the Alert is being sent to the user. This information is maintained by the brand and is passed in the request. The maximum length allowed for this field is 50 characters.

            The Inform API supports idempotency using this parameter. If a request contains a `transaction_id` and is successful and another request with the same `transaction_id` is received within 5 minutes of the successful request, the new request would be deemed a duplicate one.
        payloads:
          type: object
          description: The payload contains the following channel-level information for all the configured channels.
          properties:
            SMS:
              $ref: '#/components/schemas/PayloadChannel'
            EMAIL:
              $ref: '#/components/schemas/PayloadChannel'
            PUSH:
              $ref: '#/components/schemas/PayloadChannel'

    ChannelStatus:
      type: object
      properties:
        message:
          type: string
        err_code:
          type: string
        status_code:
          type: integer

    InformSuccessResponse:
      type: object
      properties:
        message:
          type: string
          example: "Successfully Received"
        request_id:
          type: string
        SMS:
          $ref: '#/components/schemas/ChannelStatus'
        EMAIL:
          $ref: '#/components/schemas/ChannelStatus'
        PUSH:
          $ref: '#/components/schemas/ChannelStatus'

    # FIX: Removed hardcoded examples from here so the specific response examples take precedence
    InformErrorResponse:
      type: object
      properties:
        message:
          type: string
        err_code:
          type: string
        status_code:
          type: integer