8x8 Messages API

openapi: 3.2.0
info:
  title: Contact Center Chat Gateway Messages 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: Messages
  description: Allows adding and retrieving messages of a conversation.
paths:
  /chat-gateway/v1/conversations/{conversationId}/messages:
    get:
      tags:
      - Messages
      summary: Retrieves the conversation messages.
      description: Retrieves the conversation messages that took place during the lifespan of the conversation.
      operationId: getmessagesforcctransaction-1
      security:
      - 8x8ApiKey:
        - Contact Center Chat Gateway
      parameters:
      - $ref: '#/components/parameters/ChatAPIConversationUrlID'
      - $ref: '#/components/parameters/PageSizeFilterOptional'
      - $ref: '#/components/parameters/PageIndexFilterOptional'
      - $ref: '#/components/parameters/SortByDateOptional'
      - $ref: '#/components/parameters/TenantIdFilterOptional'
      responses:
        '200':
          description: Message list
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/MessageListResult'
        '400':
          $ref: '#/components/responses/GeneralErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenRequestResponse'
        '500':
          $ref: '#/components/responses/GeneralErrorResponse'
        default:
          $ref: '#/components/responses/GeneralErrorResponse'
    post:
      tags:
      - Messages
      summary: Send a message.
      description: Send a message to a conversation represented by the provided ID.
      operationId: sendmessagetocctransaction-1
      security:
      - 8x8ApiKey:
        - Contact Center Chat Gateway
      parameters:
      - $ref: '#/components/parameters/ChatAPIConversationUrlID'
      - $ref: '#/components/parameters/TenantIdFilterOptional'
      requestBody:
        $ref: '#/components/requestBodies/SendMessageToConversationRequest'
      responses:
        '202':
          description: Accepted message.
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '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}/messages/{messageId}:
    get:
      tags:
      - Messages
      summary: Retrieves the conversation messages.
      description: Retrieves the conversation messages that took place during the lifespan of the conversation.
      operationId: getmessagebyidforcctransaction
      security:
      - 8x8ApiKey:
        - Contact Center Chat Gateway
      parameters:
      - $ref: '#/components/parameters/ChatAPIConversationUrlID'
      - $ref: '#/components/parameters/MessageID'
      - $ref: '#/components/parameters/TenantIdFilterOptional'
      responses:
        '200':
          description: Message list
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/MessageResult'
        '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:
  requestBodies:
    SendMessageToConversationRequest:
      description: Defines the send message request payload.
      required: true
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/SendConversationMessagePayload'
            - $ref: '#/components/schemas/SendConversationMessageWithExternalProviderPayload'
          examples:
            conversationMessage:
              value:
                authorType: user
                text: What would you like to do next?
                attachments: []
                cards:
                - contentType: application/8x8.quick.replies
                  content:
                    options:
                    - title: option one
                      data:
                        postback: '1'
                    - title: second option
                      data:
                        postback: '2'
                - contentType: application/vnd.microsoft.card.adaptive
                  content:
                    type: AdaptiveCard
                    body:
                    - type: TextBlock
                      size: Medium
                      weight: Bolder
                      text: Example
                    $schema: http://adaptivecards.io/schemas/adaptive-card.json
                    version: '1.3'
            conversationMessageWithExternalProviderPayload:
              value:
                authorType: user
                externalProvider:
                  name: X
                  externalMessageId: '1234567890123456789'
  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.
    ConversationParticipant:
      type: object
      properties:
        id:
          type: string
          format: string
          description: Participant identifier. (agentId, user, bot)
        removed:
          type: boolean
          description: States if the participant is still part of the conversation or if he vas removed.
        type:
          $ref: '#/components/schemas/AuthorType'
        language:
          $ref: '#/components/schemas/Language'
    AdaptiveCards:
      type: object
      properties:
        id:
          type: string
          format: string
          description: Adaptive card identifier.
        contentType:
          $ref: '#/components/schemas/ContentType'
        content:
          type: object
          description: ' Any adaptive cards, up to version 1.6 https://adaptivecards.io/schemas/1.6.0/adaptive-card.json

            https://adaptivecards.io/explorer/ <br> Any 8x8 Quick Replies card. Any interactive card. Any location card. Any template card. '
        actionSubmitted:
          type: boolean
          description: Indicates if the card was submitted by the user.
        actionExecuted:
          type: boolean
          description: Indicates if the card was executed by the agent.
    ExternalProviderPayload:
      type: object
      required:
      - name
      - externalMessageId
      properties:
        name:
          type: string
          enum:
          - X
          description: External provider name. Currently only 'X' (X/Twitter) is supported.
          example: X
        externalMessageId:
          type: string
          description: External message ID from the provider (e.g., tweet ID for X/Twitter)
          example: '1234567890123456789'
      description: External provider information for message rehydration. Required when text is not provided. Both text and externalProvider cannot be provided at the same time.
    SendConversationMessagePayload:
      allOf:
      - type: object
        required:
        - authorType
        properties:
          authorType:
            $ref: '#/components/schemas/ExternalAuthorType'
          text:
            type: string
            format: string
            example: Hello!
            description: Text content for direct messages
            required:
            - text
            additionalProperties: false
      - $ref: '#/components/schemas/Attachments'
      - $ref: '#/components/schemas/Cards'
    MessageResult:
      allOf:
      - type: object
        required:
        - id
        - text
        - author
        properties:
          id:
            type: string
            format: string
            description: ID of the message
          text:
            type: string
            format: string
            description: The message written by the sender.
            example: Hello!
          createdAt:
            type: string
            format: date-time
            description: Creation date and time - iso8601
            example: '2021-01-30T08:30:00Z'
          author:
            allOf:
            - $ref: '#/components/schemas/ConversationParticipant'
          externalProvider:
            $ref: '#/components/schemas/ExternalProviderPayload'
            description: External provider information if the message was rehydrated from an external service (e.g., X/Twitter)
      - $ref: '#/components/schemas/Attachments'
      - $ref: '#/components/schemas/Cards'
    BadRequestProblem:
      type: object
      properties:
        message:
          type: string
          example: Invalid authorType=ghfgh, has to be one of user, bot, agent
        errors:
          type: object
          properties:
            code:
              type: string
              example: invalid_json_object
            message:
              type: string
              example: Invalid authorType=ghfgh, has to be one of user, bot, agent
        referenceId:
          type: string
          example: 98e9da1f69f06d9019353ec66da6063a
    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
    MessageListResult:
      allOf:
      - type: object
        required:
        - messages
        properties:
          _embedded:
            type: object
            properties:
              messages:
                type: array
                items:
                  $ref: '#/components/schemas/MessageResult'
      - $ref: '#/components/schemas/PageResult'
    AuthorType:
      allOf:
      - $ref: '#/components/schemas/ExternalAuthorType'
      - type: string
        x-extensible-enum:
        - system
        - agent
    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>>.
    ContentType:
      type: string
      enum:
      - application/vnd.microsoft.card.adaptive
      - application/8x8.quick.replies
      - Interactive
      - Location
      - Template
      - Suggestions
      - Buttons
      - Carousel
      default: application/vnd.microsoft.card.adaptive
      description: Card content type.
    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
    Attachments:
      type: object
      properties:
        attachments:
          description: Id of an attachment uploaded using attachments path.
          type: array
          items:
            type: object
            properties:
              id:
                type: string
    SendConversationMessageWithExternalProviderPayload:
      allOf:
      - type: object
        required:
        - authorType
        properties:
          authorType:
            $ref: '#/components/schemas/ExternalAuthorType'
        allOf:
        - properties:
            externalProvider:
              $ref: '#/components/schemas/ExternalProviderPayload'
          required:
          - externalProvider
          additionalProperties: false
      - $ref: '#/components/schemas/Attachments'
      - $ref: '#/components/schemas/Cards'
    Language:
      type: string
      format: string
      default: en
      description: 'The language of the user. Based on this property the user is assigned to an agent who speaks their language.


        The default value is English (`en`).


        The sender language can be one of the following:

        * `en` => English

        * `ru` => Русский

        * `de` => Deutsch

        * `ja` => 日本語

        * `es` => Español

        * `fr` => Français

        * `pt` => Português

        * `it` => Italiano

        * `pl` => Polski

        * `hr` => Hrvatski

        * `nl` => Dutch

        * `ar` => العرية

        * `da` => Dansk

        * `ko` => 한국

        * `no` => Norsk

        * `sv` => Svenska

        * `vi` => Tiếng Việt

        * `cy` => Cymraeg

        * `th` => ไทย

        * `zh-CN` => 简体中文

        * `zh-TW` => 中國傳統'
    Cards:
      type: object
      properties:
        cards:
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/AdaptiveCards'
  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
    SortByDateOptional:
      name: sort
      in: query
      required: false
      description: Attribute on which sorting direction is applied available only for createdDate field.
      schema:
        type: string
        default: createdAt:desc
        example: createdAt:asc
    ChatAPIConversationUrlID:
      name: conversationId
      in: path
      required: true
      description: Conversation identifier.
      schema:
        type: string
        format: string
        example: '125'
    MessageID:
      name: messageId
      in: path
      required: true
      description: Message identifier.
      schema:
        type: string
        format: string
        example: msg01
    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'
    BadRequestResponse:
      description: Contains a descriptive response.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BadRequestProblem'
    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'
  securitySchemes:
    8x8ApiKey:
      type: apiKey
      name: x-api-key
      in: header
x-readme:
  explorer-enabled: true
  proxy-enabled: false
  samples-enabled: true