openapi: 3.0.1
info:
  title: Conversation API
  description: 'Provides methods for creating, retrieving, updating, and deleting

    conversations. Supports management of conversation participants—adding and

    removing members—and typing indicators to signal real-time interaction

    within a conversation.'
  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}:
    get:
      summary: Retrieves a conversation
      parameters:
      - name: conversationId
        in: path
        description: The id of the conversation
        required: true
        schema:
          type: string
      - name: includeDeleted
        in: query
        description: Indicates whether deleted conversations should be returned
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: The requested conversation
          headers:
            ETag:
              description: A unique value representing the version of the conversation, optionally used for optimistic concurrency control on PUT and DELETE
              schema:
                type: string
            Last-Modified:
              description: The date the conversation was last updated in ISO 8601 format
              schema:
                type: string
                format: date-time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '404':
          description: The conversation was not found
          content: {}
    put:
      summary: Updates a conversation
      parameters:
      - name: conversationId
        in: path
        description: The id of the conversation
        required: true
        schema:
          type: string
      - name: if-match
        in: header
        description: An optional ETag for optimistic concurrency control
        required: false
        schema:
          type: string
      requestBody:
        description: Detail of the conversation to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationUpdate'
        required: true
      responses:
        '200':
          description: The updated conversation
          headers:
            ETag:
              description: A unique value representing the version of the conversation, optionally used for optimistic concurrency control on PUT and DELETE
              schema:
                type: string
            Last-Modified:
              description: The date the conversation was last updated in ISO 8601 format
              schema:
                type: string
                format: date-time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '400':
          description: Validation issues were found
          content: {}
        '404':
          description: The conversation was not found
          content: {}
        '409':
          description: A conncurrency issue occured updating the conversation
          content: {}
        '412':
          description: The specified 'if-match' header was not valid, refresh and retry
          content: {}
      x-codegen-request-body-name: name
    delete:
      summary: Deletes a conversation
      parameters:
      - name: conversationId
        in: path
        description: The id of the conversation
        required: true
        schema:
          type: string
      - name: if-match
        in: header
        description: An optional ETag for optimistic concurrency control
        required: false
        schema:
          type: string
      responses:
        '204':
          description: Indicates successful deletetion of an conversation
          content: {}
        '404':
          description: The conversation was not found
          content: {}
        '409':
          description: A conncurrency issue occured deleting the conversation
          content: {}
        '412':
          description: The specified 'if-match' header was not valid, refresh and retry
          content: {}
  /cpaas/conversations:
    get:
      summary: Retrieves a list of conversations
      parameters:
      - name: scope
        in: query
        description: 'Defines the scope of the conversations to be returned - either all public conversations, '
        required: false
        schema:
          type: string
          enum:
          - public
          - participant
      - name: profileId
        in: query
        description: Indicates whether only conversations the profile is a participant of should be returned
        required: false
        schema:
          type: string
      - name: includeDeleted
        in: query
        description: Indicates whether deleted conversations should be returned
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: A list of matching conversations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConversationQueryResult'
    post:
      summary: Creates a new conversation
      requestBody:
        description: Detail of the conversation to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationCreate'
        required: true
      responses:
        '201':
          description: The conversation was successfully created
          headers:
            ETag:
              description: A unique value representing the version of the conversation, optionally used for optimistic concurrency control on PUT and DELETE
              schema:
                type: string
            Last-Modified:
              description: The date the conversation was last updated in ISO 8601 format
              schema:
                type: string
                format: date-time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '400':
          description: Validation issues were found
          content: {}
        '409':
          description: The conversation already exists
          content: {}
      x-codegen-request-body-name: conversation
  /cpaas/conversations/{conversationId}/typing:
    post:
      summary: Indicates that the caller is typing in this conversation
      parameters:
      - name: conversationId
        in: path
        description: The id of the conversation
        required: true
        schema:
          type: string
      responses:
        '204':
          description: The request was accepted
          content: {}
    delete:
      summary: Indicates that the caller has stopped typing in this conversation
      parameters:
      - name: conversationId
        in: path
        description: The id of the conversation
        required: true
        schema:
          type: string
      responses:
        '204':
          description: The request was accepted
          content: {}
  /cpaas/conversations/{conversationId}/participants:
    get:
      summary: Retrieves the conversation participants
      parameters:
      - name: conversationId
        in: path
        description: The id of the conversation
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The requested conversation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Participant'
        '404':
          description: The conversation was not found
          content: {}
    post:
      summary: Adds a list of participants to a conversation
      parameters:
      - name: conversationId
        in: path
        description: The id of the conversation
        required: true
        schema:
          type: string
      requestBody:
        description: The list of participants to add to the conversation
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Participant'
        required: true
      responses:
        '201':
          description: The participants were added
          content: {}
        '400':
          description: Validation issues were found
          content: {}
        '404':
          description: The conversation was not found
          content: {}
      x-codegen-request-body-name: participants
    delete:
      summary: Deletes a list of participants from a conversation
      parameters:
      - name: conversationId
        in: path
        description: The id of the conversation
        required: true
        schema:
          type: string
      - name: id
        in: query
        description: The profile ids of participants to remove from the conversation
        required: true
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      responses:
        '204':
          description: The list was accepted and valid participants will be removed
          content: {}
        '404':
          description: The conversation was not found
          content: {}
