Asapp3 Generative Agent API

openapi: 3.2.0
info:
  title: AutoCompose Generative Agent API
  description: 'Autocompose API to suggest the next agent message.

    Suggestions are based on the conversation history, conversation metadata, and

    the in-progress message text the agent has already typed into the composer.'
  version: 0.0.3
servers:
- url: https://api.sandbox.asapp.com
- url: https://api.test.asapp.com
tags:
- name: GenerativeAgent
  description: Operations to send messages and trigger GenerativeAgent to respond or query the current state
  x-displayName: GenerativeAgent
paths:
  /generativeagent/v1/analyze:
    post:
      tags:
      - GenerativeAgent
      summary: Analyze conversation
      description: 'Call this API to trigger GenerativeAgent to analyze and respond to a conversation.


        This API should be called after a customer sends a message while not speaking with a live agent. The Bot replies will not be returned on this request; they will be delivered asynchronously via the webhook callback.


        This API also adds an optional **message** field to create a message for a given conversation before triggering the bot replies. The message object is the exact same message used in the conversations API /message endpoint'
      operationId: postAnalyze
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: The parameters for triggering the analysis and response to a conversation
              properties:
                streamId:
                  type: string
                  description: The id associated with the connection where the responses should be sent to.
                  example: 97555020-0276-435f-8104-c378221ba292
                conversationId:
                  type: string
                  description: Internal conversation identifier from ASAPP
                  example: 01BX5ZZKBKACTAV9WEVGEMMVS0
                taskName:
                  type: string
                  description: Name of the task to be used in the analysis
                  example: UpgradePlan
                inputVariables:
                  type: object
                  description: Input variables to be used as context in the analysis.
                  example:
                    call_context: Customer called to upgrade their current plan to GOLD
                    customer_info:
                      current_plan: SILVER
                      customer_since: '2020-01-01'
                message:
                  $ref: '#/components/schemas/Message'
                channelType:
                  description: Channel type used by the current request (digital or voice)
                  type: string
                  enum:
                  - digital
                  - voice
                  example: digital
              required:
              - conversationId
              example:
                conversationId: 01BX5ZZKBKACTAV9WEVGEMMVS0
                message:
                  text: Hello, I would like to upgrade my internet plan to GOLD.
                  sender:
                    role: agent
                    externalId: 123
                  timestamp: '2021-11-23T12:13:14.555Z'
                taskName: UpgradePlan
                inputVariables:
                  context: Customer called to upgrade their current plan to GOLD
                  customer_info:
                    current_plan: SILVER
                    customer_since: '2020-01-01'
                channelType: digital
      responses:
        '200':
          description: Successfully triggered the bot to analyze and respond to a conversation
          content:
            application/json:
              schema:
                type: object
                description: Conversation identifier and message identifier if passed in the request
                properties:
                  conversationId:
                    type: string
                    description: Internal conversation identifier from ASAPP
                    example: 01BX5ZZKBKACTAV9WEVGEMMVS0
                  messageId:
                    type: string
                    description: Internal message identifier from ASAPP
                    example: 01BX5ZZKBKACTAV9WEVGEMMVS1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/RequestEntityTooLarge'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/DefaultError'
      security:
      - API-ID: []
        API-Secret: []
  /generativeagent/v1/streams:
    post:
      tags:
      - GenerativeAgent
      summary: Create stream URL
      description: 'This API creates a generative agent event streaming URL to start a streaming connection (SSE).


        This API should be called when the client boots-up to request a streaming_url, before it calls endpoints whose responses are delivered asynchronously (and most likely before calling any other endpoint).


        Provide the streamId to reconnect to a previous stream.'
      operationId: postStreams
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: The parameters to be associated with a given connection.
              properties:
                streamId:
                  type: string
                  description: streamId to be associated with the streaming connection. If not present, the llm-bot will provide one.
                  example: 97555020-0276-435f-8104-c378221ba292
              example:
                streamId: 97555020-0276-435f-8104-c378221ba292
      responses:
        '200':
          description: Successfully generated a new streaming URL.
          content:
            application/json:
              schema:
                type: object
                description: Streaming URL with its identifier and possible SSE message-types to be received.
                properties:
                  streamId:
                    type: string
                    description: If it was provided in the request, this field will just reaffirm the value. Otherwise, a newly generated one will be provided.
                    example: 97555020-0276-435f-8104-c378221ba292
                  streamingUrl:
                    type: string
                    description: URL for opening the SSE session. It may be used once, and is valid for only 30 seconds.
                    example: https://ws-co82129c.test.asapp.com/push-api/connect/sse\?token\=<token>
                  messageTypes:
                    type: array
                    items:
                      type: string
                    description: Possible message types to be received from the agent.
                    example:
                    - generative-agent-message
                required:
                - streamId
                - streamingUrl
                - messageTypes
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/DefaultError'
      security:
      - API-ID: []
        API-Secret: []
  /generativeagent/v1/state:
    get:
      tags:
      - GenerativeAgent
      summary: Get GenerativeAgent state
      description: This API provides the current state of the generative agent for a given conversation.
      operationId: getState
      parameters:
      - in: query
        name: criteria
        description: Search criteria
        style: form
        explode: true
        schema:
          type: object
          properties:
            externalId:
              type: string
              description: External conversation identifier from your external chat / voice system
          additionalProperties: false
          minProperties: 1
      responses:
        '200':
          description: Successfully fetched state of generative agent for a conversation
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: string
                    enum:
                    - ready
                    - processing
                    - waitingForConfirmation
                    - waitingForAuth
                    - transferredToAgent
                    - transferredToSystem
                    description: "The last status of the conversation:\n  * `ready` - GenerativeAgent is ready to respond to requests\n  * `processing` - GenerativeAgent is actively processing the conversation\n  * `waitingForConfirmation` - GenerativeAgent is expecting an explicit confirmation on the next message\n  * `waitingForAuth` - GenerativeAgent is waiting for the user to login before proceeding\n  * `transferredToAgent` - GenerativeAgent is no longer able to provide meaningful responses and has \n                           requested the conversation be transferred to a human agent\n  * `transferredToSystem` - GenerativeAgent has transferred control of this conversation back to the\n                            caller system. However, it will respond if new analyze requests are made\n"
                  lastGenerativeAgentMessageId:
                    type: string
                    description: ULID identifier of the last asynchronous response that was sent to the customer
                  currentTaskName:
                    type: string
                    description: Current task TaskBot is executing
                  inputVariables:
                    type: object
                    description: Last input variables
                example:
                  state: ready
                  lastGenerativeAgentMessageId: 01HWXSGMT91HCS18BV0CRGEKY8
                  currentTaskName: PaymentDetails
                  inputVariables:
                    input-context: Customer chatted in to check the details of their last payment.
                    last-customer-purchase: '2024-05-07'
      security:
      - API-ID: []
        API-Secret: []
