8x8 Interactions API

openapi: 3.2.0
info:
  version: 1.0.21
  title: Quality Management and Speech Analytics Interactions API
  contact:
    name: QM/SA Team
    email: qm-team@8x8.com
  termsOfService: https://www.8x8.com/terms-and-conditions
  description: 'The Quality Management and Speech Analytics (QMSA) API enables you to access raw resources such as interaction metadata, evaluation results, and users.

    ## **Authentication**

    You can try out this API through request authentication using your client credentials. Refer to [Client Credentials](/analytics/docs/how-to-get-api-keys) on the [Getting Started](/tech-partner/docs/getting-started) page for more information.

    All requests must be made over HTTPS - calls made over HTTP will fail.

    ## **Regions**

    The API resources are available distinctly for each geographical region in which the customer is located or provisioned. The base URLs for regions are as follows:

    <table> <tr> <td><b>URL</b></td> <td><b>Region</b></td> </tr> <tr> <td><b><a href=''https://api.8x8.com/qm/us-west/v1''>https://api.8x8.com/qm/us-west/v1</a></b></td><td>Western US</td></tr><tr> <td><b><a href=''https://api.8x8.com/qm/us-east/v1''>https://api.8x8.com/qm/us-east/v1</a></b></td><td>Eastern US</td></tr><tr> <td><b><a href=''https://api.8x8.com/qm/uk/v1''>https://api.8x8.com/qm/uk/v1</a></b></td><td>United Kingdom</td></tr><tr> <td><b><a href=''https://api.8x8.com/qm/ap/v1''>https://api.8x8.com/qm/ap/v1</a></b></td><td>Australia</td> </tr> <tr> <td><b><a href=''https://api.8x8.com/qm/ca/v1''>https://api.8x8.com/qm/ca/v1</a></b></td><td>Canada</td> </tr> </table>


    ## **Headers**

    With every API call, the header should contain the **`pbx`** name from which the data is to be derived.

    The header key is **`pbx`**.

    ## **Resource IDs**

    The QMSA API uses short non-sequential unique **`ids`**. Every resource **`id`** **must** consist of URL friendly characters such as:

    * Uppercase or lowercase letters of the alphabet (**`A-Z`** or **`a-z`**)

    * Numbers (**`0-9`**)

    * Underscores (**`_`**) or hyphens (**`-`**)

    The QMSA API uses the following resoruce **`ids`**:

    * **`userReference`** (e.g., `283`) - The unique identifier of the system registered user.


    * **`interactionGuid`** (e.g.,`int-15bd0b19d21-KKx2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample`) - The interaction object''s globally unique identifier for a single interaction.

    * **`customField`** (e.g., `customField1`) - One of 25 custom field identifiers.

    * **`evaluationId`** (e.g., `45`) - The unique identifier for a system evaluation.

    ## **Representation of Date and Time**

    All exchange of date and time-related data **must** be completed according to the ISO 8601 standard and stored in UTC. When returning date and time-related data **`YYYY-MM-DDThh:mm:ss`** format **must** be used.


    ## **Payload Media Type**

    Where applicable the QMSA API requires the use pf the JSON media-type. Requests that contain a message-body use plain JSON to set or update resource states. `Content-type: application/json` and `Accept: application/json` headers **must** be set on all requests if not stated otherwise.


    ## **Ordering**

    By default, all resources returned in collections are ordered by their creation time in ascending order.

    ## **Pagination**

    The QMSA API uses URI query pagination to retrieve resource collections. When a resource collection is obtained, the method used to obtain the total count of the type resourced is also returned. The pages **must** be zero (0) based, and the page size **must** be a value between 1 and 100. The default value is 100. The answer can contain links to the either the **`nextPage`** or **`previousPage`**.

    ## **HATEOAS**

    The QMSA API uses the Spring HATEOAS model for retrieving links to related resources within responses.

    ## **Filtering**

    The QMSA API is designed with limited filtering capiblities. The filtering that is available in each method is possible only for important key/value pairs. More information on what is avaiable for filtering can be found with each method description.

    ## **Error response**

    The QMSA API returns both machine-readable error codes and human-readable error messages in the response body when an error occurs.

    ## **Versioning**

    This API uses URI versioning. Subsequent versions may introduce breaking changes.

    ## **Example**

    Second version of method: `https://api.8x8.com/qm/us-west/V2/method`'
