openapi: 3.0.1
info:
  title: Cuein answers conversations API
  description: API for Cuein Answers Service.
  termsOfService: http://swagger.io/terms/
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
- url: https://api.cuein.ai/answers/v1
tags:
- name: conversations
  description: APIs for retrieving customer-support interaction insights
paths:
  /conversations:
    get:
      tags:
      - conversations
      summary: Retrieve paginated conversation insights records based on date range as input
      operationId: Retrieve insights for multiple conversations
      parameters:
      - $ref: '#/components/parameters/timeframeFrom'
      - $ref: '#/components/parameters/timeframeTo'
      - $ref: '#/components/parameters/nextToken'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationBulkResponse'
        '400':
          description: Invalid Request Payload
          content: {}
        '401':
          description: Authentication Failure
          content: {}
        '500':
          description: Internal Cuein Error
          content: {}
      security:
      - ApiKeyAuth: []
    delete:
      tags:
      - conversations
      summary: Schedule deletion of conversation text (utterance text) from insight records based on source ids
      operationId: Schedule deletion of conversation text for multiple conversations
      parameters:
      - $ref: '#/components/parameters/sourceIds'
      responses:
        '200':
          description: successful operation
          content: {}
        '400':
          description: Invalid Request Payload
          content: {}
        '401':
          description: Authentication Failure
          content: {}
        '500':
          description: Internal Cuein Error
          content: {}
      security:
      - ApiKeyAuth: []
  /conversations/meta/lastProcessed:
    get:
      tags:
      - conversations
      summary: Retrieves the latest updated timestamp of conversation that has been processed and ready for access.
      operationId: Retrieve the latest processed conversation timestamp
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LastProcessedResponse'
        '400':
          description: Invalid Request Payload
          content: {}
        '401':
          description: Authentication Failure
          content: {}
        '500':
          description: Internal Cuein Error
          content: {}
      security:
      - ApiKeyAuth: []
  /conversations/{id}:
    get:
      tags:
      - conversations
      summary: Retrieve single conversation insights record by id
      operationId: Retrieve insights for a conversation
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConversationResponse'
        '400':
          description: Invalid Request Payload
          content: {}
        '401':
          description: Authentication Failure
          content: {}
        '500':
          description: Internal Cuein Error
          content: {}
      security:
      - ApiKeyAuth: []
