openapi: 3.0.2
x-explorer-enabled: false
x-samples-languages: ['curl', 'node', 'java', 'javascript', 'python', 'go']
info:
  title: AXP Client SDK
  description: >
    The AXP SDK enables Front End Client applications with the Messaging, 
    WebRTC Voice, Video and Screen-sharing capabilities provided by 
    Avaya Experience Platform™.
  contact:
    name: Avaya API Team
    url: https://developers.avayacloud.com/onecloud-ccaas
    email: apiteam@avaya.com
  license:
    name: Avaya Software Development Kit (SDK) Software License Terms
    url: http://support.avaya.com/css/P8/documents/101038288
  version: 0.0.1
servers:
  - url: '{protocol}://{server}{basePath}'
    description: Open API
    variables:
      protocol:
        enum:
          - 'https'
        default: 'https'
      server:
        default: 'HOST-REGION.cc.avayacloud.com'
      basePath:
        default: "/sdk/omni/"
  - url: "{protocol}://{server}:{port}"
    description: Internal API
    variables:
      protocol:
        enum:
          - "http"
          - "https"
        default: "http"
      server:
        default: "sdk"
      port:
        enum:
          - "80"
          - "443"
        default: "80"
tags:
  - name: Endpoints
    description: Endpoints represents the device which needs to be registered for WebRTC capabilities
  - name: Engagements
    description: Engagements can be created from the customer side which are then handled by contact center resources like agents, supervisors and bots.
  
security:
  - {}
  - BearerAuth: []
paths:
  "/v1/webrtc-integrations/{integrationId}/endpoints":
    post:
      tags:
        - Endpoints
      summary: Create Endpoint Registration
      description: >
        Register the device as an endpoint for WebRTC capabilities
      operationId: registerEndpoint
      parameters:
        - $ref: "#/components/parameters/integrationId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateEndpoint"
            examples:
              "Register Endpoint":
                $ref: "#/components/examples/EndpointRequest"
        required: true
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Endpoint"
              examples:
                "Register Endpoint":
                  $ref: "#/components/examples/Endpoint"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalServerError"
  "/v1/webrtc-integrations/{integrationId}/endpoints/{endpointId}":
    delete:
      tags:
        - Endpoints
      summary: Delete Endpoint Registration
      description: >
        Delete endpoint registration
      operationId: unregisterEndpoint
      parameters:
        - $ref: "#/components/parameters/integrationId"
        - $ref: "#/components/parameters/endpointId"
      responses:
        "204":
          description: No Content
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalServerError"
  "/v1/webrtc-integrations/{integrationId}/engagements":
    post:
      tags:
        - Engagements
      summary: Create Engagement
      description: >
        Creates a new engagement.
      operationId: createEngagement
      parameters:
        - $ref: "#/components/parameters/integrationId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateEngagement"
            examples:
              "Start Engagement":
                $ref: "#/components/examples/CreateEngagement"
        required: true
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Engagement"
              examples:
                "Start Engagement":
                  $ref: "#/components/examples/Engagement"
        "400":
          $ref: "#/components/responses/BadRequestCreateEngagement"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
