ASAPP GenerativeAgent API
Operations to send messages and trigger GenerativeAgent to respond or query the current state
OpenAPI Specification
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\=<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:
# --- truncated at 32 KB (96 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/asapp/refs/heads/main/openapi/asapp-generativeagent-api-openapi.yml