openapi: 3.2.0
info:
  title: Contact Center Chat Gateway Attachments API
  version: 1.0.0
  contact:
    email: cc-cluj-iris@8x8.com
  description: Integration with the 8x8 Contact Center (CC) Chat API
servers:
- url: https://api.8x8.com
tags:
- name: Attachments
  description: Allows adding and retrieving attachments of a conversation.
paths:
  /chat-gateway/v1/conversations/{conversationId}/attachments:
    get:
      tags:
      - Attachments
      summary: Get attachments in Conversation.
      description: Get all attachments added to the conversation along with their details.
      operationId: getconversationattachments
      security:
      - 8x8ApiKey:
        - Contact Center Chat Gateway
      parameters:
      - $ref: '#/components/parameters/ChatAPIConversationUrlID'
      - $ref: '#/components/parameters/PageSizeFilterOptional'
      - $ref: '#/components/parameters/PageIndexFilterOptional'
      - $ref: '#/components/parameters/SortByOptional'
      - $ref: '#/components/parameters/FilterOptional'
      - $ref: '#/components/parameters/TenantIdFilterOptional'
      responses:
        '200':
          description: Attachments list
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/AttachmentsResult'
        '400':
          $ref: '#/components/responses/GeneralErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenRequestResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundResponse'
        '500':
          $ref: '#/components/responses/GeneralErrorResponse'
        default:
          $ref: '#/components/responses/GeneralErrorResponse'
    post:
      tags:
      - Attachments
      summary: Add an attachment.
      description: Add an attachment that you can later use as a reference when adding a message to the conversation.
      operationId: addconversationattachments
      security:
      - 8x8ApiKey:
        - Contact Center Chat Gateway
      parameters:
      - $ref: '#/components/parameters/ChatAPIConversationUrlID'
      - $ref: '#/components/parameters/TenantIdFilterOptional'
      requestBody:
        $ref: '#/components/requestBodies/AttachmentUpload'
      responses:
        '200':
          description: Created attachment
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/AttachmentResult'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/GeneralErrorResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundResponse'
        '500':
          $ref: '#/components/responses/GeneralErrorResponse'
        default:
          $ref: '#/components/responses/GeneralErrorResponse'
  /chat-gateway/v1/conversations/{conversationId}/attachments/{attachmentId}:
    get:
      tags:
      - Attachments
      summary: Get an attachment from Conversation.
      description: Get an attachment from conversation along with their details.
      operationId: getconversationattachment
      security:
      - 8x8ApiKey:
        - Contact Center Chat Gateway
      parameters:
      - $ref: '#/components/parameters/ChatAPIConversationUrlID'
      - $ref: '#/components/parameters/AttachmentID'
      - $ref: '#/components/parameters/TenantIdFilterOptional'
      responses:
        '200':
          description: Attachments list
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/AttachmentResult'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenRequestResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundResponse'
        '500':
          $ref: '#/components/responses/GeneralErrorResponse'
        default:
          $ref: '#/components/responses/GeneralErrorResponse'
  /chat-gateway/v1/conversations/{conversationId}/attachments/{attachmentId}/content:
    get:
      tags:
      - Attachments
      summary: Download attachment.
      description: Download attachment contents.
      operationId: downloadattachmentforchatapiconversation
      security:
      - 8x8ApiKey:
        - Contact Center Chat Gateway
      parameters:
      - $ref: '#/components/parameters/ChatAPIConversationUrlID'
      - $ref: '#/components/parameters/AttachmentID'
      - $ref: '#/components/parameters/TenantIdFilterOptional'
      responses:
        '200':
          description: Attachments content
          headers:
            Content-Disposition:
              schema:
                type: string
              description: Content-Disposition response header is a header indicating if the content is expected to be displayed inline in the browser, that is, as a Web page or as part of a Web page, or as an attachment, that is downloaded and saved locally.
          content:
            application/octet-stream:
              schema:
                type: string
                description: Success
                format: binary
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenRequestResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundResponse'
        '500':
          $ref: '#/components/responses/GeneralErrorResponse'
        default:
          $ref: '#/components/responses/GeneralErrorResponse'