servers:
- url: https://api.8x8.com/qm/{region}/{apiversion}
  description: The QM/SA API Gateway Endpoint
  variables:
    region:
      enum:
      - us-west
      - us-east
      - uk
      - ap
      - ca
      default: us-west
    apiversion:
      default: v1
security:
- bearerAuth: []
tags:
- name: Interactions
paths:
  /interactions/count:
    get:
      tags:
      - Interactions
      summary: Interaction count.
      description: This method retrieves the interactions count for the specified interaction type. Unless the interaction type is specified, all the interaction types are retrieved.
      operationId: interactions count
      parameters:
      - name: interactionType
        in: query
        description: Interaction type.
        required: false
        style: form
        explode: true
        schema:
          $ref: '#/components/schemas/interactionType'
      - name: Content-Type
        in: header
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: application/json
      - name: startTS
        in: query
        description: The UTC time to begin the query with.
        required: false
        style: form
        explode: true
        schema:
          type: string
          example: '2018-03-02 06:14:53'
      - name: endTS
        in: query
        description: The UTC time to end the query with.
        required: false
        style: form
        explode: true
        schema:
          type: string
          example: '2018-03-02 06:14:53'
      - name: userReference
        in: query
        description: The user's unique identification for interactions counts.
        required: false
        style: form
        explode: true
        schema:
          type: number
          format: double
          example: 283
      - name: customField
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: customFieldValue
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: string
          example: data
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
                example: 34
        default:
          description: Unexpected error
      deprecated: false
  /interactions:
    get:
      tags:
      - Interactions
      summary: The Interaction collection
      description: This method retrieves interaction collections.
      operationId: interactions
      parameters:
      - name: Content-Type
        in: header
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: application/json
      - name: startTS
        in: query
        description: The UTC time to begin the query with.
        required: false
        style: form
        explode: true
        schema:
          type: string
          example: '2018-03-02 06:14:53'
      - name: endTS
        in: query
        description: The UTC time to end the query with.
        required: false
        style: form
        explode: true
        schema:
          type: string
          example: '2018-03-02 09:14:53'
      - name: page
        in: query
        description: The page to start the query with.
        required: false
        style: form
        explode: true
        schema:
          type: number
          format: double
          example: 1
      - name: size
        in: query
        description: The page size to begin query with.
        required: false
        style: form
        explode: true
        schema:
          type: number
          format: double
          example: 30
      - name: interactionGuid
        in: query
        description: The unique identifier of the interaction object which uniquely identifies a record. Separate up to **10** **`guids`** using a comma.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: userReference
        in: query
        description: The unique identifier for the requested user interactions.
        required: false
        style: form
        explode: true
        schema:
          type: number
          format: double
          example: 283
      - name: customField
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: customFieldValue
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: string
          example: data
      - name: interactionType
        in: query
        description: The interaction type.
        required: false
        style: form
        explode: true
        schema:
          $ref: '#/components/schemas/interactionType'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/interactionDetailsResponse'
              example:
                pageNumber: 1
                pageSize: 100
                pageResultSize: 1
                content:
                - createdAt: '2018-03-02T07:14:53'
                  interactionGuid: int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample
                  agent:
                    userReference: 283
                    agentId: agent123
                    name: John Doe
                    mainGroup: Agent
                    supervisorName: David Smith
                    trainerName: Ian Smith
                  telephony:
                    direction: inbound
                    callerPhoneNumber: 4085551212
                    callerName: Joe Customer
                    dialedPhoneNumber: 1541549643
                    vccTransactionId: 12345
                    transferredFrom: ag32049403
                    transferredTo: ag52049403
                    holdDuration: 34
                    status: completed
                  media:
                    interactionType: voiceInteraction
                    interactionDuration: 435
                    videoSize: 4566
                    audioSize: 523
                  customFields:
                    customField:
                      value: field value
                      displayName: field custom name
                    customField1:
                      value: field value
                      displayName: field custom name
                    customField2:
                      value: field value
                      displayName: field custom name
                    customField3:
                      value: field value
                      displayName: field custom name
                    customField4:
                      value: field value
                      displayName: field custom name
                    customField5:
                      value: field value
                      displayName: field custom name
                    customField6:
                      value: field value
                      displayName: field custom name
                    customField7:
                      value: field value
                      displayName: field custom name
                    customField8:
                      value: field value
                      displayName: field custom name
                    customField9:
                      value: field value
                      displayName: field custom name
                    customField10:
                      value: field value
                      displayName: field custom name
                    customField11:
                      value: field value
                      displayName: field custom name
                    customField12:
                      value: field value
                      displayName: field custom name
                    customField13:
                      value: field value
                      displayName: field custom name
                    customField14:
                      value: field value
                      displayName: field custom name
                    customField15:
                      value: field value
                      displayName: field custom name
                    customField16:
                      value: field value
                      displayName: field custom name
                    customField17:
                      value: field value
                      displayName: field custom name
                    customField18:
                      value: field value
                      displayName: field custom name
                    customField19:
                      value: field value
                      displayName: field custom name
                    customField20:
                      value: field value
                      displayName: field custom name
                    customField21:
                      value: field value
                      displayName: field custom name
                    customField22:
                      value: field value
                      displayName: field custom name
                    customField23:
                      value: field value
                      displayName: field custom name
                    customField24:
                      value: field value
                      displayName: field custom name
                    customField25:
                      value: field value
                      displayName: field custom name
                  speechAnalysis:
                    overallEmotion: Positive
                    overtalk: 7.5
                    clarity: 90
                  links:
                  - rel: notes
                    href: https://api.8x8.com/qm/us-west/v1/interactions/int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample/notes
                    type: GET
                  - rel: labels
                    href: https://api.8x8.com/qm/us-west/v1/interactions/int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample/labels
                    type: GET
                  - rel: transcriptions
                    href: https://api.8x8.com/qm/us-west/v1/interactions/int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample/transcriptions
                    type: GET
                  - rel: media
                    href: https://api.8x8.com/qm/us-west/v1/interactions/int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample/media
                    type: GET
                links:
                - rel: nextUrl
                  href: https://api.8x8.com/qm/us-west/v1/interactions?page=2&size=100
                  type: GET
                - rel: prevUrl
                  href: https://api.8x8.com/qm/us-west/v1/interactions?page=1&size=100
                  type: GET
        default:
          description: Unexpected error
      deprecated: false
  /interactions/{interactionGuid}:
    delete:
      tags:
      - Interactions
      summary: Deletes a single interaction.
      description: Removes the interaction and all associated metadata. This action cannot be undone.
      operationId: delete interaction
      parameters:
      - name: interactionGuid
        in: path
        description: The interaction unique identifier.
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample
      responses:
        '200':
          description: OK
        default:
          description: Unexpected error
      deprecated: false
  /interactions/{interactionGuid}/purge:
    delete:
      tags:
      - Interactions
      summary: This method purges a single interaction.
      description: 'Removes the interaction and all associated metadata.  **This action cannot be undone.**

        '
      operationId: purge interaction
      parameters:
      - name: interactionGuid
        in: path
        description: The interaction unique identifier.
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample
      responses:
        '200':
          description: OK
        default:
          description: Unexpected error
      deprecated: false
  /interactions/{interactionGuid}/{customFieldNo}:
    put:
      tags:
      - Interactions
      summary: This method updates custom fields.
      description: This method either updates or removes the custom field contained data for user customizable fields. Only custom fields **1** to **15** can be edited.
      operationId: update custom field
      parameters:
      - name: interactionGuid
        in: path
        description: The interaction unique identifier
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample
      - name: customFieldNo
        in: path
        description: The custom field identifier
        required: true
        style: simple
        explode: false
        schema:
          $ref: '#/components/schemas/customFieldNo'
      - name: Content-Type
        in: header
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: application/json
      requestBody:
        content:
          text/plain:
            schema:
              type: string
              example: custom field text
            example: custom field text
        required: true
      responses:
        '200':
          description: OK
        default:
          description: Unexpected error
      deprecated: false
    delete:
      tags:
      - Interactions
      summary: Deletes custom field data
      description: Updates or removes the custom field contained data for user customizable fields. Only the custom fields **1** to **15** are editable.
      operationId: deletes the custom field
      parameters:
      - name: interactionGuid
        in: path
        description: The interaction unique identifier
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample
      - name: customFieldNo
        in: path
        description: The custom field identifier
        required: true
        style: simple
        explode: false
        schema:
          $ref: '#/components/schemas/customFieldNo'
      - name: Content-Type
        in: header
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: application/json
      responses:
        '200':
          description: OK
        default:
          description: Unexpected error
      deprecated: false
  /interactions/{interactionGuid}/transcriptions:
    get:
      tags:
      - Interactions
      summary: This method queries a single interaction transcription record.
      description: Retrieves available transcriptions for the selected interaction
      operationId: interaction transcription
      parameters:
      - name: interactionGuid
        in: path
        description: The interaction unique identifier
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample
      - name: Content-Type
        in: header
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                description: Transcription value respone
                items:
                  $ref: '#/components/schemas/transcriptionValueResponse'
              example:
              - text: Good morning.
                confidence: 100
                channel: 1
                emotion: Positive
                gender: male
                timestampStart: 10
                timestampEnd: 11
        default:
          description: Unexpected error
      deprecated: false
  /interactions/{interactionGuid}/topics:
    get:
      tags:
      - Interactions
      summary: Queries a single interaction for matched topics
      description: Retrieves the list of detected topics within the transcriptions
      operationId: topics
      parameters:
      - name: interactionGuid
        in: path
        description: The interaction unique identifier
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample
      - name: Content-Type
        in: header
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/topic'
              example:
              - channel: 0
                topic: Agent Sales Enablers
                category: Sales
        default:
          description: Unexpected error
      deprecated: false
  /interactions/{interactionGuid}/labels:
    get:
      tags:
      - Interactions
      summary: Query a single interaction attached label
      description: Retrieves the collection of labels attached to the interaction
      operationId: labels
      parameters:
      - name: interactionGuid
        in: path
        description: The interaction unique identifier
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample
      - name: Content-Type
        in: header
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/labelValue'
              example:
              - text: read this
                createdAt: '2018-03-02T06:14:53'
                updatedAt `2018-03-02T06:14:53`: ''
                links:
                - rel: creator
                  href: https://api.8x8.com/qm/us-west/v1/users/854
                  type: GET
                - rel: updater
                  href: https://api.8x8.com/qm/us-west/v1/users/854
                  type: GET
        default:
          description: Unexpected error
      deprecated: false
  /interactions/{interactionGuid}/notes:
    get:
      tags:
      - Interactions
      summary: Query the attached notes for a single interaction
      description: Retrieve the notes attached to an interaction
      operationId: notes
      parameters:
      - name: interactionGuid
        in: path
        description: The interaction unique identifier
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample
      - name: Content-Type
        in: header
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/noteValue'
              example:
              - text: read this
                interactionTimestamp: 10
                createdAt: '2018-03-02T06:14:53'
                updatedAt `2018-03-02T06:14:53`: ''
                links:
                - rel: creator
                  href: https://api.8x8.com/qm/us-west/v1/users/854
                  type: GET
        default:
          description: Unexpected error
      deprecated: false
  /interactions/{interactionGuid}/media:
    get:
      tags:
      - Interactions
      summary: The requested interaction media file download
      description: 'Retrieves audio, video, mixed audio (MP3), and video (MP4)

        Transcoding (bit rate, sample rate and channel) options are available for audio files'
      operationId: interaction media file
      parameters:
      - name: interactionGuid
        in: path
        description: The interaction unique identifier
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample
      - name: Content-Type
        in: header
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: application/json
      - name: bitRate
        in: query
        description: 'The bitrate (kbps)

          |Possible values|

          |:-|

          | `8`,`16`,`24`,`32`,`40`,`48`,`56`,`64`,`80`,`96`,`112`,`128`,`144`,`160`|'
        required: false
        style: form
        explode: true
        schema:
          type: number
          format: double
          example: 48
      - name: sampleRate
        in: query
        description: 'Sample Rates, in Hz.


          |Possible values|

          |:-|

          |`22050`, `24000`, `16000`|'
        required: false
        style: form
        explode: true
        schema:
          type: number
          format: double
          example: 24000
      - name: stereoEnabled
        in: query
        description: If false, the file is a mono, single channel file. If true, the file is in stereo format.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          example: true
      responses:
        '200':
          description: OK
        default:
          description: Unexpected error
      deprecated: false
  /interactions/redirect:
    get:
      tags:
      - Interactions
      summary: Webpage redirect
      description: Advanced customers can use this method to integrate systems. 8x8 recommends contacting your account representative for more details.
      operationId: webpage redirect
      parameters:
      - name: interactionGuid
        in: query
        description: The interaction unique identifier
        required: true
        style: form
        explode: true
        schema:
          type: string
          example: int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample
      responses:
        '200':
          description: OK
        default:
          description: Unexpected error
      deprecated: false
