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\= 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 x-provenance: method: harvested publisher: Asapp3 source: https://docs.asapp.com/api-specs/openapi.yaml note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json); stamped by stamp-openapi-provenance.py (roadmap#793)