components:
  parameters:
    sessionId:
      name: sessionId
      description: "The unique 36 character internal id that represents the session."
      required: true
      in: path
      schema:
        type: string
        minLength: 36
        maxLength: 36
        pattern: '^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$'
        example: "fc741b00-710b-11eb-9439-0242ac130002"
    integrationId:
      name: integrationId
      description: "The unique 36 character id for this specific chat integration"
      required: true
      in: path
      schema:
        type: string
        minLength: 36
        maxLength: 36
        pattern: '^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$'
        example: "fc741b00-710b-11eb-9439-0242ac130002"
    conversationId:
      name: conversationId
      description: "The unique 36 character internal id that represents the conversation."
      required: true
      in: path
      schema:
        type: string
        minLength: 36
        maxLength: 36
        pattern: '^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$'
        example: "9d7cf5b8-70ad-11eb-9439-0242ac130005"
    engagementId:
      name: engagementId
      description: "The unique 36 character internal id that represents the engagement."
      required: true
      in: path
      schema:
        type: string
        minLength: 36
        maxLength: 36
        pattern: '^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$'
        example: "8d7cf5b8-70ad-11eb-9439-0242ac130002"
    dialogId:
      name: dialogId
      description: "The unique 36 character internal id that represents the dialog."
      required: true
      in: query
      schema:
        type: string
        minLength: 36
        maxLength: 36
        pattern: '^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$'
        example: "fc741b00-710b-11eb-9439-0242ac130002"
    endpointId:
      name: endpointId
      description: "The unique id that represents the endpoint."
      required: true
      in: path
      schema:
        type: string
        minLength: 3
        maxLength: 36
        example: "fc741b00-710b-11eb-9439-0242ac130002"
  responses:
    BadRequestCreateEngagement:
      description: Bad Request
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          examples:
            "Constraint Violation":
              $ref: "#/components/examples/ErrorConstraintViolation"
            "Max Engagements Limit Exceeded":               
              $ref: "#/components/examples/MaxEngagementsLimitExceeded"
    BadRequest:
      description: Bad Request
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          examples:
            default:
              $ref: "#/components/examples/ErrorConstraintViolation"
    Unauthorized:
      description: Unauthorized.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          examples:
            default:
              $ref: "#/components/examples/ErrorUnauthorized"
    Forbidden:
      description: Forbidden.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          examples:
            default:
              $ref: "#/components/examples/ErrorForbidden"
    NotFound:
      description: Not Found.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          examples:
            default:
              $ref: '#/components/examples/ErrorNotFound'
    InternalServerError:
      description: Internal Server Error
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          examples:
            default:
              $ref: "#/components/examples/ErrorInternalServerError"
    ServiceUnavailable:
      description: Service Unavailable
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          examples:
            default:
              $ref: "#/components/examples/ServiceUnavailable"
  schemas:
    CreateEndpoint:
      type: object
      required:
        - id
        - sessionId
      properties:
        id:
          type: string
          minLength: 3
          maxLength: 36
          description: "The unique id that represents the endpoint."
        sessionId:
          type: string
          minLength: 36
          maxLength: 36
          pattern: '^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$'
          description: "The unique 36 character internal id that represents the session."
        displayName:
          type: string
          maxLength: 70
          description: "The display name of the customer. Note, this field will be ignored if a customer name was already provided at the time of generating the JWT token."
          example: John Doe
    Endpoint:
      type: object
      required:
        - sessionId
        - endpointId
        - ttl
        - webSocketSessionId
        - webSocketSessionToken
      properties:
        sessionId:
          type: string
          minLength: 36
          maxLength: 36
          pattern: '^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$'
          description: "The unique 36 character internal id that represents the session."
        displayName:
          type: string
          maxLength: 70
          description: "The display name of the customer. Note, this field will be ignored if a customer name was already provided at the time of generating the JWT token."
          example: John Doe
        endpointId:
          type: string
          minLength: 3
          maxLength: 36
          readOnly: true
          description: "The unique id that represents the endpoint."
        ttl:
          type: integer
          readOnly: true
          description: "Time left in seconds after which the registration of the endpoint will expire."
        webSocketSessionId:
          type: string
          minLength: 36
          maxLength: 36
          pattern: '^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$'
          readOnly: true
          description: "The unique 36 character internal id that represents the websocket session."
        webSocketSessionToken:
          type: string
          minLength: 3
          maxLength: 256
          readOnly: true
          description: "The token for the websocket session."
    CreateEngagement:
      type: object
      required:
        - sessionId
        - clientType
        - endpointId
        - address
        - mediaPreferences
      properties:
        sessionId:
          type: string
          description: "The unique 36 character internal id that represents the session."
          minLength: 36
          maxLength: 36
          pattern: '^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$'
        clientType:
          type: string
          minLength: 2
          maxLength: 70
          example: web
          description: "The type of client making the request"
        endpointId:
          type: string
          minLength: 3
          maxLength: 36
          description: "The unique id that represents the endpoint."
        address:
          type: string
          minLength: 3
          maxLength: 256
          example: "+18005551234"
          description: "The address of the customer."
        engagementParameters:
          type: object
          maxProperties: 20
          description: "Optional key/value context information on the dialog. This information might be used to make business decisions on how the dialog is treated. For example, the client application might want to send hints about customer's interest based on the customer's searches or FAQ browsing. Key is limited to 64 characters"
          additionalProperties:
            type: string
            maxLength: 256
        isPriority:
          type: boolean
          description: "Indicates whether the engagement is a priority engagement."
        mediaPreferences:
          $ref: "#/components/schemas/MediaPreferences"
    MediaPreferences:
      type: object
      properties:
        enableVideo: 
          type: boolean
          description: "Indicates whether the engagement should be a video engagement."
        enableWebCollaboration:
          type: boolean
          description: "Indicates whether the engagement should be a web collaboration engagement."
        enableAudioNoiseReduction:
          type: boolean
          description: "Indicates whether the engagement should be a audio noise reduction engagement."
    Engagement:
      type: object
      description: The media specific element inside the engagement
      required:
        - engagementId
      properties:
        engagementId:
          type: string
          description: "The unique 36 character internal id that represents the engagement."
        conversationId:
          type: string
          description: "The unique 36 character internal id that represents the conversation."
        engagementParameters:
          type: object
          description: "Optional key/value context information on the dialog. This information might be used to make business decisions on how the dialog is treated. For example, the client application might want to send hints about customer's interest based on the customer's searches or FAQ browsing"
          additionalProperties:
            type: string
        dialogs:
          type: array
          items:
            $ref: "#/components/schemas/Dialog"
          description: "The list of active dialogs"
    Dialog:
      type: object
      description: The media specific element inside the dialog.
      required:
        - dialogId
        - dialogStatus
        - participants
        - createdAt
        - lastUpdatedAt
      properties:
        dialogId:
          type: string
          description: "The unique 36 character internal id that represents the dialog."
        dialogStatus:
          $ref: "#/components/schemas/DialogStatus"
        participants:
          type: array
          items:
            $ref: "#/components/schemas/Participant"
          description: List of participants
        createdAt:
          type: string
          format: date-time
          description: "The datetime when the dialog was created (in ISO 8601 format including timezone, 'yyyy-MM-dd'T'HH:mm:ss[.SSS]Z')"
        lastUpdatedAt:
          type: string
          format: date-time
          description: "The datetime when the dialog was last updated (in ISO 8601 format including timezone, 'yyyy-MM-dd'T'HH:mm:ss[.SSS]Z')"
    DialogStatus:
      type: string
      description: Status of the dialog.
      enum:
        - PENDING
        - ACTIVE
        - TERMINATING
        - TERMINATED
    Participant:
      type: object
      description: The association between a dialog and a participant
      required:
        - participantId
        - participantType
      properties:
        participantId:
          type: string
          description: "The id that represents the participant."
        participantType:
          $ref: "#/components/schemas/ParticipantType"
        displayName:
          type: string
          description: "The display name of the participant"

    ParticipantType:
      description: "The type of participant"
      type: string
      enum:
        - CUSTOMER
        - AGENT
        - SUPERVISOR
        - SYSTEM
        - BOT
    Problem:
      type: object
      description: |
        <b>Problem Detail</b> as a way to carry machine-readable details of errors in a HTTP response to avoid the need to define new error response formats for HTTP APIs <a href="https://tools.ietf.org/html/rfc7807">RFC 7807</a>
      properties:
        type:
          type: string
          format: uri
          description: |
            An absolute URI that identifies the problem type. When dereferenced, it SHOULD provide human-readable documentation for the problem type (e.g., using HTML).
          default: 'about:blank'
          example: 'https://developers.avayacloud.com/onecloud-ccaas/docs/error-handling#constraint-violation'
        title:
          type: string
          description: |
            A short, summary of the problem type. Written in english and readable for engineers (usually not suited for non technical stakeholders and not localized).
          example: Service Unavailable
          nullable: true
        status:
          type: integer
          format: int32
          description: |
            The HTTP status code generated by the origin server for this occurrence of the problem.
          minimum: 100
          maximum: 600
          exclusiveMaximum: true
          example: 503
          nullable: true
        detail:
          type: string
          description: |
            A human readable explanation specific to this occurrence of the problem.
          example: Connection to database timed out
          nullable: true
        instance:
          type: string
          format: uri
          description: |
            An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
          nullable: true
        violations:
          type: array
          description: |
            A list of violations that occurred as a result of invalid data provided as part of a request.
          nullable: true
          items:
            type: object
            properties:
              field:
                type: string
                description: |
                  The name of the field in the request that caused the violation. This can be the name of a path parameter, query parameter, or a field within the request body.
                example: accountId
              message:
                type: string
                description: |
                  A human readable explanation specific to this occurrence of the violation.
                example: "must match \"^[a-zA-Z]{6}$\""
              code:
                type: integer
                format: int32
                description: |
                  The violation code generated by the server for this occurrence of the violation. Use this code when implementing any error handling logic instead of the message, as the message can change.
                example: 20006
          example:
            - field: emailAddress
              message: "must not be null"
              code: 20002
            - field: accountId
              message: "must match \"^[a-zA-Z]{6}$\""
              code: 20006
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: This API uses Bearer Token Authorization Flow
      bearerFormat: JWT
  examples:
    EndpointRequest:
      value:
        id: 64C0C4FC-74CE-42C4-94CF-6A5838393A00
        sessionId: fc741b00-710b-11eb-9439-0242ac130002
        ttl: 7200
        displayName: John Doe
    Endpoint:
      value:
        endpointId: 64C0C4FC-74CE-42C4-94CF-6A5838393A00
        displayName: John Doe
        sessionId: fc741b00-710b-11eb-9439-0242ac130002
        webSocketSessionId: 4dc53692-e25c-4e8c-a780-0b2f05008478
        webSocketSessionToken: 4dc53692-e25c-4e8c-a780-0b2f05008478
        ttl: 7200
    CreateEngagement:
      value:
        sessionId: fc741b00-710b-11eb-9439-0242ac130002
        endpointId: 64C0C4FC-74CE-42C4-94CF-6A5838393A00
        clientType: web
        address: "+18005551234"
        engagementParameters:
          model: 512GTB
          interestedModel: 488GTB
        mediaPreferences:
          enableVideo: false
          enableWebCollaboration: false
          enableAudioNoiseReduction: true
    Engagement:
      value:
        engagementId: 133fbaab-de2f-4927-b76a-5d379ef340f3
        engagementParameters:
          model: 512GTB
          interestedModel: 488GTB
        dialogs:
          - dialogId: 40374765-2b39-4b11-98b1-79545337dd30
            dialogStatus: ACTIVE
            participants:
              - participantId: 4dc53692-e25c-4e8c-a780-0b2f05008478
                participantType: CUSTOMER
                displayName: John Doe
              - participantId: e3c8400d-c44f-4451-8316-e75c4efb8cc7
                participantType: AGENT
                displayName: Scott Adams
            createdAt: "2021-11-13T20:25:39.534Z"
            lastUpdatedAt: "2021-11-13T20:25:39.734Z"

    ErrorConstraintViolation:
      description: Constraint Violation
      value:
        type: "https://developers.avayacloud.com/onecloud-ccaas/docs/error-handling#constraint-violation"
        title: "Constraint Violation"
        status: 400
        detail: "A problem that indicates a syntactically correct, yet semantically illegal request. The Server can not process this request until the client resolves the semantic errors described in the violations section."
        violations:
          - field: integrationId
            message: "must match \"^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{12}$\""
            code: 20006
    MaxEngagementsLimitExceeded:
      description: Constraint Violation
      value:
        type: "https://developers.avayacloud.com/onecloud-ccaas/docs/error-handling#constraint-violation"
        title: "Constraint Violation"
        status: 400
        detail: "A problem that indicates a max limit set for no of engagements per user has exceeded. The Server can not process this request until existing engagement(s) are terminated."
        violations:
          - message: "Maximum number of engagements allowed for an user has exceeded"
    ErrorUnauthorized:
      description: Unauthorized
      value:
        type: "https://developers.avayacloud.com/onecloud-ccaas/docs/error-handling#unauthorized"
        title: "Unauthorized"
        status: 401
        detail: "This operation requires authentication. See https://developers.avayacloud.com/onecloud-ccaas/docs/how-to-authenticate-with-ccaas-apis"
    ErrorForbidden:
      description: Forbidden
      value:
        type: "https://developers.avayacloud.com/onecloud-ccaas/docs/error-handling#forbidden"
        title: "Forbidden"
        status: 403
        detail: "According to the access control policy the current user and/or integrationId does not have permission to access this resource."
    ErrorNotFound:
      description: Not Found
      value:
        type: "https://developers.avayacloud.com/onecloud-ccaas/docs/error-handling#not-found"
        title: "Not Found"
        status: 404
        detail: "Either there is no API method associated with the URL path of the request, or the request refers to one or more resources that were not found."
    ErrorInternalServerError:
      description: Server Error
      value:
        type: "https://developers.avayacloud.com/onecloud-ccaas/docs/error-handling#server-error"
        title: "Server Error"
        status: 500
        detail: "An internal server error was encountered."
    ServiceUnavailable:
      description: Service Unavailable
      value:
        type: "https://developers.avayacloud.com/onecloud-ccaas/docs/error-handling#service-unavailable"
        title: "Service Unavailable"
        status: 503