openapi: 3.0.1
info:
  title: Conversation Message API
  description: 'Send and retrieve messages in conversations. Use this API to retrieve

    conversation events, retrieve messages working backwards from a point in

    time, send new messages to a conversation, and post delivery and read

    status updates for messages.'
  version: 1.0.1
servers:
- url: https://{region}-api.dotdigital.com
  variables:
    region:
      description: The Dotdigital region id your account belongs to
      enum:
      - r1
      - r2
      - r3
      default: r1
security:
- basicAuth: []
paths:
  /cpaas/conversations/{conversationId}/events:
    get:
      summary: Retrieves a conversation's events
      parameters:
      - name: conversationId
        in: path
        description: The id of the conversation
        required: true
        schema:
          type: string
      - name: from
        in: query
        description: The event id to start from
        required: true
        schema:
          minimum: 0
          type: integer
      - name: limit
        in: query
        description: The number of events to read forward
        required: true
        schema:
          minimum: 0
          type: integer
      responses:
        '200':
          description: A list of conversation events
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MessageEvent'
  /cpaas/conversations/{conversationId}/messages:
    get:
      summary: Retrieves a conversation's messages from an point (event) in time and works backwards
      parameters:
      - name: conversationId
        in: path
        description: The id of the conversation
        required: true
        schema:
          type: string
      - name: from
        in: query
        description: The event id to work backwards from
        required: false
        schema:
          minimum: 0
          type: integer
      - name: limit
        in: query
        description: The number of messages to return
        required: true
        schema:
          maximum: 100
          minimum: 1
          type: integer
      responses:
        '200':
          description: A list of partial and the requested number of complete messages, aggregated from the conversation events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResult'
    post:
      summary: Sends a message to conversation
      parameters:
      - name: conversationId
        in: path
        description: The id of the conversation
        required: true
        schema:
          type: string
      requestBody:
        description: Detail of the message to send
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessagePost'
        required: true
      responses:
        '200':
          description: The message was successfully sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessagePostResult'
      x-codegen-request-body-name: message
  /cpaas/conversations/{conversationId}/messages/statusupdates:
    post:
      summary: Posts message updates back
      parameters:
      - name: conversationId
        in: path
        description: The id of the conversation
        required: true
        schema:
          type: string
      requestBody:
        description: Details of the message status updates
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/MessageStatusUpdate'
        required: true
      responses:
        '200':
          description: The status updates were successfully received
          content: {}
      x-codegen-request-body-name: updates
