openapi: 3.0.3
info:
  title: MoEngage Message Archival API
  description: |
    This API allows you to store and access any communication sent to customers for later access. 
    
    For more information, refer to [Message Archival](/user-guide/campaigns-and-channels/campaign-management-and-reports/message-archival/message-archival).
  version: '1.0'

servers:
  - url: 'https://api-{dc}.moengage.com/v1'
    description: MoEngage 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."

tags:
  - name: Message Archival
    description: Retrieve archived message content.

security:
  - basicAuth: []

paths:
  /archival/view:
    post:
      tags:
        - Message Archival
      summary: View Archived Message
      operationId: viewArchivedMessage
      description: |
        You can use this API to store any communication sent to customers for later access.
       
      x-mint:
        content: |
          #### Rate Limit
          The rate limit for this endpoint is **1000 RPM**.

      parameters:
        - name: 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:
        description: The request body contains the parameters required to identify and retrieve the message.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArchivalRequest'
            examples:
              pushAndroidExample:
                summary: Push (Android) Archival Request
                value:
                  user_id: 'USER_ID_123'
                  delivery_type: ONE_TIME
                  campaign_type: General Push Campaign
                  campaign_channel: PUSH
                  sent_epoch_time: 1716915262
                  campaign_id: 'CAMPAIGN_ID_XYZ'
                  event_name: Notification Received Android
                  platform: ANDROID
              smsExample:
                summary: SMS Archival Request
                value:
                  user_id: 'USER_ID_123'
                  delivery_type: ONE_TIME
                  campaign_type: SMS
                  campaign_channel: SMS
                  sent_epoch_time: 1716972486
                  campaign_id: 'CAMPAIGN_ID_XYZ'
                  event_name: SMS Sent
                  platform: SMS
                  event_id: 'EVENT_ID_ABC'
              emailExample:
                summary: Email Archival Request
                value:
                  user_id: 'USER_ID_123'
                  delivery_type: ONE_TIME
                  campaign_type: Email Campaign
                  campaign_channel: EMAIL
                  sent_epoch_time: 1717150294
                  campaign_id: 'CAMPAIGN_ID_XYZ'
                  event_name: Email Sent
                  platform: EMAIL
              pushIosExample:
                summary: Push (iOS) Archival Request
                value:
                  user_id: 'USER_ID_123'
                  delivery_type: ONE_TIME
                  campaign_type: General Push Campaign
                  campaign_channel: PUSH
                  sent_epoch_time: 1717060428
                  campaign_id: 'CAMPAIGN_ID_XYZ'
                  event_name: Notification Sent iOS
                  platform: IOS
              pushWebExample:
                summary: Push (Web) Archival Request
                value:
                  user_id: 'USER_ID_123'
                  delivery_type: ONE_TIME
                  campaign_type: General Push Campaign
                  campaign_channel: PUSH
                  sent_epoch_time: 1717056071
                  campaign_id: 'CAMPAIGN_ID_XYZ'
                  event_name: Notification Received Web
                  platform: WEB

      responses:
        '200':
          $ref: '#/components/responses/Success200'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'

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

        For more information on authentication and getting your credentials, refer [here](https://www.moengage.com/docs/api/introduction#getting-your-credentials).
  
  schemas:
    ArchivalRequest:
      type: object
      required:
        - user_id
        - delivery_type
        - campaign_type
        - campaign_channel
        - sent_epoch_time
        - campaign_id
        - event_name
        - platform
      properties:
        user_id:
          type: string
          description: |
            This field denotes the unique identifier of the user.
        delivery_type:
          type: string
          description: |
            This field denotes the delivery type of the channel.
          enum:
            - ONE_TIME
            - PERIODIC
            - EVENT_TRIGGERED
            - LOCATION_TRIGGERED
            - DEVICE_TRIGGERED
            - API_TRIGGERED
            - BUSINESS_EVENT_TRIGGERED
        campaign_type:
          type: string
          description: |
            This field denotes the campaign type.
            
            **Supported Values:**
            * **Push:** General Push Campaign, Autotrigger Campaign, Geo-fencing Campaign, Business Event Trigger Push Campaign
            * **SMS:** sms, Business Event Trigger SMS Campaign
            * **Email:** Email Campaign, Email Triggers, Business Event Trigger Email Campaign
            * **Alerts:** Inform Email, Inform SMS, Inform Push
          enum:
            - General Push Campaign
            - Autotrigger Campaign
            - Geo-fencing Campaign
            - Business Event Trigger Push Campaign
            - sms
            - Business Event Trigger SMS Campaign
            - Email Campaign
            - Email Triggers
            - Business Event Trigger Email Campaign
            - Inform Email
            - Inform SMS
            - Inform Push
        campaign_channel:
          type: string
          description: The campaign channel.
          enum:
            - EMAIL
            - SMS
            - PUSH
            - FLOWS
        sent_epoch_time:
          type: integer
          format: int64
          description: The sent time of the campaign as a Unix epoch timestamp.
          example: 1716972486
        campaign_id:
          type: string
          description: This field denotes the campaign ID.
        event_name:
          type: string
          description: The name of the event (e.g., 'Email Sent', 'SMS Sent', 'Notification Sent iOS').
          enum:
            - Email Sent
            - SMS Sent
            - Notification Sent iOS
            - Notification Received Android
            - Notification Received Web
        platform:
          type: string
          description: The target platform of the campaign.
          enum:
            - IOS
            - ANDROID
            - WEB
            - EMAIL
            - SMS
            - MWEB
        event_id:
          type: string
          description: |
            The event ID. **Required for event-triggered campaigns.**
            
            * You must pass `moe_event_id` if any event attribute is present for campaigns.
            * You must pass `moe_transaction_id` for alerts.
   
    ArchivalResponseSuccess:
      type: object
      properties:
        status:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/ArchivalData'
   
    ArchivalData:
      type: object
      properties:
        message_details:
          $ref: '#/components/schemas/MessageDetails'
        message_content:
          $ref: '#/components/schemas/MessageContent'
        backup_content:
          $ref: '#/components/schemas/MessageContent'
        file_info:
          $ref: '#/components/schemas/FileInfo'
   
    MessageDetails:
      type: object
      properties:
        message_type:
          type: string
          example: campaign
        message_id:
          type: string
          example: 66560c2d2880326031c474a6
        channel:
          type: string
          example: push
        platform:
          type: string
          example: android
        delivery_type:
          type: string
          example: ONE_TIME
        sent_time:
          type: string
          example: 'Tue, 28 May 2024 22:24:22 IST'
        message_to:
          type: string
          example: 'cZug38RqRd2-cF30bd2vda:APA91bGEG-OHMiWV3eHd_ohLs8V-yTgDJuQXNV32jO13or-R118OAC65MXdSx5ozYsIiL-RFan_iflQ62XVX7T2BiNqqQQfKd3FitlpbLR7nVBdkFF1yv_s8pqZux-HfThn-ojhpBIWd'
        moe_event_id:
          type: string
          nullable: true
          example: null
        service:
          type: object
          properties:
            type:
              type: string
              example: FCM
        template_info:
          type: object
          properties:
            type:
              type: string
              example: Native
            version:
              type: string
              nullable: true
              example: null
            id:
              type: string
              example: stylizedbasic
   
    MessageContent:
      type: object
      properties:
        title:
          type: string
        summary:
          type: string
          nullable: true
        message:
          type: string
        related_urls:
          type: array
          items:
            type: string
            format: uri
   
    FileInfo:
      type: object
      properties:
        version:
          type: string
          example: v2
        file_name:
          type: string
          example: '66560c2d2880326031c474a6_pramodseg_1716915262_push_android.json'
   
    ErrorResponse400:
      type: object
      properties:
        status:
          type: boolean
          example: false
        error_message:
          type: string
          example: 'This event is unsupported to view message copy. The supported events are [...]'
   
    ErrorResponse401:
      type: object
      properties:
        status:
          type: boolean
          example: false
        error:
          type: string
          example: Invalid data key
   
    ErrorResponse500:
      type: object
      properties:
        title:
          type: string
          example: Server Error
        description:
          type: string
          example: An unexpected error was encountered while processing this request. Please contact MoEngage Team
        code:
          type: string
          example: 'BiaFuAzn-aefa0b0e-2c88-4106-8d07-0f0c53513e48'

  responses:
    Success200:
      description: Success. The server successfully processed the request, but is not returning any content.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ArchivalResponseSuccess'
          example:
            status: true
            data:
              message_details:
                message_type: campaign
                message_id: 66560c2d2880326031c474a6
                channel: push
                platform: android
                delivery_type: ONE_TIME
                sent_time: 'Tue, 28 May 2024 22:24:22 IST'
                message_to: 'cZug38RqRd2-cF30bd2vda:APA91bGEG-OHMiWV3eHd_ohLs8V-yTgDJuQXNV32jO13or-R118OAC65MXdSx5ozYsIiL-RFan_iflQ62XVX7T2BiNqqQQfKd3FitlpbLR7nVBdkFF1yv_s8pqZux-HfThn-ojhpBIWd'
                moe_event_id: null
                service:
                  type: FCM
                template_info:
                  type: Native
                  version: null
                  id: stylizedbasic
              message_content:
                title: expiry in 1 hour
                summary: expiry in 1 hour
                message: expiry in 1 hour
                related_urls:
                  - 'https://image-staging-ap1.moengage.com/checkfcsgainmoengage/20240527083246095196HE4ELHScreenshotofUploadyourAppDiawiDevelopmentandInhouseAppsWirelessInstallationjpgcheckfcsgainmoengage.jpg'
              backup_content:
                title: Stylized Android Template
                summary: null
                message: Sample Stylized Android Template
                related_urls: []
              file_info:
                version: v2
                file_name: '66560c2d2880326031c474a6_pramodseg_1716915262_push_android.json'
    Error400:
      description: "Bad Request. This response is returned when the required parameters are missing from the request, or when the provided parameters are invalid, or when a template already exists with the same version, name, or id."
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse400'
          example:
            status: false
            error_message: "This event is unsupported to view message copy. The supported events are ['Email Sent', 'SMS Sent', 'Notification Sent iOS', 'Notification Received Android', 'Notification Received Web']"
    Error401:
      description: "Authentication Failure. This response is returned when the authorization parameters are missing in the HTTP Auth Header."
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse401'
          example:
            status: false
            error: Invalid data key
    Error429:
      description: "Too Many Requests. A number of headers are returned in case of a rate-limit breach."
    Error500:
      description: "Internal Server Error. This response is returned when the system runs into an unexpected error."
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse500'
          example:
            title: Server Error
            description: An unexpected error was encountered while processing this request. Please contact MoEngage Team
            code: 'BiaFuAzn-aefa0b0e-2c88-4106-8d07-0f0c53513e48'
    Error502:
      description: "Server Error. Something went wrong on MoEngage."