openapi: 3.0.0
info:
  title: Webex Admin Address Book Agent Summaries API
  version: 1.0.0
  description: The Webex Admin APIs provide comprehensive programmatic access to administrative functions for managing Webex organizations, users, licenses, and settings. These APIs enable automation of user provisioning, license assignment, compliance management, and audit event retrieval. Administrators can integrate with enterprise identity systems, enforce security policies, monitor usage, and streamline onboarding/offboarding processes. The APIs support granular control over organizational resources, making them ideal for large-scale deployments and custom admin tooling.
tags:
- name: Agent Summaries
paths:
  /generated-summaries/search:
    post:
      tags:
      - Agent Summaries
      summary: List summaries
      description: Lists summaries based on the requested search type.
      operationId: listSummaries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SummaryListRequest'
            examples:
              listByOrganization:
                summary: 'Case 1: List by organizationId'
                value:
                  searchType: ORGANIZATION
                  orgId: acc80d18-b1fb-4261-b44e-a46435eea1da
              listByInteraction:
                summary: 'Case 2: List by interactionId'
                value:
                  searchType: INTERACTION
                  orgId: acc80d18-b1fb-4261-b44e-a46435eea1da
                  interactionId: 9d2a7879-8957-4cd6-a39c-46d4f21eaea5
              listByAgentCiUserId:
                summary: 'Case 3: List by agentCiUserId'
                value:
                  searchType: AGENT
                  agentCiUserId: 77e70d79-64b1-402e-9b84-b113ad71b06d
                  orgId: acc80d18-b1fb-4261-b44e-a46435eea1da
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummaryListResponse'
              examples:
                listByOrganization:
                  summary: 'Case 1: List by organizationId'
                  value:
                    interactionId: null
                    orgId: acc80d18-b1fb-4261-b44e-a46435eea1da
                    searchType: ORGANIZATION
                    agentCiUserId: null
                    summaries:
                      POST_CALL:
                        acc80d18-b1fb-4261-b44e-a46435eea1da:1bf3bd99-633b-401a-a3d4-61157a446809:c47d7c08-0776-4e38-a6bb-751d933a0c5d:
                          initialContactReason: Broken tools appointment request
                          additionalContext: Customer mentioned they had previously tried to fix the tools themselves but were unsuccessful.
                          additionalContactReasons: Customer also asked about warranty coverage for the broken tools.
                          keyActionsTaken: Scheduled an appointment with Doctor Petrophe for the caller
                          nextSteps: Confirm appointment details via email and follow up on warranty inquiry.
                          chosenWrapUpCode: Appointment Scheduled
                          proposedWrapUpCodes:
                          - name: Appointment Scheduled
                          - name: Service Request
                      MID_CALL:
                        acc80d18-b1fb-4261-b44e-a46435eea1da:9d2a7879-8957-4cd6-a39c-46d4f21eaea5:c47d7c08-0776-4e38-a6bb-751d933a0c5d:
                          reasonForTransferOrConsult: The caller wants to purchase fifteen tickets for an upcoming match but the current agent needs to check with teammates for ticket availability, requiring a transfer to another agent who can assist with ticket sales.
                          additionalContext: The match will take place next weekend at 6 PM, and the caller is part of a group looking to buy a large number of tickets.
                          keyActionsTaken: Checked the match schedule\nInquired about the number of tickets needed\nInitiated a transfer to check ticket availability with teammates
                    queueId: null
                listByInteraction:
                  summary: 'Case 2: List by interactionId'
                  value:
                    interactionId: 9d2a7879-8957-4cd6-a39c-46d4f21eaea5
                    orgId: acc80d18-b1fb-4261-b44e-a46435eea1da
                    searchType: INTERACTION
                    agentCiUserId: null
                    summaries:
                      POST_CALL:
                        acc80d18-b1fb-4261-b44e-a46435eea1da:9d2a7879-8957-4cd6-a39c-46d4f21eaea5:c47d7c08-0776-4e38-a6bb-751d933a0c5d:
                          initialContactReason: The caller wants to buy tickets for a match.
                          additionalContext: The match is next weekend and the caller represents a group looking for tickets.
                          additionalContactReasons: The caller also inquired about group discount options.
                          keyActionsTaken: The agent checked ticket availability with teammates.\nThe agent engaged with the caller about their request.
                          nextSteps: Agent will confirm ticket availability for fifteen tickets and get back to the caller.
                          chosenWrapUpCode: Ticket Inquiry
                          proposedWrapUpCodes:
                          - name: Ticket Inquiry
                          - name: Group Booking
                      MID_CALL:
                        acc80d18-b1fb-4261-b44e-a46435eea1da:9d2a7879-8957-4cd6-a39c-46d4f21eaea5:c47d7c08-0776-4e38-a6bb-751d933a0c5d:
                          reasonForTransferOrConsult: The caller wants to purchase fifteen tickets for an upcoming match but the current agent needs to check with teammates for ticket availability, requiring a transfer to another agent who can assist with ticket sales.
                          additionalContext: The match will take place next weekend at 6 PM, and the caller is part of a group looking to buy a large number of tickets.
                          keyActionsTaken: Checked the match schedule\nInquired about the number of tickets needed\nInitiated a transfer to check ticket availability with teammates
                    queueId: null
                listByAgentCiUserId:
                  summary: 'Case 3: List by agentCiUserId'
                  value:
                    interactionId: null
                    orgId: acc80d18-b1fb-4261-b44e-a46435eea1da
                    searchType: AGENT
                    agentCiUserId: 77e70d79-64b1-402e-9b84-b113ad71b06d
                    summaries:
                      POST_CALL:
                        acc80d18-b1fb-4261-b44e-a46435eea1da:9d2a7879-8957-4cd6-a39c-46d4f21eaea5:77e70d79-64b1-402e-9b84-b113ad71b06d:
                          initialContactReason: Customer wants to buy tickets for an upcoming match.
                          additionalContext: Customer has a group of fifteen people and needs the tickets to be together.
                          additionalContactReasons: Customer asked about group seating arrangements.
                          keyActionsTaken: Checked availability of fifteen tickets for the match.\nConfirmed grouped discount for the tickets.\nProcessed the ticket purchase and confirmed ticket sending via email.
                          nextSteps: Send the tickets to the customer's email.
                          chosenWrapUpCode: Ticket Purchase
                          proposedWrapUpCodes:
                          - name: Ticket Purchase
                          - name: Group Booking
                    queueId: null
        '400':
          description: Validation Error
        '401':
          description: Unauthorized Operation
        '403':
          description: Forbidden Operation
        '429':
          description: Too many requests have been sent in a given amount of time and the request has been rate limited.
        '500':
          description: An Unexpected Error Occurred
