openapi: 3.0.1 info: title: GenerativeAgent API description: > GenerativeAgent API allows customers to interact with a chat / voice automation bot leveraging LLMs by sending messages and receiving responses asynchronously through webhooks contact: email: api-info@asapp.com license: name: ASAPP Software License url: https://api.asapp.com/LICENSE version: '0.1' servers: - url: https://api.sandbox.asapp.com tags: - name: GenerativeAgent description: >- Operations to send messages and trigger GenerativeAgent to respond or query the current state security: - API-ID: [] API-Secret: [] 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: * `ready` - GenerativeAgent is ready to respond to requests * `processing` - GenerativeAgent is actively processing the conversation * `waitingForConfirmation` - GenerativeAgent is expecting an explicit confirmation on the next message * `waitingForAuth` - GenerativeAgent is waiting for the user to login before proceeding * `transferredToAgent` - GenerativeAgent is no longer able to provide meaningful responses and has requested the conversation be transferred to a human agent * `transferredToSystem` - GenerativeAgent has transferred control of this conversation back to the caller system. However, it will respond if new analyze requests are made 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. This is the primary identifier for conversations within ASAPP and is reflected in reporting. 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. On creation, the status is `ACTIVE` and is waiting for your system to transfer the call. 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. - `ACTIVE`: The call transfer request has been created and is waiting for your system to transfer the call. - `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. - `COMPLETED`: The call transfer has been successfully completed. The output context will be returned. - `EXPIRED`: The call transfer request is no longer valid (e.g., the phone number expired). 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: - **AGENT**: GenerativeAgent has requested to transfer the call to a human agent. - **SYSTEM**: A task has requested to hand the call back to the originating system. Usually indicative that the call was handle successfully. - **CALLER_DISCONNECT**: The caller disconnected before the transfer could be completed. 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 responses: BadRequest: 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 Unauthorized: 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 Forbidden: 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 NotFound: 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 Conflict: 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 RequestEntityTooLarge: 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 UnprocessableEntity: 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 TooManyRequests: 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 ServiceUnavailable: 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 DefaultError: 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 schemas: GenerativeAgentSignal: type: object description: | The type of signals the GenerativeAgent sends through webhooks. oneOf: - type: object properties: webhookMessageId: type: string description: The ID that uniquely identifies the webhook conversationId: type: string description: Internal conversation identifier from ASAPP externalConversationId: type: string description: External conversation identifier from chat / voice system type: type: string description: A signal to containing the bot responses reply: type: object properties: messageId: type: string description: The identifier of the message sent in the reply text: type: string description: The message text of the reply - type: object properties: webhookMessageId: type: string description: The ID that uniquely identifies the webhook conversationId: type: string description: Internal conversation identifier from ASAPP externalConversationId: type: string description: External conversation identifier from chat / voice system type: type: string description: A signal to indicate the bot started processing - type: object properties: webhookMessageId: type: string description: The ID that uniquely identifies the webhook conversationId: type: string description: Internal conversation identifier from ASAPP externalConversationId: type: string description: External conversation identifier from chat / voice system type: type: string description: A signal to indicate the bot finished processing - type: object properties: webhookMessageId: type: string description: The ID that uniquely identifies the webhook conversationId: type: string description: Internal conversation identifier from ASAPP externalConversationId: type: string description: External conversation identifier from chat / voice system type: type: string description: >- A signal to indicate the bot is waiting for the customer to authenticate (for integrated flows) - type: object properties: webhookMessageId: type: string description: The ID that uniquely identifies the webhook conversationId: type: string description: Internal conversation identifier from ASAPP externalConversationId: type: string description: External conversation identifier from chat / voice system type: type: string description: >- A signal to indicate the bot could not handle the request and the conversation should be transferred to an agent discriminator: propertyName: type mapping: reply: '#/components/schemas/GenerativeAgentSignalReply' processingStart: '#/components/schemas/GenerativeAgentSignalProcessingStart' processingEnd: '#/components/schemas/GenerativeAgentSignalProcessingEnd' authenticationRequested: '#/components/schemas/GenerativeAgentSignalAuthenticationRequested' transferToAgent: '#/components/schemas/GenerativeAgentSignalTransferToAgent' GenerativeAgentSignalReply: type: object properties: webhookMessageId: type: string description: The ID that uniquely identifies the webhook conversationId: type: string description: Internal conversation identifier from ASAPP externalConversationId: type: string description: External conversation identifier from chat / voice system type: type: string description: A signal to containing the bot responses reply: type: object properties: messageId: type: string description: The identifier of the message sent in the reply text: type: string description: The message text of the reply GenerativeAgentSignalProcessingStart: type: object properties: webhookMessageId: type: string description: The ID that uniquely identifies the webhook conversationId: type: string description: Internal conversation identifier from ASAPP externalConversationId: type: string description: External conversation identifier from chat / voice system type: type: string description: A signal to indicate the bot started processing GenerativeAgentSignalProcessingEnd: type: object properties: webhookMessageId: type: string description: The ID that uniquely identifies the webhook conversationId: type: string description: Internal conversation identifier from ASAPP externalConversationId: type: string description: External conversation identifier from chat / voice system type: type: string description: A signal to indicate the bot finished processing GenerativeAgentSignalAuthenticationRequested: type: object properties: webhookMessageId: type: string description: The ID that uniquely identifies the webhook conversationId: type: string description: Internal conversation identifier from ASAPP externalConversationId: type: string description: External conversation identifier from chat / voice system type: type: string description: >- A signal to indicate the bot is waiting for the customer to authenticate (for integrated flows) GenerativeAgentSignalTransferToAgent: type: object properties: webhookMessageId: type: string description: The ID that uniquely identifies the webhook conversationId: type: string description: Internal conversation identifier from ASAPP externalConversationId: type: string description: External conversation identifier from chat / voice system type: type: string description: >- A signal to indicate the bot could not handle the request and the conversation should be transferred to an agent PostCallTransferRequest: 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. This is the primary identifier for conversations within ASAPP and is reflected in reporting. 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 PostCallTransferResponse: 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. On creation, the status is `ACTIVE` and is waiting for your system to transfer the call. 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 GetCallTransferResponse: 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. - `ACTIVE`: The call transfer request has been created and is waiting for your system to transfer the call. - `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. - `COMPLETED`: The call transfer has been successfully completed. The output context will be returned. - `EXPIRED`: The call transfer request is no longer valid (e.g., the phone number expired). 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: - **AGENT**: GenerativeAgent has requested to transfer the call to a human agent. - **SYSTEM**: A task has requested to hand the call back to the originating system. Usually indicative that the call was handle successfully. - **CALLER_DISCONNECT**: The caller disconnected before the transfer could be completed. 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' PostLookupCallTransferRequest: 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' PostLookupCallTransferResponse: 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 PostCompleteCallTransferRequest: 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' SIPTransferData: 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 SIPInviteAuthentication: description: >- Authentication credentials for SIP INVITE transfers. Only used when `returnTransferType` is `INVITE`. 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