ASAPP GenerativeAgent API
Trigger GenerativeAgent to analyze and respond to conversations, stream events (SSE), and manage call transfers.
OpenAPI Specification
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\=<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](/g
# --- truncated at 32 KB (150 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/asapp/refs/heads/main/openapi/asapp-generativeagent-openapi.yml