components:
  schemas:
    SummaryListResponse:
      type: object
      properties:
        orgId:
          type: string
          description: The unique identifier of the organization to which the summarized interactions belong.
        agentCiUserId:
          type: string
          description: The CI (Common Identity) user ID of the agent associated with the summaries. Present when searchType is AGENT; otherwise null.
          nullable: true
        interactionId:
          type: string
          description: The unique identifier of a specific interaction. Present when searchType is INTERACTION; otherwise null.
          nullable: true
        queueId:
          type: string
          description: The queue ID (reserved for future use).
          nullable: true
        searchType:
          $ref: '#/components/schemas/SearchType'
        summaries:
          type: object
          description: Map of summaries keyed by feature type (POST_CALL, MID_CALL). Each feature maps summary identifiers to their summary fields.
          properties:
            POST_CALL:
              type: object
              description: Post-call summaries keyed by summary identifier.
              additionalProperties:
                $ref: '#/components/schemas/PostCallSummary'
            MID_CALL:
              type: object
              description: Mid-call summaries keyed by summary identifier.
              additionalProperties:
                $ref: '#/components/schemas/MidCallSummary'
      example:
        interactionId: null
        orgId: acc80d18-b1fb-4261-b44e-a46435eea1da
        searchType: ORGANIZATION
        agentCiUserId: null
        summaries:
          POST_CALL:
            acc80d18-b1fb-4261-b44e-a46435eea1da:1bf3bd99-633b-401a-a3d4-61157a446809:c47d7c08-0776-4e38-a6bb-751d933a0c5d:
              initialContactReason: Broken tools appointment request
              additionalContext: Customer mentioned they had previously tried to fix the tools themselves but were unsuccessful.
              additionalContactReasons: Customer also asked about warranty coverage for the broken tools.
              keyActionsTaken: Scheduled an appointment with Doctor Petrophe for the caller
              nextSteps: Confirm appointment details via email and follow up on warranty inquiry.
              chosenWrapUpCode: Appointment Scheduled
              proposedWrapUpCodes:
              - name: Appointment Scheduled
              - name: Service Request
          MID_CALL:
            acc80d18-b1fb-4261-b44e-a46435eea1da:9d2a7879-8957-4cd6-a39c-46d4f21eaea5:c47d7c08-0776-4e38-a6bb-751d933a0c5d:
              reasonForTransferOrConsult: The caller wants to purchase fifteen tickets for an upcoming match but the current agent needs to check with teammates for ticket availability, requiring a transfer to another agent who can assist with ticket sales.
              additionalContext: The match will take place next weekend at 6 PM, and the caller is part of a group looking to buy a large number of tickets.
              keyActionsTaken: Checked the match schedule\nInquired about the number of tickets needed\nInitiated a transfer to check ticket availability with teammates
        queueId: null
    SummaryListByInteractionRequest:
      type: object
      required:
      - orgId
      - interactionId
      - searchType
      properties:
        orgId:
          type: string
          description: The unique identifier of the organization to which the summarized interactions belong.
        interactionId:
          type: string
          description: The unique identifier of a specific interaction.
        searchType:
          type: string
          enum:
          - INTERACTION
          description: The type of search to be performed.
    ProposedWrapUpCode:
      type: object
      properties:
        name:
          type: string
          description: The name of the proposed wrap-up reason.
    SummaryListRequest:
      description: List summaries based on the given search type.
      oneOf:
      - $ref: '#/components/schemas/SummaryListByOrganizationRequest'
      - $ref: '#/components/schemas/SummaryListByInteractionRequest'
      - $ref: '#/components/schemas/SummaryListByAgentRequest'
    SummaryListByOrganizationRequest:
      type: object
      required:
      - orgId
      - searchType
      properties:
        orgId:
          type: string
          description: The unique identifier of the organization to which the summarized interactions belong.
        searchType:
          type: string
          enum:
          - ORGANIZATION
          description: The type of search to be performed.
    SearchType:
      type: string
      description: The type of search to be performed.
      enum:
      - ORGANIZATION
      - INTERACTION
      - AGENT
    SummaryListByAgentRequest:
      type: object
      required:
      - orgId
      - agentCiUserId
      - searchType
      properties:
        orgId:
          type: string
          description: The unique identifier of the organization to which the summarized interactions belong.
        agentCiUserId:
          type: string
          description: The CI (Common Identity) user ID of the agent associated with the summaries.
        searchType:
          type: string
          enum:
          - AGENT
          description: The type of search to be performed.
    PostCallSummary:
      type: object
      properties:
        initialContactReason:
          type: string
          description: The primary issue or request the customer contacted you about at the start of the interaction.
        additionalContext:
          type: string
          description: Relevant background details shared during the conversation that help explain the situation.
        additionalContactReasons:
          type: string
          description: Any new or secondary issues raised after the initial reason for contact.
        keyActionsTaken:
          type: string
          description: The main steps the agent took to investigate, resolve, or address the customer's request.
        nextSteps:
          type: string
          description: Clear follow-up actions and expected outcomes agreed upon before ending the interaction.
        chosenWrapUpCode:
          type: string
          description: The wrap-up reason code that was ultimately selected by the agent at the end of the interaction.
        proposedWrapUpCodes:
          type: array
          nullable: true
          description: A list of wrap-up reasons suggested by the AI based on the interaction content. Each object contains a name field. Can return null, 1, or 2 objects.
          items:
            $ref: '#/components/schemas/ProposedWrapUpCode'
    MidCallSummary:
      type: object
      properties:
        reasonForTransferOrConsult:
          type: string
          description: The specific reason the interaction is being transferred or consulted.
        additionalContext:
          type: string
          description: Important information already gathered that the next agent needs to continue smoothly.
        keyActionsTaken:
          type: string
          description: Steps completed so far in the interaction before the transfer or consult occurred.
  securitySchemes:
    oauth2:
      flows:
        authorizationCode:
          authorizationUrl: /
          scopes: {}
          tokenUrl: /
      type: oauth2
    bearer-key:
      type: http
      description: e.g. Bearer YOUR_AUTHORIZATION_TOKEN
      scheme: bearer
      bearerFormat: JWT
    bearerAuth:
      type: oauth2
      description: OAuth 2.0 Bearer token authentication
      flows:
        authorizationCode:
          authorizationUrl: https://webexapis.com/v1/authorize
          tokenUrl: https://webexapis.com/v1/access_token
          scopes:
            spark:applications_token: Create access tokens for Service Apps