components:
  schemas:
    interactionContent:
      description: The interaction object model
      title: Interaction Content
      type: object
      properties:
        createdAt:
          type: string
          description: The datetime when the interaction began
          example: '2018-03-02T07:14:53'
        interactionGuid:
          type: string
          description: The interaction unique identifier
          example: int-15bd0b19d21-KK2fSQPPTD3DRpOS8UfhmgALh-phone-03-sample
        agent:
          $ref: '#/components/schemas/interactionAgent'
        telephony:
          $ref: '#/components/schemas/telephonyDetails'
        media:
          $ref: '#/components/schemas/media'
        customFields:
          $ref: '#/components/schemas/customFieldMap'
        speechAnalysis:
          $ref: '#/components/schemas/speechDetails'
        links:
          type: array
          items:
            $ref: '#/components/schemas/notesLink'
    customFieldMap:
      description: The list of custom fields attached to an interaction object.
      title: customFieldMap
      type: object
      properties:
        customField:
          $ref: '#/components/schemas/customFields'
        customField1:
          $ref: '#/components/schemas/customFields'
        customField2:
          $ref: '#/components/schemas/customFields'
        customField3:
          $ref: '#/components/schemas/customFields'
        customField4:
          $ref: '#/components/schemas/customFields'
        customField5:
          $ref: '#/components/schemas/customFields'
        customField6:
          $ref: '#/components/schemas/customFields'
        customField7:
          $ref: '#/components/schemas/customFields'
        customField8:
          $ref: '#/components/schemas/customFields'
        customField9:
          $ref: '#/components/schemas/customFields'
        customField10:
          $ref: '#/components/schemas/customFields'
        customField11:
          $ref: '#/components/schemas/customFields'
        customField12:
          $ref: '#/components/schemas/customFields'
        customField13:
          $ref: '#/components/schemas/customFields'
        customField14:
          $ref: '#/components/schemas/customFields'
        customField15:
          $ref: '#/components/schemas/customFields'
        customField16:
          $ref: '#/components/schemas/customFields'
        customField17:
          $ref: '#/components/schemas/customFields'
        customField18:
          $ref: '#/components/schemas/customFields'
        customField19:
          $ref: '#/components/schemas/customFields'
        customField20:
          $ref: '#/components/schemas/customFields'
        customField21:
          $ref: '#/components/schemas/customFields'
        customField22:
          $ref: '#/components/schemas/customFields'
        customField23:
          $ref: '#/components/schemas/customFields'
        customField24:
          $ref: '#/components/schemas/customFields'
        customField25:
          $ref: '#/components/schemas/customFields'
    creatorLink:
      description: The preformatted query URL for user details
      title: User Details Link
      type: object
      properties:
        rel:
          type: string
          description: Relation
          example: creator
        href:
          type: string
          description: The link to user details
          example: https://api.8x8.com/qm/us-west/v1/users/854
        type:
          type: string
          description: HTTP verb
          example: GET
    labelValue:
      description: The object model for a label description
      title: Label Values
      type: object
      properties:
        text:
          type: string
          description: Label text
          example: read this
        createdAt:
          type: string
          description: Label creation time.
        links:
          type: array
          items:
            $ref: '#/components/schemas/creatorLink'
      example:
        text: read this
        createdAt: '2018-03-02T06:14:53'
    customFields:
      description: The object model for custom field key-pairs
      title: customFields
      type: object
      properties:
        value:
          type: string
          description: The custom data that is delivered through integrations.
          example: field value
        displayName:
          type: string
          description: The display definition for this field
          example: field custom name
    interactionType:
      title: Interaction Types
      type: string
      example: voiceInteraction
      enum:
      - voiceInteraction
      - screenRecording
      - voiceScreen
      - other
    media:
      description: The object model for media size and duration.
      title: Media Information
      t

# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/8x8/refs/heads/main/openapi/8x8-interactions-api-openapi.yml