components:
  schemas:
    ConversationCreate:
      required:
      - id
      - isPublic
      - name
      - roles
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the conversation
        name:
          type: string
          description: The name of the conversation
        description:
          type: string
          description: The description of the conversation
        roles:
          $ref: '#/components/schemas/Roles'
        isPublic:
          type: boolean
          description: Determines whether the conversation is publically visible
        participants:
          type: array
          items:
            $ref: '#/components/schemas/Participant'
        messageScope:
          type: string
          description: Indicates if a conversation is A2P or P2P
          enum:
          - a2p
          - p2p
    ConversationUpdate:
      required:
      - name
      - roles
      type: object
      properties:
        name:
          type: string
          description: The name of the conversation
        description:
          type: string
          description: The description of the conversation
        roles:
          $ref: '#/components/schemas/Roles'
    Conversation:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the conversation
        name:
          type: string
          description: The name of the conversation
        description:
          type: string
          description: The description of the conversation
        roles:
          $ref: '#/components/schemas/Roles'
        isPublic:
          type: boolean
          description: Determines whether the conversation is publically visible
        messageScope:
          type: string
          description: Indicates if a conversation is A2P or P2P
          enum:
          - a2p
          - p2p
        _createdOn:
          type: string
          description: The date (in UTC, ISO 8601 format) that the conversation was created
          format: date-time
          readOnly: true
        _createdBy:
          type: string
          description: The identity that created the conversation
        _updatedOn:
          type: string
          description: The date (in UTC, ISO 8601 format) that the conversation was last updated
          format: date-time
          readOnly: true
        _updatedBy:
          type: string
          description: The identity that created the conversation
          readOnly: true
    ConversationQueryResult:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the conversation
        name:
          type: string
          description: The name of the conversation
        description:
          type: string
          description: The description of the conversation
        roles:
          $ref: '#/components/schemas/Roles'
        isPublic:
          type: boolean
          description: Determines whether it is publically visible
        participantCount:
          type: integer
          description: The total number of participants
        latestSentEventId:
          type: integer
          description: The eventId of the last message sent
        messageScope:
          type: string
          description: Indicates if a conversation is A2P or P2P
          enum:
          - a2p
          - p2p
        _createdOn:
          type: string
          description: The date (in UTC, ISO 8601 format) that the conversation was created
          format: date-time
          readOnly: true
        _createdBy:
          type: string
          description: The identity that created the conversation
        _updatedOn:
          type: string
          description: The date (in UTC, ISO 8601 format) that the conversation was last updated
          format: date-time
          readOnly: true
        _updatedBy:
          type: string
          description: The identity that created the conversation
          readOnly: true
    Roles:
      required:
      - owner
      - participant
      type: object
      properties:
        owner:
          $ref: '#/components/schemas/Privileges'
        participant:
          $ref: '#/components/schemas/Privileges'
      description: Describes the roles belonging to the conversation
    Role:
      $ref: '#/components/schemas/Privileges'
    Privileges:
      required:
      - canAddParticipants
      - canRemoveParticipants
      - canSend
      type: object
      properties:
        canSend:
          type: boolean
          description: Determines whether the role assigned can send to the conversation
        canAddParticipants:
          type: boolean
          description: Determines whether the role assigned can add participants to the conversation
        canRemoveParticipants:
          type: boolean
          description: Determines whether the role assigned can remove participants from the conversation
    Participant:
      required:
      - id
      type: object
      properties:
        id:
          type: string
          description: The id of the conversation participant's profile
        role:
          type: string
          description: The role of the conversation participant
          enum:
          - owner
          - participant
          default: participant
  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