components:
  schemas:
    PageResult:
      type: object
      properties:
        page:
          type: object
          properties:
            size:
              type: number
              format: int32
              description: Page size of the response.
            number:
              type: number
              format: int32
              description: Page 0-based index of the response.
            totalElements:
              type: number
              format: int32
              description: Total number of items.
            totalPages:
              type: number
              format: int32
              description: Total number of pages.
    GenericExceptionPayload:
      type: object
      properties:
        message:
          type: string
          description: Error message.
          example: Internal error.
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                description: Unique error code.
                example: invalid_queue
              message:
                type: string
                description: Free text error description.
                example: Queue ID 112 is invalid.
    ForbiddenViolationProblem:
      type: object
      properties:
        message:
          type: string
          description: Error message.
          example: The tenant does not belong to customer.
        errors:
          type: array
          items:
            type: string
            example: Header X-8x8-Tenant doesn't match tenant information for customerId=aaaa
    ResourceNotFoundProblem:
      type: object
      properties:
        message:
          type: string
          description: Error message.
          example: Resource of type <<resourceType>> with id <<resourceId>> was not found.
        errors:
          type: array
          items:
            type: string
            example: Tenant <<tenantId>> does not belong to customer <<customerId>>.
    AttachmentsResult:
      allOf:
      - type: object
        required:
        - data
        properties:
          _embedded:
            type: object
            properties:
              attachments:
                type: array
                items:
                  $ref: '#/components/schemas/AttachmentResult'
      - $ref: '#/components/schemas/Links'
      - $ref: '#/components/schemas/PageResult'
    UnauthorizedProblem:
      type: object
      properties:
        message:
          type: string
          example: Access Denied
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
                example: Access Denied
              code:
                type: string
                example: access_denied
        referenceId:
          type: string
          example: dacd0dd252723a2
    ExternalAuthorType:
      type: string
      x-extensible-enum:
      - bot
      - user
      default: user
    AttachmentResult:
      type: object
      required:
      - id
      - filename
      - size
      - type
      - createdAt
      properties:
        id:
          type: string
          example: T6c-pPJYJoeiTZOJ4RxEOzXMBcmxG8KES2TZkmvuukcUPxgdZrBKIRbVMwnTLmk0nIXxWSNoSnaeJOZ5BIXV4Q
        filename:
          type: string
          example: sample-doc.docx
        sizeInBytes:
          type: number
          format: int64
          example: 4166
          description: File size in bytes
        createdAt:
          type: string
          format: date-time
          description: Creation date and time
          example: '2021-01-30T08:30:00Z'
    Links:
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              type: object
              properties:
                href:
                  type: string
  parameters:
    TenantIdFilterOptional:
      name: X-8x8-Tenant
      in: header
      required: false
      description: Tenant ID, it is going to be mandatory if customer has more than one CC tenant in his organisation.
      schema:
        type: string
        format: string
      example: TheTenant
    SortByOptional:
      name: sort
      in: query
      required: false
      description: Attribute on which sorting direction is applied.
      schema:
        type: string
        default: id:asc
        example: id:asc
    FilterOptional:
      name: filter
      in: query
      required: false
      description: Filter for a query in FIQL format.
      schema:
        type: string
        example: name==Cosmin,(routingOption.id==11)
    ChatAPIConversationUrlID:
      name: conversationId
      in: path
      required: true
      description: Conversation identifier.
      schema:
        type: string
        format: string
        example: '125'
    AttachmentID:
      name: attachmentId
      in: path
      required: true
      description: Attachment ID
      schema:
        type: string
        format: string
        example: T6c-pPJYJoeiTZOJ4RxEOzXMBcmxG8KES2TZkmvuukcUPxgdZrBKIRbVMwnTLmk0nIXxWSNoSnaeJOZ5BIXV4Q
    PageSizeFilterOptional:
      name: size
      in: query
      required: false
      description: Response page size.
      schema:
        type: number
        format: int32
        default: 20
      example: 100
    PageIndexFilterOptional:
      name: page
      in: query
      required: false
      description: Response page index.
      schema:
        type: number
        format: int32
        default: 0
        example: 1
  responses:
    UnauthorizedResponse:
      description: Contains a description of the error.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/UnauthorizedProblem'
    GeneralErrorResponse:
      description: Contains a description of the error.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/GenericExceptionPayload'
    ForbiddenRequestResponse:
      description: Contains a descriptive response.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ForbiddenViolationProblem'
    ResourceNotFoundResponse:
      description: Contains a descriptive information.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ResourceNotFoundProblem'
  requestBodies:
    AttachmentUpload:
      description: Defines the file upload request payload. Contains the file part and the authorType part.
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            properties:
              attachment:
                type: string
                format: binary
              authorType:
                $ref: '#/components/schemas/ExternalAuthorType'
  securitySchemes:
    8x8ApiKey:
      type: apiKey
      name: x-api-key
      in: header
x-readme:
  explorer-enabled: true
  proxy-enabled: false
  samples-enabled: true