components:
  schemas:
    MessageResult:
      type: object
      properties:
        earliestEventId:
          type: integer
          description: The earliest event id that was included in the message aggregation. If this value is above 0, there will be more data available and should be used in the 'from' parameter of subsequent calls
        latestEventId:
          type: integer
          description: The latest event id that was included in the message aggregation.
        messages:
          type: array
          items:
            $ref: '#/components/schemas/MessageComplete'
        orphanedEvents:
          type: array
          items:
            $ref: '#/components/schemas/MessageEvent'
      description: A list of conversation messages
    MessageComplete:
      type: object
      properties:
        id:
          pattern: ^([a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})|[a-f0-9]{32}$
          type: string
          description: The id of the message
        sentEventId:
          type: integer
          description: The event id that corresponds to the sent event for the message
        metadata:
          type: object
          properties: {}
          description: Custom metadata relating to the message
        context:
          $ref: '#/components/schemas/MessageContext'
        parts:
          type: array
          items:
            $ref: '#/components/schemas/MessagePart'
        statusUpdates:
          type: object
          properties: {}
          description: Array of updates keyed by the profileId and a list of statues and the date the status was set
      description: Details of a message sent to a conversation
    MessageEvent:
      type: object
      properties:
        id:
          type: integer
          description: The id of the event
        data:
          type: object
          properties: {}
          description: The event data
      description: An event relating to a message
    MessageContext:
      type: object
      properties:
        from:
          $ref: '#/components/schemas/MessageContextFrom'
        conversationId:
          type: string
          description: The id of the conversation that the message was sent on
        sentBy:
          type: string
          description: The message sender
        sentOn:
          type: string
          description: The date the message was sent in ISO 8601 format
          format: date-time
        scope:
          type: string
          description: Indicates if a conversation is A2P or P2P
          enum:
          - a2p
          - p2p
          default: p2p
        direction:
          type: string
          description: Indicates the direction of the message (only applicable to a2p messages)
          enum:
          - inbound
          - outbound
      description: Platform metadata relating to the message
    MessageContextFrom:
      type: object
      properties:
        id:
          type: string
          description: The id of the profile the message was from
        name:
          type: string
          description: The name for the profile that sent the message
        avatarUrl:
          type: string
          description: URL for an avatar to display with this message
      description: Details of the sender of a message
    MessagePost:
      required:
      - parts
      type: object
      properties:
        from:
          $ref: '#/components/schemas/MessagePost_from'
        metadata:
          type: object
          properties: {}
          description: Custom metadata relating to the message
        parts:
          type: array
          items:
            $ref: '#/components/schemas/MessagePart'
        alert:
          $ref: '#/components/schemas/MessageAlert'
        direction:
          type: string
          description: Indicates the direction of the message (only applicable to a2p messages)
          enum:
          - inbound
          - outbound
      description: Details of a message to post to the conversation
    MessagePostResult:
      required:
      - id
      type: object
      properties:
        id:
          type: string
          description: The globally unique id of the message
        eventId:
          type: integer
          description: The id of the event corresponding to the send in the message stream for this conversation
      description: The id of the message sent event recorded
    MessagePart:
      type: object
      properties:
        name:
          type: string
          description: A name for the part
        type:
          type: string
          description: The mime type (if applicable) sof the part
        url:
          type: string
          description: A url associated with the message part
        data:
          type: string
          description: String representation (e.g. base64) of the message part
        size:
          type: integer
          description: Size of the message part in bytes
      description: Details of a single part that makes up the message
    MessageAlert:
      type: object
      properties:
        title:
          type: string
          description: Title for the notification to send to all platforms. Note that this is ignored if any details are set in platforms
        body:
          type: string
          description: Body for the notification to send to all platforms. Note that this is ignored if any details are set in platforms
        platforms:
          $ref: '#/components/schemas/MessageAlertPlatforms'
      description: Details of the alert to be displayed on receipt of the message
    MessageAlertPlatforms:
      type: object
      properties:
        apns:
          $ref: '#/components/schemas/MessageAlertApns'
        fcm:
          $ref: '#/components/schemas/MessageAlertFcm'
      description: The platform specific details for the alert. If specified, these are set verbatim and alert.title / alert.body values are ignored
    MessageAlertApns:
      type: object
      properties:
        badge:
          type: integer
          description: The value to display on the application badge
        sound:
          type: string
          description: The soundfile to play on the device when the notification arrived
        alert:
          type: string
          description: The alert to display on the device when the notification arrives
        payload:
          type: object
          properties: {}
          description: The payload to send to the device
      description: The APNS details for the alert
    MessageAlertFcm:
      type: object
      properties:
        collapse_key:
          type: string
          description: The collapse key to send to FCM
        data:
          type: object
          properties: {}
          description: The payload to send to the device
        notification:
          $ref: '#/components/schemas/MessageAlertFcmNotification'
      description: The FCM details for the alert
    MessageAlertFcmNotification:
      type: object
      properties:
        title:
          type: string
          description: The title to display
        body:
          type: string
          description: The body to display
        icon:
          type: string
          description: The icon to display
      description: Details of the notification to display
    MessageStatusUpdate:
      required:
      - messageIds
      - status
      - timestamp
      type: object
      properties:
        messageIds:
          type: array
          description: A list of message ids being updated
          items:
            type: string
        status:
          type: string
          description: The status to update each message to
          enum:
          - delivered
          - read
        timestamp:
          type: string
          description: The date of the status update in ISO 8601 format
          format: date-time
    MessagePost_from:
      required:
      - profileId
      type: object
      properties:
        profileId:
          type: string
          description: The id of the profile to send from
        name:
          type: string
          description: Name to display
      description: Set of identifiers for the message sender.
  parameters:
    conversationIdPathParameter:
      name: conversationId
      in: path
      description: The id of the conversation
      required: true
      schema:
        type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
x-readme:
  samples-languages:
  - curl
  - csharp
  - java
  - node
  - php
  - python
  - ruby
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true