openapi: 3.0.1 info: title: AutoCompose GenerativeAgent 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 security: - API-ID: [] API-Secret: [] tags: - name: GenerativeAgent description: Operations to send messages and trigger GenerativeAgent to respond or query the current state 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: description: Represents a single message within a conversation. type: object properties: text: type: string minLength: 1 description: The content of the message. sender: description: Information about the participant who sent the message. type: object properties: role: description: The role of the participant in the conversation. type: string enum: - customer 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 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: customer externalId: 123 timestamp: '2021-11-23T12:13:14.555Z' 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: customer 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': description: 400 - Bad request content: application/json: schema: description: Bad request response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 400-01 message: Bad request 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 '401': description: 401 - Unauthorized content: application/json: schema: description: Unauthorized response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 401-01 message: Unauthorized 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 '403': description: 403 - Forbidden content: application/json: schema: description: Forbidden response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 403-01 message: Forbidden Response 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 '404': description: 404 - Not Found content: application/json: schema: description: Not Found response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 404-01 message: Not Found 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 '409': description: 409 - Conflict content: application/json: schema: description: Conflict response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 409-01 message: Conflict 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 '413': description: 413 - Request Entity Too Large content: application/json: schema: description: Request Entity Too Large response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 413-01 message: Request Entity Too Large 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 '422': description: 422 - Unprocessable Entity content: application/json: schema: description: Unprocessable Entity response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 422-01 message: Unprocessable Entity 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 '429': description: 429 - Too Many Requests content: application/json: schema: description: Too Many Requests response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 429-01 message: Too Many Requests 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 '503': description: 503 - Service Unavailable content: application/json: schema: description: Service Unavailable response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 503-01 message: Service Unavailable 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 default: description: 500 - Internal Server Error content: application/json: schema: description: Default error response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 500-01 message: Internal server error 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 /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': description: 400 - Bad request content: application/json: schema: description: Bad request response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 400-01 message: Bad request 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 '401': description: 401 - Unauthorized content: application/json: schema: description: Unauthorized response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 401-01 message: Unauthorized 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 default: description: 500 - Internal Server Error content: application/json: schema: description: Default error response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 500-01 message: Internal server error 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 /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' /generativeagent/v1/call-transfers: post: tags: - GenerativeAgent operationId: createCallTransfer summary: Create Call Transfer description: 'Creates a new Call Transfer resource that represents an attempt to transfer a call from your IVR or CCaaS to ASAPP. The `type` indicates the type of call transfer: - `PHONE_NUMBER`: A temporary phone number is assigned for the transfer. - `SIP`: Session Initiation Protocol (SIP) transfer. You can optionally provide `inputContext` to provide context for the conversation. This is passed to GenerativeAgent. ' requestBody: required: true content: application/json: schema: description: Post Call Transfer Request type: object properties: id: description: A unique identifier for this call transfer request. This should be different for each transfer attempt. type: string example: 0867617078-0032318833-2221801472-0002236962 externalConversationId: description: "The unique identifier of the call in your call system. Multiple call transfers using the same externalConversationId will be treated as a single conversation. \n\nThis is the primary identifier for conversations within ASAPP and is reflected in reporting.\n" type: string example: 0867617078-0032318833-2221801472-0002236962 type: description: 'The type of call transfer being made. Currently supports: - `PHONE_NUMBER`: A temporary phone number is assigned for the transfer. - `SIP`: Session Initiation Protocol (SIP) transfer. ' type: string enum: - PHONE_NUMBER - SIP phoneNumber: description: Configuration information for requesting a phone number. Mandatory if `type` is `PHONE_NUMBER`. type: object properties: country: description: Country code (ISO 3166 Alpha 2) for the phone number to be assigned. Determines the country of the temporary transfer number. type: string example: US required: - country sip: description: 'Configuration for SIP transfers. Defines how the call will be transferred back when the Generative Agent finishes the conversation. **Transfer Types:** - `BYE`: Ends the call with a SIP BYE message. Use for supervised transfers to Generative Agent. Default value if returnTransferType is not provided. - `REFER`: Sends a SIP REFER message with the return URI in the Refer-To header. Use for blind transfers to another system. - `INVITE`: Initiates a new SIP INVITE to the return URI, ASAPP will continue to transcribe the call until the call is ended. ' type: object properties: returnTransferType: description: 'How the call will be transferred back when the Generative Agent finishes the conversation. - `BYE`: Ends the call with a SIP BYE message. Use for supervised transfers to Generative Agent. Default value if returnTransferType is not provided. - `REFER`: Sends a SIP REFER message with the return URI in the Refer-To header. Use for blind transfers to another system. - `INVITE`: Initiates a new SIP INVITE to the return URI, ASAPP will continue to transcribe the call until the call is ended. ' type: string enum: - BYE - REFER - INVITE returnUri: description: 'The SIP URI to transfer the call back to when the conversation ends. - Used in the Refer-To header if `returnTransferType` is `REFER` - Used as the destination for the SIP INVITE if `returnTransferType` is `INVITE` - Not used if `returnTransferType` is `BYE` ' type: string returnInviteAuthentication: description: Authentication credentials for SIP INVITE transfers. Required only when `returnTransferType` is `INVITE` and authentication is needed. type: object properties: username: description: Authentication username for the SIP INVITE. Required if authentication is needed. type: string example: sip_user password: description: Authentication password for the SIP INVITE. Required if authentication is needed. type: string example: sip_password example: returnTransferType: REFER returnUri: sip:transfer@your-company.com:5060 inputContext: description: Optional context information to pass to the Generative Agent when the call is received. type: object properties: taskName: description: The name of the task that the [Generative Agent will enter](generativeagent/configuring/tasks-and-functions/enter-specific-task) when the call begins. type: string inputVariables: description: Key-value pairs of [input variables](/generativeagent/configuring/tasks-and-functions/input-variables) that provide context to the Generative Agent for the conversation. type: object additionalProperties: type: string required: - id - externalConversationId - type example: id: 0867617078-0032318833-2221801472-0002236962 externalConversationId: 0867617078-0032318833-2221801472-0002236962 type: PHONE_NUMBER phoneNumber: country: US inputContext: taskName: Welcome inputVariables: email: example@gmail.com name: name responses: '200': description: Successful response content: application/json: schema: description: Post Call Transfer Response type: object properties: id: description: The unique identifier for this call transfer request, matching the ID provided in the request. type: string example: 0867617078-0032318833-2221801472-0002236962 externalConversationId: description: The unique identifier of the call in your call system. This will be referenced in ASAPP reporting. Usually this is the same value as the call transfer ID. type: string example: 0867617078-0032318833-2221801472-0002236962 status: description: "The current status of the call transfer request. \n\nOn creation, the status is `ACTIVE` and is waiting for your system to transfer the call.\n" type: string enum: - ACTIVE - ONGOING - COMPLETED - EXPIRED type: description: The type of call transfer method being used. type: string enum: - PHONE_NUMBER - SIP phoneNumber: description: Details about the assigned phone number for the transfer. Available only if `type` is `PHONE_NUMBER`. type: object properties: transferNumber: description: The phone number that your IVR should dial to transfer the call to ASAPP. type: string example: '+19995550199' country: description: Country code (ISO 3166 Alpha 2) of the assigned phone number. type: string example: US expiresAt: description: Timestamp (ISO 8601) when the transfer phone number will expire and become unavailable. type: string example: '2024-06-01T12:34:56Z' required: - transferNumber - country - expiresAt sip: description: 'Configuration for SIP transfers. Defines how the call will be transferred back when the Generative Agent finishes the conversation. **Transfer Types:** - `BYE`: Ends the call with a SIP BYE message. Use for supervised transfers to Generative Agent. Default value if returnTransferType is not provided. - `REFER`: Sends a SIP REFER message with the return URI in the Refer-To header. Use for blind transfers to another system. - `INVITE`: Initiates a new SIP INVITE to the return URI, ASAPP will continue to transcribe the call until the call is ended. ' type: object properties: returnTransferType: description: 'How the call will be transferred back when the Generative Agent finishes the conversation. - `BYE`: Ends the call with a SIP BYE message. Use for supervised transfers to Generative Agent. Default value if returnTransferType is not provided. - `REFER`: Sends a SIP REFER message with the return URI in the Refer-To header. Use for blind transfers to another system. - `INVITE`: Initiates a new SIP INVITE to the return URI, ASAPP will continue to transcribe the call until the call is ended. ' type: string enum: - BYE - REFER - INVITE returnUri: description: 'The SIP URI to transfer the call back to when the conversation ends. - Used in the Refer-To header if `returnTransferType` is `REFER` - Used as the destination for the SIP INVITE if `returnTransferType` is `INVITE` - Not used if `returnTransferType` is `BYE` ' type: string returnInviteAuthentication: description: Authentication credentials for SIP INVITE transfers. Required only when `returnTransferType` is `INVITE` and authentication is needed. type: object properties: username: description: Authentication username for the SIP INVITE. Required if authentication is needed. type: string example: sip_user password: description: Authentication password for the SIP INVITE. Required if authentication is needed. type: string example: sip_password example: returnTransferType: REFER returnUri: sip:transfer@your-company.com:5060 inputContext: description: The context information that will be passed to the Generative Agent when the call is received. type: object properties: taskName: description: The name of the task that the [Generative Agent will enter](generativeagent/configuring/tasks-and-functions/enter-specific-task) when the call begins. type: string inputVariables: description: Key-value pairs of [input variables](/generativeagent/configuring/tasks-and-functions/input-variables) that provide context to the Generative Agent for the conversation. type: object additionalProperties: type: string example: email: example@gmail.com name: name required: - id - externalConversationId - type example: id: 0867617078-0032318833-2221801472-0002236962 externalConversationId: 0867617078-0032318833-2221801472-0002236962 type: PHONE_NUMBER phoneNumber: transferNumber: '+19995550199' country: US expiresAt: '2024-06-01T12:34:56Z' inputContext: taskName: Welcome inputVariables: email: example@gmail.com name: name '400': description: 400 - Bad request content: application/json: schema: description: Bad request response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 400-01 message: Bad request 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 '401': description: 401 - Unauthorized content: application/json: schema: description: Unauthorized response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 401-01 message: Unauthorized 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 '403': description: 403 - Forbidden content: application/json: schema: description: Forbidden response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 403-01 message: Forbidden Response 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 '404': description: 404 - Not Found content: application/json: schema: description: Not Found response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 404-01 message: Not Found 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 '409': description: 409 - Conflict content: application/json: schema: description: Conflict response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 409-01 message: Conflict 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 '413': description: 413 - Request Entity Too Large content: application/json: schema: description: Request Entity Too Large response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 413-01 message: Request Entity Too Large 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 '422': description: 422 - Unprocessable Entity content: application/json: schema: description: Unprocessable Entity response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 422-01 message: Unprocessable Entity 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 '429': description: 429 - Too Many Requests content: application/json: schema: description: Too Many Requests response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 429-01 message: Too Many Requests 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 '503': description: 503 - Service Unavailable content: application/json: schema: description: Service Unavailable response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 503-01 message: Service Unavailable 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 default: description: 500 - Internal Server Error content: application/json: schema: description: Default error response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 500-01 message: Internal server error 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 /generativeagent/v1/call-transfers/{callTransferId}: get: tags: - GenerativeAgent operationId: getCallTransfer summary: Get Call Transfer description: 'Get Call Transfer resource by ID. ' parameters: - name: callTransferId description: The identifier for the call transfer. in: path required: true schema: type: string responses: '200': description: Successful response content: application/json: schema: description: Get Call Transfer Response type: object properties: id: description: The unique identifier for this call transfer request. type: string example: 0867617078-0032318833-2221801472-0002236962 externalConversationId: description: The unique identifier of the call in your call system. This will be referenced in ASAPP reporting. type: string example: 0867617078-0032318833-2221801472-0002236962 status: description: "The current status of the call transfer request.\n- `ACTIVE`: The call transfer request has been created and is waiting for your system to transfer the call.\n- `ONGOING`: The call transfer has been received by ASAPP and is currently in progress. The phone number is no longer assigned to the call transfer request.\n- `COMPLETED`: The call transfer has been successfully completed. The output context will be returned.\n- `EXPIRED`: The call transfer request is no longer valid (e.g., the phone number expired). \n" type: string enum: - ACTIVE - ONGOING - COMPLETED - EXPIRED createdAt: description: Timestamp (ISO 8601) when the call transfer resource was created. type: string example: '2024-06-01T12:34:56Z' callReceivedAt: description: Timestamp (ISO 8601) when the call transfer was received by ASAPP. type: string example: '2024-06-01T12:34:56Z' completedAt: description: Timestamp (ISO 8601) when the call transfer was completed by the Generative Agent. type: string example: '2024-06-01T12:34:56Z' inputContext: description: The context information that was passed to the Generative Agent when the call was received. type: object properties: taskName: description: The name of the task that the [Generative Agent entered](generativeagent/configuring/tasks-and-functions/enter-specific-task) when the call began. type: string inputVariables: description: Key-value pairs of [input variables](/generativeagent/configuring/tasks-and-functions/input-variables) that provided context to the Generative Agent for the conversation. type: object additionalProperties: type: string example: taskName: welcome variables: email: example@gmail.com name: name outputContext: description: The context information from the Generative Agent when the call ended. type: object properties: transferType: description: "The type of returning transfer. Can be one of:\n- **AGENT**: GenerativeAgent has requested to transfer the call to a human agent.\n- **SYSTEM**: A task has requested to hand the call back to the originating system. Usually indicative that the call was handle successfully.\n- **CALLER_DISCONNECT**: The caller disconnected before the transfer could be completed. \n" type: string enum: - AGENT - SYSTEM - CALLER_DISCONNECT currentTaskName: description: The name of the task that the Generative Agent was executing when the call ended. type: string referenceVariables: description: Key-value pairs of reference variables that were set during the conversation as returned during a [system transfer](/generativeagent/configuring/tasks-and-functions/system-transfer). type: object additionalProperties: type: string transferVariables: description: Key-value pairs of transfer variables that can be used when transferring to another system as returned during a [system transfer](/generativeagent/configuring/tasks-and-functions/system-transfer). type: object additionalProperties: type: string example: currentTaskName: welcome referenceVariables: reference_variable_1: reference_value_1 reference_variable_2: reference_value_2 transferVariables: transfer_variable_1: transfer_value_1 transfer_variable_2: transfer_value_2 type: description: The type of call transfer method that was used. type: string enum: - PHONE_NUMBER - SIP phoneNumber: description: Details about the assigned phone number for the transfer, including the number to dial and when it expires. Only available if `type` is `PHONE_NUMBER`. type: object properties: transferNumber: description: The phone number that your IVR should dial to transfer the call to ASAPP. type: string example: '+19995550199' country: description: Country code (ISO 3166 Alpha 2) of the assigned phone number. type: string example: US expiresAt: description: Timestamp (ISO 8601) when the transfer phone number will expire and become unavailable. type: string example: '2024-06-01T12:34:56Z' required: - transferNumber - country - expiresAt sip: description: 'Configuration for SIP transfers. Defines how the call will be transferred back when the Generative Agent finishes the conversation. **Transfer Types:** - `BYE`: Ends the call with a SIP BYE message. Use for supervised transfers to Generative Agent. Default value if returnTransferType is not provided. - `REFER`: Sends a SIP REFER message with the return URI in the Refer-To header. Use for blind transfers to another system. - `INVITE`: Initiates a new SIP INVITE to the return URI, ASAPP will continue to transcribe the call until the call is ended. ' type: object properties: returnTransferType: description: 'How the call will be transferred back when the Generative Agent finishes the conversation. - `BYE`: Ends the call with a SIP BYE message. Use for supervised transfers to Generative Agent. Default value if returnTransferType is not provided. - `REFER`: Sends a SIP REFER message with the return URI in the Refer-To header. Use for blind transfers to another system. - `INVITE`: Initiates a new SIP INVITE to the return URI, ASAPP will continue to transcribe the call until the call is ended. ' type: string enum: - BYE - REFER - INVITE returnUri: description: 'The SIP URI to transfer the call back to when the conversation ends. - Used in the Refer-To header if `returnTransferType` is `REFER` - Used as the destination for the SIP INVITE if `returnTransferType` is `INVITE` - Not used if `returnTransferType` is `BYE` ' type: string returnInviteAuthentication: description: Authentication credentials for SIP INVITE transfers. Required only when `returnTransferType` is `INVITE` and authentication is needed. type: object properties: username: description: Authentication username for the SIP INVITE. Required if authentication is needed. type: string example: sip_user password: description: Authentication password for the SIP INVITE. Required if authentication is needed. type: string example: sip_password example: returnTransferType: REFER returnUri: sip:transfer@your-company.com:5060 required: - id - externalConversationId - status - createdAt - type example: id: 0867617078-0032318833-2221801472-0002236962 externalConversationId: 0867617078-0032318833-2221801472-0002236962 status: completed createdAt: '2024-06-01T12:34:56Z' callReceivedAt: '2024-06-01T12:35:00Z' completedAt: '2024-06-01T12:38:56Z' inputContext: taskName: Welcome inputVariables: email: example@gmail.com name: name outputContext: transferType: SYSTEM currentTaskName: Welcome referenceVariables: reference_variable_1: reference_value_1 reference_variable_2: reference_value_2 transferVariables: transfer_variable_1: transfer_value_1 transfer_variable_2: transfer_value_2 type: PHONE_NUMBER phoneNumber: transferNumber: '+19995550199' country: US expiresAt: '2024-06-01T12:35:56Z' '400': description: 400 - Bad request content: application/json: schema: description: Bad request response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 400-01 message: Bad request 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 '401': description: 401 - Unauthorized content: application/json: schema: description: Unauthorized response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 401-01 message: Unauthorized 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 '403': description: 403 - Forbidden content: application/json: schema: description: Forbidden response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 403-01 message: Forbidden Response 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 '404': description: 404 - Not Found content: application/json: schema: description: Not Found response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 404-01 message: Not Found 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 '409': description: 409 - Conflict content: application/json: schema: description: Conflict response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 409-01 message: Conflict 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 '413': description: 413 - Request Entity Too Large content: application/json: schema: description: Request Entity Too Large response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 413-01 message: Request Entity Too Large 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 '422': description: 422 - Unprocessable Entity content: application/json: schema: description: Unprocessable Entity response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 422-01 message: Unprocessable Entity 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 '429': description: 429 - Too Many Requests content: application/json: schema: description: Too Many Requests response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 429-01 message: Too Many Requests 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 '503': description: 503 - Service Unavailable content: application/json: schema: description: Service Unavailable response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 503-01 message: Service Unavailable 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 default: description: 500 - Internal Server Error content: application/json: schema: description: Default error response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 500-01 message: Internal server error 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 /generativeagent/v1/lookup-transfer: post: tags: - GenerativeAgent operationId: lookupCallTransfer summary: Lookup Call Transfer with phone number and retrieve variables description: 'Lookup Call Transfer with phone number and retrieve variables. Used by ASAPP to match the phone number with a call transfer. ' requestBody: required: true content: application/json: schema: description: Post Lookup Call Transfer Request type: object properties: type: description: Enum to identify how the call will be transferred to ASAPP. type: string enum: - PHONE_NUMBER - SIP phoneNumber: description: ASAPP Phone Number which received the call. Only used if `type` is `PHONE_NUMBER`. type: string example: '+19995550199' transferId: description: SIP Identifier (SIP Identifier Header value). type: string example: 0867617078-0032318833-2221801472-0002236962 required: - type example: type: PHONE_NUMBER phoneNumber: '+19995550199' responses: '200': description: Successful response content: application/json: schema: description: Post Lookup Call Transfer Response type: object properties: id: description: Call Transfer unique identifier. type: string example: 0867617078-0032318833-2221801472-0002236962 externalConversationId: description: The unique identifier of the call in your call system. This will be referenced in ASAPP reporting. Usually this is the same value as call transfer id. type: string example: 0867617078-0032318833-2221801472-0002236962 inputContext: description: Input context for the conversation. type: object properties: taskName: description: Task name used to engage Generative Agent. type: string inputVariables: description: Input variables to engage Generative Agent. type: object additionalProperties: type: string example: taskName: welcome variables: email: example@gmail.com name: name sip: description: 'Configuration for SIP transfers. Defines how the call will be transferred back when the Generative Agent finishes the conversation. **Transfer Types:** - `BYE`: Ends the call with a SIP BYE message. Use for supervised transfers to Generative Agent. Default value if returnTransferType is not provided. - `REFER`: Sends a SIP REFER message with the return URI in the Refer-To header. Use for blind transfers to another system. - `INVITE`: Initiates a new SIP INVITE to the return URI, ASAPP will continue to transcribe the call until the call is ended. ' type: object properties: returnTransferType: description: 'How the call will be transferred back when the Generative Agent finishes the conversation. - `BYE`: Ends the call with a SIP BYE message. Use for supervised transfers to Generative Agent. Default value if returnTransferType is not provided. - `REFER`: Sends a SIP REFER message with the return URI in the Refer-To header. Use for blind transfers to another system. - `INVITE`: Initiates a new SIP INVITE to the return URI, ASAPP will continue to transcribe the call until the call is ended. ' type: string enum: - BYE - REFER - INVITE returnUri: description: 'The SIP URI to transfer the call back to when the conversation ends. - Used in the Refer-To header if `returnTransferType` is `REFER` - Used as the destination for the SIP INVITE if `returnTransferType` is `INVITE` - Not used if `returnTransferType` is `BYE` ' type: string returnInviteAuthentication: description: Authentication credentials for SIP INVITE transfers. Required only when `returnTransferType` is `INVITE` and authentication is needed. type: object properties: username: description: Authentication username for the SIP INVITE. Required if authentication is needed. type: string example: sip_user password: description: Authentication password for the SIP INVITE. Required if authentication is needed. type: string example: sip_password example: returnTransferType: REFER returnUri: sip:transfer@your-company.com:5060 required: - id - externalConversationId - inputContext example: id: 0867617078-0032318833-2221801472-0002236962 externalConversationId: 0867617078-0032318833-2221801472-0002236962 inputContext: taskName: Welcome inputVariables: email: example@gmail.com name: name '400': description: 400 - Bad request content: application/json: schema: description: Bad request response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 400-01 message: Bad request 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 '401': description: 401 - Unauthorized content: application/json: schema: description: Unauthorized response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 401-01 message: Unauthorized 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 '403': description: 403 - Forbidden content: application/json: schema: description: Forbidden response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 403-01 message: Forbidden Response 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 '404': description: 404 - Not Found content: application/json: schema: description: Not Found response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 404-01 message: Not Found 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 '409': description: 409 - Conflict content: application/json: schema: description: Conflict response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 409-01 message: Conflict 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 '413': description: 413 - Request Entity Too Large content: application/json: schema: description: Request Entity Too Large response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 413-01 message: Request Entity Too Large 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 '422': description: 422 - Unprocessable Entity content: application/json: schema: description: Unprocessable Entity response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 422-01 message: Unprocessable Entity 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 '429': description: 429 - Too Many Requests content: application/json: schema: description: Too Many Requests response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 429-01 message: Too Many Requests 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 '503': description: 503 - Service Unavailable content: application/json: schema: description: Service Unavailable response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 503-01 message: Service Unavailable 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 default: description: 500 - Internal Server Error content: application/json: schema: description: Default error response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 500-01 message: Internal server error 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 /generativeagent/v1/complete-transfer: post: tags: - GenerativeAgent operationId: completeCallTransfer summary: Complete Call Transfer with phone number. description: 'Complete Call Transfer with phone number. Used by ASAPP to release phone number back to the pool and update Call Transfer resource status. ' requestBody: required: true content: application/json: schema: description: Post Complete Call Transfer Request type: object properties: type: description: Enum to identify how the call will be transferred to ASAPP. type: string enum: - PHONE_NUMBER - SIP phoneNumber: description: ASAPP Phone Number which received the call. Only used if `type` is `PHONE_NUMBER`. type: string example: '+19995550199' transferId: description: Call Transfer unique identifier. type: string example: 0867617078-0032318833-2221801472-0002236962 required: - type example: type: PHONE_NUMBER phoneNumber: '+19995550199' responses: '200': description: Acknowledgement that the complete call transfer request was successful. content: {} '400': description: 400 - Bad request content: application/json: schema: description: Bad request response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 400-01 message: Bad request 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 '401': description: 401 - Unauthorized content: application/json: schema: description: Unauthorized response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 401-01 message: Unauthorized 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 '403': description: 403 - Forbidden content: application/json: schema: description: Forbidden response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 403-01 message: Forbidden Response 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 '404': description: 404 - Not Found content: application/json: schema: description: Not Found response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 404-01 message: Not Found 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 '409': description: 409 - Conflict content: application/json: schema: description: Conflict response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 409-01 message: Conflict 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 '413': description: 413 - Request Entity Too Large content: application/json: schema: description: Request Entity Too Large response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 413-01 message: Request Entity Too Large 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 '422': description: 422 - Unprocessable Entity content: application/json: schema: description: Unprocessable Entity response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 422-01 message: Unprocessable Entity 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 '429': description: 429 - Too Many Requests content: application/json: schema: description: Too Many Requests response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 429-01 message: Too Many Requests 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 '503': description: 503 - Service Unavailable content: application/json: schema: description: Service Unavailable response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 503-01 message: Service Unavailable 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 default: description: 500 - Internal Server Error content: application/json: schema: description: Default error response type: object properties: error: example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 500-01 message: Internal server error 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 components: securitySchemes: API-ID: type: apiKey in: header name: asapp-api-id API-Secret: type: apiKey in: header name: asapp-api-secret