components:
  schemas:
    ConflictResponse:
      description: Conflict response
      type: object
      properties:
        error:
          $ref: '#/components/schemas/DefaultErrorDetails'
          example:
            requestId: 8e033668-9f1a-11ec-b909-0242ac120002
            code: 409-01
            message: Conflict
    TooManyRequestsResponse:
      description: Too Many Requests response
      type: object
      properties:
        error:
          $ref: '#/components/schemas/DefaultErrorDetails'
          example:
            requestId: 8e033668-9f1a-11ec-b909-0242ac120002
            code: 429-01
            message: Too Many Requests
    Message:
      description: Represents a single message within a conversation.
      type: object
      properties:
        text:
          type: string
          minLength: 1
          description: The content of the message.
        sender:
          $ref: '#/components/schemas/Participant'
          description: Information about the participant who sent the message.
        timestamp:
          type: string
          format: date-time
          description: The time when the message was sent. Include the timezone, otherwise UTC will be assumed.
      required:
      - text
      - sender
      - timestamp
      example:
        text: Hello, I would like to upgrade my internet plan to GOLD.
        sender:
          role: agent
          externalId: 123
        timestamp: '2021-11-23T12:13:14.555Z'
    UnprocessableEntity:
      description: Unprocessable Entity response
      type: object
      properties:
        error:
          $ref: '#/components/schemas/DefaultErrorDetails'
          example:
            requestId: 8e033668-9f1a-11ec-b909-0242ac120002
            code: 422-01
            message: Unprocessable Entity
    BadRequestResponse:
      description: Bad request response
      type: object
      properties:
        error:
          $ref: '#/components/schemas/DefaultErrorDetails'
          example:
            requestId: 8e033668-9f1a-11ec-b909-0242ac120002
            code: 400-01
            message: Bad request
    NotFoundResponse:
      description: Not Found response
      type: object
      properties:
        error:
          $ref: '#/components/schemas/DefaultErrorDetails'
          example:
            requestId: 8e033668-9f1a-11ec-b909-0242ac120002
            code: 404-01
            message: Not Found
    DefaultErrorResponse:
      description: Default error response
      type: object
      properties:
        error:
          $ref: '#/components/schemas/DefaultErrorDetails'
          example:
            requestId: 8e033668-9f1a-11ec-b909-0242ac120002
            code: 500-01
            message: Internal server error
    RequestEntityTooLargeResponse:
      description: Request Entity Too Large response
      type: object
      properties:
        error:
          $ref: '#/components/schemas/DefaultErrorDetails'
          example:
            requestId: 8e033668-9f1a-11ec-b909-0242ac120002
            code: 413-01
            message: Request Entity Too Large
    ServiceUnavailableResponse:
      description: Service Unavailable response
      type: object
      properties:
        error:
          $ref: '#/components/schemas/DefaultErrorDetails'
          example:
            requestId: 8e033668-9f1a-11ec-b909-0242ac120002
            code: 503-01
            message: Service Unavailable
    ParticipantRole:
      description: 'A participant role, usually the customer or an agent for human participants. System participant is also allowed but keep in mind

        that this role won''t be considered a participant in a conversation, just a message sender.

        '
      type: string
      enum:
      - agent
      - customer
      - system
    Participant:
      description: Represents a participant in the conversation.
      type: object
      properties:
        role:
          $ref: '#/components/schemas/ParticipantRole'
          description: The role of the participant in the conversation.
        externalId:
          type: string
          description: The unique identifier for the participant in your external system. This should be consistent across all interactions for the same individual.
      required:
      - role
      - externalId
    UnauthorizedResponse:
      description: Unauthorized response
      type: object
      properties:
        error:
          $ref: '#/components/schemas/DefaultErrorDetails'
          example:
            requestId: 8e033668-9f1a-11ec-b909-0242ac120002
            code: 401-01
            message: Unauthorized
    ForbiddenResponse:
      description: Forbidden response
      type: object
      properties:
        error:
          $ref: '#/components/schemas/DefaultErrorDetails'
          example:
            requestId: 8e033668-9f1a-11ec-b909-0242ac120002
            code: 403-01
            message: Forbidden Response
    DefaultErrorDetails:
      description: Error details
      type: object
      properties:
        requestId:
          type: string
          description: Unique ID of the failing request
        message:
          type: string
          description: Error message
        code:
          type: string
          description: Error code
      required:
      - requestId
      - message
  responses:
    ServiceUnavailable:
      description: 503 - Service Unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServiceUnavailableResponse'
    DefaultError:
      description: 500 - Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DefaultErrorResponse'
    Unauthorized:
      description: 401 - Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedResponse'
    BadRequest:
      description: 400 - Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequestResponse'
    Forbidden:
      description: 403 - Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenResponse'
    Conflict:
      description: 409 - Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ConflictResponse'
    RequestEntityTooLarge:
      description: 413 - Request Entity Too Large
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RequestEntityTooLargeResponse'
    TooManyRequests:
      description: 429 - Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TooManyRequestsResponse'
    UnprocessableEntity:
      description: 422 - Unprocessable Entity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnprocessableEntity'
    NotFound:
      description: 404 - Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundResponse'
  securitySchemes:
    API-ID:
      type: apiKey
      in: header
      name: asapp-api-id
    API-Secret:
      type: apiKey
      in: header
      name: asapp-api-secret
x-tagGroups:
- name: AutoCompose API
  tags:
  - AutoCompose
- name: AutoSummary API
  tags:
  - AutoSummary
- name: AutoTranscribe API
  tags:
  - AutoTranscribe
- name: Conversations API
  tags:
  - Conversations
- name: File Exporter API
  tags:
  - File Exporter
- name: GenerativeAgent API
  tags:
  - GenerativeAgent
- name: Health Check API
  tags:
  - Health Check
- name: Knowledge Base API
  tags:
  - Knowledge Base
- name: Metadata Ingestion API
  tags:
  - Metadata
- name: MG Autotranscribe API Router
  tags:
  - AutoTranscribe Media Gateway