components:
  schemas:
    AdditionalIdKeyValue:
      description: List of additional id key and values to identify conversations
      type: object
      properties:
        idKey:
          description: Name of a specific id/key
          type: string
          enum:
          - contactId
        value:
          description: Value for the id key
          type: string
    MetricResponse:
      description: AI driven annotations/score for conversations
      type: object
      properties:
        label:
          description: Name for a specific annotation/metric
          type: string
          enum:
          - deflection
          - inferredCSAT
          - effortScore
          - resolved
          - abandoned
          - frustration
          - confusion
          - nextSteps
          - transferEscalation
          - empathy
        value:
          description: AI generated  values for various metric values
          oneOf:
          - type: string
          - type: integer
          - type: number
          - type: boolean
    LastProcessedResponse:
      description: Provide info on last processed record by ETL/analysis process
      type: object
      properties:
        timestamp:
          description: Most recent processing timestamp by Cuein
          type: string
          format: date-time
        latestMessageTimestamp:
          description: Latest message timestamp of processed conversations
          type: string
          format: date-time
    ConversationResponse:
      description: Provides insights for a single conversation
      type: object
      properties:
        sourceId:
          description: unique customer dataset specific id (caseId/transcriptId)
          type: string
        summary:
          description: summary for the entire conversation
          type: string
        timestamp:
          description: Returns the timestamp of the last message in the conversation
          type: string
          format: date-time
        processedTimestamp:
          description: Returns processing timestamp by Cuein for the conversation
          type: string
          format: date-time
        additionalId:
          description: list of additional identifiers for the conversation
          type: array
          items:
            $ref: '#/components/schemas/AdditionalIdKeyValue'
        intents:
          description: list of contact reasons/user intents for which user is seeking support/assistance
          type: array
          items:
            $ref: '#/components/schemas/InsightResponse'
        rootCauses:
          description: list of root causes for the contact reasons/user intents
          type: array
          items:
            $ref: '#/components/schemas/InsightResponse'
        resolutions:
          description: list of resolutions provided by bot or agent for providing support/assistance
          type: array
          items:
            $ref: '#/components/schemas/InsightResponse'
        policies:
          description: list of policies associated with the session
          type: array
          items:
            $ref: '#/components/schemas/InsightResponse'
        metrics:
          description: AI driven annotations/metrics for the conversation session
          type: array
          items:
            $ref: '#/components/schemas/MetricResponse'
        botMetrics:
          description: AI driven annotations/metrics for the chatbot section of the conversation session, if any
          type: array
          items:
            $ref: '#/components/schemas/MetricResponse'
        agentMetrics:
          description: AI driven annotations/metrics for the agent section of the conversation session, if any
          type: array
          items:
            $ref: '#/components/schemas/MetricResponse'
        sourceMetadata:
          description: Selected key-value tags from original source metadata
          $ref: '#/components/schemas/SourceMetadata'
    InsightResponse:
      description: Provides generated summary, clustered category and label for intents/root causes/resolutions
      type: object
      properties:
        summary:
          description: short  description for the specific insight
          type: string
        utteranceIndex:
          description: index of the utterance in the conversation/case (starting from 1)
          type: integer
          format: int64
        messageId:
          description: optional reference to the message id in the conversation (if provided)
          type: string
        categories:
          description: one or more cluster categories the insight belongs to
          type: array
          items:
            $ref: '#/components/schemas/CategoryDetails'
        generatedLabel:
          description: a short label for the insight (for outlier insights not part of existing clusters)
          type: string
    SourceMetadata:
      description: Key-values tags from the original source metadata. The keys vary by dataset.
      type: object
      additionalProperties:
        type: string
    CategoryDetails:
      description: Clustered category name and score
      type: object
      required:
      - label
      properties:
        label:
          description: Cluster label the insight is part of
          type: string
        score:
          description: Cluster score between 0 & 1 for insight association with specific cluster label
          type: number
    ConversationBulkResponse:
      description: Response object for returning count and support interaction insights for time frame
      type: object
      properties:
        meta:
          description: data about returned results
          type: object
          properties:
            count:
              description: count of conversation insights records returned
              type: integer
              format: int64
            nextToken:
              description: token to be used for the next batch call (if not present, there are no more results)
              type: string
        conversations:
          description: list of conversation insights records
          type: array
          items:
            $ref: '#/components/schemas/ConversationResponse'
  parameters:
    timeframeFrom:
      name: timeframeFrom
      in: query
      description: Starting time frame value ('YYYY-MM-DD' or 'YYYY-MM-DD HH:mm:SS') for filtering conversation records on the processing timestamp by Cuein
      required: true
      schema:
        type: string
        format: date-time
    sourceIds:
      name: sourceIds
      in: query
      description: list of unique customer dataset specific id (caseId/transcriptId)
      schema:
        type: array
        items:
          type: string
    timeframeTo:
      name: timeframeTo
      in: query
      description: Ending time frame value ('YYYY-MM-DD' or 'YYYY-MM-DD HH:mm:SS') for filtering conversation records on the processing timestamp by Cuein
      required: true
      schema:
        type: string
        format: date-time
    nextToken:
      name: nextToken
      in: query
      description: Token to use for next batch lookup (empty returns the first batch of records)
      required: false
      schema:
        type: string
    id:
      name: id
      in: path
      description: unique customer dataset specific id (caseId/transcriptId)
      required: true
      schema:
        type: string
    limit:
      name: limit
      in: query
      description: Limit of results to return (default system limits exist)
      required: true
      schema:
        type: integer
        format: int64
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: x-api-key
      in: header
externalDocs:
  description: Find out more about Cuein
  url: https://cuein.ai
x-readme:
  explorer-enabled: true
  proxy-enabled: true