openapi: 3.0.1
info:
title: AutoCompose API
description: >
Autocompose API to suggest the next agent message.
Suggestions are based on the conversation history, conversation metadata,
and
the in-progress message text the agent has already typed into the composer.
version: 0.0.3
servers:
- url: https://api.sandbox.asapp.com
- url: https://api.test.asapp.com
tags:
- name: AutoCompose
description: Improve agent productivity with AutoCompose API
x-displayName: AutoCompose
- name: AutoSummary
description: Endpoints for summarizing conversations and retrieving structured data
x-displayName: AutoSummary
- name: AutoTranscribe
description: Get streaming URL to transcribe audio
x-displayName: AutoTranscribe
- name: Conversations
description: Operations to send conversational inputs to ASAPP AI services
x-displayName: Conversations
- name: File Exporter
description: API to get client exports
x-displayName: File Exporter
- name: GenerativeAgent
description: >-
Operations to send messages and trigger GenerativeAgent to respond or
query the current state
x-displayName: GenerativeAgent
- name: Health Check
description: Operations to ensure that ASAPP APIs are up and running.
x-displayName: Health Check
- name: Knowledge Base
description: >-
Operations to submit and retrieve Articles to the GenerativeAgent
Knowledge Base.
x-displayName: Knowledge Base
- name: Metadata
description: API to submit entity's attributes to ASAPP
x-displayName: Metadata
- name: AutoTranscribe Media Gateway
description: >-
Operations for controlling AutoTranscribe Media Gateway transcription and
streaming
x-displayName: AutoTranscribe Media Gateway
paths:
/autocompose/v1/conversations/{conversationId}/suggestions:
parameters:
- $ref: '#/components/parameters/conversationId'
post:
tags:
- AutoCompose
operationId: getSuggestions
summary: Generate suggestions
description: >
Get suggestions for the next agent message in the conversation.
There are several times when this should be called:
- when an agent joins the conversation,
- after a message is sent by either the customer or the agent,
- and as the agent is typing in the composer (to enable completing the
agent's in-progress message).
Optionally, add a message to the conversation.
requestBody:
description: The parameters for getting suggestions for the next agent message.
content:
application/json:
schema:
$ref: '#/components/schemas/SuggestionsRequest'
responses:
'200':
description: Successfully fetched suggestions for the conversation
content:
application/json:
schema:
$ref: '#/components/schemas/Suggestions'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/autocompose/v1/profanity/evaluation:
post:
tags:
- AutoCompose
operationId: getEvaluation
summary: Evaluate profanity
description: >
Get an evaluation of a text to verify if it contains profanity,
obscenity or other unwanted words. This service should be called before
sending a message to prevent the agent from sending profanities in the
chat.
requestBody:
description: >-
The parameters for getting a evaluation result of the text typed by
the user.
content:
application/json:
schema:
type: object
properties:
text:
description: text to be checked for profanity
type: string
example:
text: This is a perfectly decent sentence.
responses:
'200':
description: Successfully fetched a evaluation result of the sentence.
content:
application/json:
schema:
$ref: '#/components/schemas/ProfanityResult'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/autocompose/v1/spellcheck/correction:
post:
tags:
- AutoCompose
operationId: getSpellingCorrection
summary: Check for spelling mistakes
description: >
Get spelling correction for a message as it is being typed, if there is
a misspelling. Only the current word
will be corrected, once it's fully typed (so it is recommended to call
this endpoint after space characters).
requestBody:
description: >-
The parameters for getting a spelling correction as a message is being
typed.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SpellcheckQuery'
responses:
'200':
description: Successfully checked for a spelling mistake.
content:
application/json:
schema:
$ref: '#/components/schemas/SpellcheckCorrection'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/autocompose/v1/analytics/message-sent:
post:
tags:
- AutoCompose
operationId: createMessageSentEvent
summary: Create a MessageSent analytics event
description: >
Create a MessageSent analytics event describing the agent's usage of
AutoCompose augmentation features
while composing a message
requestBody:
description: The parameters for creating a MessageSent event
content:
application/json:
schema:
$ref: '#/components/schemas/MessageSentEvent'
responses:
'200':
description: Successfully created a MessageSent event
content: {}
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/autocompose/v1/conversations/{conversationId}/message-analytic-events:
parameters:
- $ref: '#/components/parameters/conversationId'
post:
tags:
- AutoCompose
operationId: createMessageAnalyticEvent
summary: Create a message analytic event
description: >
To improve the performance of ASAPP suggestions, provide information
about the actions performed by the agent while composing a message by
creating `message-analytic-events`.
These analytic events indicate which AutoCompose functionality was used
or not. This information along with the conversation itself is used to
optimize our models, resulting in better results for the agents.
We track the following types of message analytic events:
- suggestion-1-inserted: The agent selected the first of the
`suggestions` from a `Suggestion` API response.
- suggestion-2-inserted: The agent selected the second of the
`suggestions` from a `Suggestion` API response.
- suggestion-3-inserted: The agent selected the third of the
`suggestions` from a `Suggestion` API response.
- phrase-completion-accepted: The agent selected the `phraseCompletion`
from a `Suggestion` API response.
- spellcheck-applied: A correction provided in a `SpellcheckCorrection`
API response was applied automatically.
- spellcheck-undone: A correction provided in a `SpellcheckCorrection`
API response was undone by clicking the undo button.
- custom-response-drawer-inserted: The agent inserted one of their
custom responses from the custom response drawer.
- custom-panel-inserted: The agent inserted a response from their custom
response list in the custom response panel.
- global-panel-inserted: The agent inserted a response from the global
response list in the global response panel.
Some of the event types have a corresponding event object to provide
details.
requestBody:
description: The parameters for reporting the analytic event
content:
application/json:
schema:
$ref: '#/components/schemas/MessageAnalyticEvent'
examples:
Create a suggestion-inserted event.:
value:
type: suggestion-1-inserted
suggestionsId: 4d2fd982640c311394008259594399a1
Create a spellcheck-applied event.:
value:
type: spellcheck-applied
suggestionsId: 4d2fd982640c311394008259594399a1
spellcheckApplied:
correctionId: 75bc8912c66842594375bc8912c66842
Create a spellcheck-undone event.:
value:
type: spellcheck-undone
suggestionsId: 4d2fd982640c311394008259594399a1
spellcheckUndone:
correctionId: 75bc8912c66842594375bc8912c66842
Create a custom-response-drawer-inserted event.:
value:
type: custom-response-drawer-inserted
suggestionsId: 4d2fd982640c311394008259594399a1
customResponseDrawerInserted:
query: Hi
text: Hi, I'm Alice. How can I help you today?
Create a custom-panel-inserted event.:
value:
type: custom-panel-inserted
suggestionsId: 4d2fd982640c311394008259594399a1
customPanelInserted:
text: Hi, I'm Alice. How can I help you today?
Create a global-panel-inserted event.:
value:
type: global-panel-inserted
suggestionsId: 4d2fd982640c311394008259594399a1
globalPanelInserted:
text: How can I help you today?
responses:
'200':
description: Successfully reported selected suggestion
content: {}
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/autocompose/v1/settings:
parameters:
- $ref: '#/components/parameters/agentId'
get:
tags:
- AutoCompose
operationId: getSettings
summary: Get settings for AutoCompose clients
description: >
Get settings for AutoCompose clients, such as whether any features
should not be used.
It may be desirable to disable some features in high-latency scenarios.
responses:
'200':
description: Settings for AutoCompose clients
content:
application/json:
schema:
$ref: '#/components/schemas/Settings'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/autocompose/v1/responses/globals:
get:
tags:
- AutoCompose
summary: List the global responses
description: >-
Get the global responses and folder organization for a company.
Responses are sorted by text, and folders are sorted by name.
operationId: getGlobalResponses
parameters:
- in: query
name: folderId
schema:
type: string
required: false
description: >-
Optional identifier for the ID of the folder containing responses to
be retrieved. If this is omitted, all global responses are
returned. Data format is expected to be UUID. The special value
'__root' can also be used to retrieve top level folders/responses.
- in: query
name: resourceType
schema:
type: string
enum:
- folders
- responses
- all
default: all
required: false
description: >-
Optional identifier for the ID of the type of responses to be
retrieved. A value of 'folders' will return only folder information
describing the way responses are organized. A value of 'responses'
will return only responses. A value of 'all' will return a mix of
folders and responses. Note that if the folderId parameter is
specified as well, only the resource type identified here that
exists within the specified folder will be returned. If this is
omitted, all resources are returned.
- in: query
name: searchTerm
schema:
type: string
required: false
description: >-
Search term to search for global responses. This will search for
matching folder names, response text or both, depending on the
resourceType parameter value.
example: greetings
- in: query
name: pageToken
description: >-
This service responds with a set of global responses. These are
divided into pages, with maxPerPage items in each page. This
parameter is the page token returned in the call prior to this one.
If this is the first call being made, this field should be omitted.
The server will respond with global responses following the one
previously sent.
required: false
schema:
type: string
example: '3'
- in: query
name: maxPerPage
description: >-
The maximum number of custom responses the client can handle within
one page
required: false
schema:
type: integer
default: 1000
responses:
'200':
description: The global responses for this company
content:
application/json:
schema:
$ref: '#/components/schemas/GlobalResponsesWithVersion'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/autocompose/v1/responses/customs:
parameters:
- $ref: '#/components/parameters/agentId'
get:
tags:
- AutoCompose
summary: Get custom responses
description: >-
Get custom responses for an agent. Responses are sorted by title, and
folders are sorted by name.
operationId: getCustomResponseCollection
parameters:
- in: query
name: folderId
schema:
type: string
required: false
description: >-
Optional identifier for the ID of the folder containing responses to
be retrieved. If this is omitted, all custom responses are
returned. Data format is expected to be UUID. The special value
'__root' can also be used to retrieve top level folders/responses.
- in: query
name: resourceType
schema:
type: string
enum:
- folders
- responses
- all
default: all
required: false
description: >-
Optional identifier for the ID of the type of responses to be
retrieved. A value of 'folders' will return only folder information
describing the way responses are organized. A value of 'responses'
will return only responses. A value of 'all' will return a mix of
folders and responses. Note that if the folderId parameter is
specified as well, only the resource type identified here that
exists within the specified folder will be returned. If this is
omitted, all resources are returned.
- in: query
name: searchTerm
schema:
type: string
required: false
description: >-
Search term to search for custom responses. This will search for
matching folder names, response text or both, depending on the
resourceType parameter value.
example: greetings
- in: query
name: pageToken
description: >-
This service responds with a set of custom responses. These are
divided into pages, with maxPerPage items in each page. This
parameter is the page token returned in the call prior to this one.
If this is the first call being made, this field should be omitted.
The server will respond with custom responses following the one
previously sent.
required: false
schema:
type: string
example: '3'
- in: query
name: maxPerPage
description: >-
The maximum number of custom responses the client can handle within
one page
required: false
schema:
type: integer
default: 1000
responses:
'200':
description: >-
A collection of custom response lists for this customer, sorted by
agent ID
content:
application/json:
schema:
$ref: '#/components/schemas/Responses'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/autocompose/v1/responses/customs/folder:
parameters:
- $ref: '#/components/parameters/agentId'
post:
tags:
- AutoCompose
summary: Create a response folder
description: Add a single folder for an agent
operationId: addCustomResponseFolder
requestBody:
description: The folder to be added
content:
application/json:
schema:
$ref: '#/components/schemas/Folder'
required: true
responses:
'200':
description: Acknowledgement that the folder was successfully added
content:
application/json:
schema:
$ref: '#/components/schemas/Folder'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/autocompose/v1/responses/customs/response:
parameters:
- $ref: '#/components/parameters/agentId'
post:
tags:
- AutoCompose
summary: Create a custom response
description: Add a single custom response for an agent
operationId: addCustomResponse
requestBody:
description: The custom response to be added
content:
application/json:
schema:
$ref: '#/components/schemas/NewCustomResponse'
required: true
responses:
'200':
description: Acknowledgement that the response was successfully added
content:
application/json:
schema:
$ref: '#/components/schemas/Response'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/autocompose/v1/responses/customs/response/{responseId}:
parameters:
- $ref: '#/components/parameters/agentId'
- $ref: '#/components/parameters/responseId'
put:
tags:
- AutoCompose
summary: Update a custom response
description: Update a specific custom response for an agent
operationId: updateCustomResponse
requestBody:
description: The custom response to be updated
content:
application/json:
schema:
$ref: '#/components/schemas/NewCustomResponse'
required: true
responses:
'200':
description: Acknowledgement that the custom response was successfully updated
content: {}
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
delete:
tags:
- AutoCompose
summary: Delete a custom response
description: Delete a specific custom response for an agent
operationId: deleteCustomResponse
responses:
'200':
description: Acknowledgement that the custom response was successfully deleted
content: {}
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/autocompose/v1/responses/customs/folder/{folderId}:
parameters:
- $ref: '#/components/parameters/agentId'
- $ref: '#/components/parameters/folderId'
put:
tags:
- AutoCompose
summary: Update a response folder
description: Update a folder for an agent
operationId: updateFolder
requestBody:
description: The folder to be updated
content:
application/json:
schema:
$ref: '#/components/schemas/Folder'
required: true
responses:
'200':
description: Acknowledgement that the folder was successfully updated
content: {}
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
delete:
tags:
- AutoCompose
summary: Delete a response folder
description: Delete a folder for an agent
operationId: deleteFolder
responses:
'200':
description: Acknowledgement that the custom response was successfully deleted
content: {}
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/autocompose/v1/autopilot/greetings:
parameters:
- $ref: '#/components/parameters/agentId'
get:
tags:
- AutoCompose
summary: Get autopilot greetings
description: Get autopilot greetings for an agent
operationId: getAutopilotGreetings
responses:
'200':
description: The autopilot greetings for this agent
content:
application/json:
schema:
$ref: '#/components/schemas/AutopilotGreeting'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
put:
tags:
- AutoCompose
summary: Update autopilot greetings
description: Update autopilot greetings for an agent
operationId: updateAutopilotGreetings
requestBody:
description: The updated autopilot greetings
content:
application/json:
schema:
$ref: '#/components/schemas/AutopilotGreeting'
required: true
responses:
'200':
description: Acknowledgement that the greetings were successfully updated
content:
application/json:
schema:
$ref: '#/components/schemas/AutopilotGreeting'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/autocompose/v1/autopilot/greetings/status:
parameters:
- $ref: '#/components/parameters/agentId'
get:
tags:
- AutoCompose
summary: Get autopilot greetings status
description: Get autopilot greetings status for an agent
operationId: getAutopilotGreetingsStatus
responses:
'200':
description: The autopilot greetings status for this agent
content:
application/json:
schema:
$ref: '#/components/schemas/AutopilotStatus'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
put:
tags:
- AutoCompose
summary: Update autopilot greetings status
description: Update autopilot greetings status for an agent
operationId: updateAutopilotGreetingsStatus
requestBody:
description: The updated autopilot greetings status
content:
application/json:
schema:
$ref: '#/components/schemas/AutopilotStatus'
required: true
responses:
'200':
description: Acknowledgement that the greetings status was successfully updated
content:
application/json:
schema:
$ref: '#/components/schemas/AutopilotStatus'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/autosummary/v1/intent/{conversationId}:
parameters:
- $ref: '#/components/parameters/conversationId'
get:
tags:
- AutoSummary
summary: Get conversation intent
description: >
Retrieves the primary intent of a conversation, represented by both an
intent code and a human-readable intent name. If no intent is detected,
"NO_INTENT" is returned.
This endpoint requires:
1. Intent support to be explicitly enabled for your account.
2. A valid conversationId, which is an ASAPP-generated identifier
created when using the ASAPP /conversations endpoint.
Use this endpoint to gain insights into the main purpose or topic of a
conversation.
operationId: getIntent
responses:
'200':
description: Successfully generated intent.
content:
application/json:
schema:
$ref: '#/components/schemas/IntentResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/autosummary/v1/free-text-summaries/{conversationId}:
get:
deprecated: true
tags:
- AutoSummary
summary: Get free text summary
description: >
**Deprecated**
Replaced by [POST
/autosummary/v1/free-text-summaries](/apis/autosummary/retrieve-free-text-summary)
Generates a concise, human-readable summary of a conversation.
Provide an agentExternalId if you want to get the summary for a single
agent's involvment with a conversation.
Multilingual support: You can get summaries in languages different from
English by making use of the 'Accept-Language' header.
operationId: getFreeTextSummary
parameters:
- $ref: '#/components/parameters/conversationId'
- $ref: '#/components/parameters/agentExternalId'
responses:
'200':
description: Successfully generated summary.
content:
application/json:
schema:
$ref: '#/components/schemas/FreeTextSummaryResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/autosummary/v1/feedback/free-text-summaries/{conversationId}:
parameters:
- $ref: '#/components/parameters/conversationId'
- $ref: '#/components/parameters/agentExternalId'
post:
tags:
- AutoSummary
summary: Provide feedback.
description: >
Create a feedback event with the full and updated summary. Each event is
associated with a specific summary id.
The event must contain the final summary, in the form of text.
operationId: createFeedbackEvent
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FreeTextSummaryFeedback'
responses:
'202':
description: Successfully accepted a feedback event for the summary.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/autosummary/v1/free-text-summaries:
post:
tags:
- AutoSummary
summary: Retrieve free text summary
description: >
Retrieves a concise, human-readable summary of a conversation.
Provide an agentExternalId if you want to get the summary for a single
agent's involvement with a conversation.
You can use the id from ASAPP's system (conversationId or IssueId) or
your own id (externalConversationId).
Multilingual support: You can get summaries in languages different from
English by making use of the 'Accept-Language' header.
operationId: retrieveFreeTextSummary
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FreeTextSummaryRequest'
responses:
'200':
description: Successfully retrieved free text summary.
content:
application/json:
schema:
$ref: '#/components/schemas/FreeTextSummaryResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/autosummary/v1/structured-data:
post:
tags:
- AutoSummary
summary: Retrieve structured data
description: >
Retrieves a set of structured data about a conversation that is already
known to ASAPP.
You can use the id from ASAPP's system (conversationId or IssueId) or
your own id (externalConversationId).
Provide an agentExternalId if you want to get the structured data for a
single agent's involvement with a conversation.
operationId: retrieveStructuredData
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StructuredDataRequest'
responses:
'200':
description: Successfully retrieved structured data.
content:
application/json:
schema:
$ref: '#/components/schemas/StructuredDataResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/autotranscribe/v1/streaming-url:
post:
tags:
- AutoTranscribe
operationId: getStreamingUrl
summary: Get streaming URL
description: >
Get [websocket streaming
URL](/autotranscribe/deploying-autotranscribe-via-websocket) to
transcribe audio in real time. This websocket is used to send audio to
ASAPP's transcription service and receive transcription results.
requestBody:
description: The parameters for getting streaming URL
content:
application/json:
schema:
type: object
properties:
externalId:
description: >-
Your unique identifier for the conversation. This ID should
be the same for streams of the same conversation.
type: string
example:
externalId: 8560333f-7e53-4e9f-80f3-3409a396506e
responses:
'200':
description: Successfully generated the URL for streaming
content:
application/json:
schema:
$ref: '#/components/schemas/StreamingUrl'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/conversation/v1/conversations:
post:
tags:
- Conversations
operationId: createOrUpdateConversation
summary: Create or update a conversation
description: >
Creates a new conversation or updates an existing one based on the
provided `externalId`.
Use this endpoint when:
- Starting a new conversation
- Updating conversation details (e.g., reassigning to a different agent)
If the `externalId` is not found, a new conversation will be created.
Otherwise, the existing conversation will be updated.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TimeBasedConversation'
responses:
'200':
description: Successfully created or updated conversation
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
get:
tags:
- Conversations
operationId: getConversations
summary: List conversations
description: >
Retrieves a list of conversation resources that match the specified
criteria.
You must provide at least one search criterion in the query parameters.
parameters:
- $ref: '#/components/parameters/externalId'
responses:
'200':
description: Successfully fetched conversations
content:
application/json:
schema:
$ref: '#/components/schemas/Conversations'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/conversation/v1/conversations/{conversationId}:
parameters:
- $ref: '#/components/parameters/conversationId'
get:
tags:
- Conversations
operationId: getConversation
summary: Retrieve a conversation
description: >
Retrieves the details of a specific conversation using its
`conversationId`.
This endpoint returns detailed information about the conversation,
including participants and metadata.
responses:
'200':
description: Successfully fetched conversation
content:
application/json:
schema:
$ref: '#/components/schemas/Conversation'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/conversation/v1/conversations/{conversationId}/messages:
parameters:
- $ref: '#/components/parameters/conversationId'
post:
tags:
- Conversations
operationId: createMessage
summary: Create a message
description: |
Creates a message object, adding it to an existing conversation.
Use this endpoint to record each new message in the conversation.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
responses:
'200':
description: Successfully created message in conversation
content:
application/json:
schema:
$ref: '#/components/schemas/MessagesResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
get:
tags:
- Conversations
operationId: getMessages
summary: List messages
description: |
Lists all messages within a conversation.
This messages are returned in chronological order.
responses:
'200':
description: Successfully fetched messages from a conversation
content:
application/json:
schema:
$ref: '#/components/schemas/GetMessagesResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/conversation/v1/conversations/{conversationId}/messages/{messageId}:
parameters:
- $ref: '#/components/parameters/conversationId'
- $ref: '#/components/parameters/messageId'
get:
tags:
- Conversations
operationId: getMessage
summary: Retrieve a message
description: |
Retrieve the details of a message from a conversation.
responses:
'200':
description: Successfully fetched message from a conversation
content:
application/json:
schema:
$ref: '#/components/schemas/GetMessageResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/conversation/v1/conversations/{conversationId}/messages/batch:
parameters:
- $ref: '#/components/parameters/conversationId'
post:
tags:
- Conversations
operationId: createBatchMessages
summary: Create multiple messages
description: >
This creates multiple message objects at once, adding them to an
existing conversation.
Use this endpoint when you need to add several messages at once, such as
when importing historical conversation data.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BatchMessages'
responses:
'200':
description: Successfully created messages in conversation
content:
application/json:
schema:
$ref: '#/components/schemas/BatchMessagesResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/conversation/v1/conversation/messages:
get:
tags:
- Conversations
operationId: getMessagesByExternalId
summary: List messages with an externalId
description: |
Get all messages from a conversation.
parameters:
- $ref: '#/components/parameters/externalId'
responses:
'200':
description: Successfully fetched messages from a conversation
content:
application/json:
schema:
$ref: '#/components/schemas/GetMessagesResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/conversation/v1/conversations/{conversationId}/authenticate:
post:
tags:
- Conversations
summary: Authenticate a user in a conversation
description: >
Stores customer-specific authentication credentials for use in
integrated flows.
- Can be called at any point during a conversation
- Commonly used at the start of a conversation or after mid-conversation
authentication
- May trigger additional actions, such as GenerativeAgent API signals to
customer webhooks
This API only accepts the customer-specific auth credentials; the
customer is responsible for handling
the specific authentication mechanism.
operationId: postAuthenticate
parameters:
- $ref: '#/components/parameters/conversationId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AuthObject'
responses:
'204':
description: 204 - No Content
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/fileexporter/v1/static/listfeeds:
post:
tags:
- File Exporter
operationId: listFeeds
summary: List feeds
description: |
Lists feed names for a company
responses:
'200':
description: Successfully requested feed names
content:
application/json:
schema:
$ref: '#/components/schemas/ListFeedsResponse'
'422':
$ref: '#/components/responses/UnprocessableEntity'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/fileexporter/v1/static/listfeedversions:
post:
tags:
- File Exporter
operationId: listFeedVersions
summary: List feed versions
description: |
Lists feed versions for a company
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListFeedVersionsRequest'
responses:
'200':
description: Successfully requested feed versions
content:
application/json:
schema:
$ref: '#/components/schemas/ListFeedVersionsResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/fileexporter/v1/static/listfeedformats:
post:
tags:
- File Exporter
operationId: listFeedFormats
summary: List feed formats
description: |
Lists feed formats for a company feed/version/
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListFeedFormatsRequest'
responses:
'200':
description: Successfully requested feed formats
content:
application/json:
schema:
$ref: '#/components/schemas/ListFeedFormatsResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/fileexporter/v1/static/listfeeddates:
post:
tags:
- File Exporter
operationId: listFeedDates
summary: List feed dates
description: |
Lists dates for a company feed/version/format
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListFeedDatesRequest'
responses:
'200':
description: Successfully requested feed dates
content:
application/json:
schema:
$ref: '#/components/schemas/ListFeedDatesResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/fileexporter/v1/static/listfeedintervals:
post:
tags:
- File Exporter
operationId: listFeedIntervals
summary: List feed intervals
description: |
Lists intervals for a company feed/version/format/date
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListFeedIntervalsRequest'
responses:
'200':
description: Successfully requested feed intervals
content:
application/json:
schema:
$ref: '#/components/schemas/ListFeedIntervalsResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/fileexporter/v1/static/listfeedfiles:
post:
tags:
- File Exporter
operationId: listFeedFiles
summary: List feed files
description: |
Lists files for a company feed/version/format/date/interval
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListFeedFilesRequest'
responses:
'200':
description: Successfully requested feed files
content:
application/json:
schema:
$ref: '#/components/schemas/ListFeedFilesResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/fileexporter/v1/static/getfeedfile:
post:
tags:
- File Exporter
operationId: listFeedFile
summary: Retrieve a feed file
description: >
Retrieves a feed file URL for a company
feed/version/format/date/interval/file
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GetFeedFileRequest'
responses:
'200':
description: Successfully requested feed file
content:
application/json:
schema:
$ref: '#/components/schemas/GetFeedFileResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/generativeagent/v1/analyze:
post:
tags:
- GenerativeAgent
summary: Analyze conversation
description: >
Call this API to trigger GenerativeAgent to analyze and respond to a
conversation.
This API should be called after a customer sends a message while not
speaking with a live agent. The Bot replies will not be returned on this
request; they will be delivered asynchronously via the webhook callback.
This API also adds an optional **message** field to create a message for
a given conversation before triggering the bot replies. The message
object is the exact same message used in the conversations API /message
endpoint
operationId: postAnalyze
requestBody:
required: true
content:
application/json:
schema:
type: object
description: >-
The parameters for triggering the analysis and response to a
conversation
properties:
streamId:
type: string
description: >-
The id associated with the connection where the responses
should be sent to.
example: 97555020-0276-435f-8104-c378221ba292
conversationId:
type: string
description: Internal conversation identifier from ASAPP
example: 01BX5ZZKBKACTAV9WEVGEMMVS0
taskName:
type: string
description: Name of the task to be used in the analysis
example: UpgradePlan
inputVariables:
type: object
description: Input variables to be used as context in the analysis.
example:
call_context: Customer called to upgrade their current plan to GOLD
customer_info:
current_plan: SILVER
customer_since: '2020-01-01'
message:
$ref: '#/components/schemas/Message'
channelType:
description: Channel type used by the current request (digital or voice)
type: string
enum:
- digital
- voice
example: digital
required:
- conversationId
example:
conversationId: 01BX5ZZKBKACTAV9WEVGEMMVS0
message:
text: Hello, I would like to upgrade my internet plan to GOLD.
sender:
role: agent
externalId: 123
timestamp: '2021-11-23T12:13:14.555Z'
taskName: UpgradePlan
inputVariables:
context: Customer called to upgrade their current plan to GOLD
customer_info:
current_plan: SILVER
customer_since: '2020-01-01'
channelType: digital
responses:
'200':
description: >-
Successfully triggered the bot to analyze and respond to a
conversation
content:
application/json:
schema:
type: object
description: >-
Conversation identifier and message identifier if passed in
the request
properties:
conversationId:
type: string
description: Internal conversation identifier from ASAPP
example: 01BX5ZZKBKACTAV9WEVGEMMVS0
messageId:
type: string
description: Internal message identifier from ASAPP
example: 01BX5ZZKBKACTAV9WEVGEMMVS1
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/generativeagent/v1/streams:
post:
tags:
- GenerativeAgent
summary: Create stream URL
description: >
This API creates a generative agent event streaming URL to start a
streaming connection (SSE).
This API should be called when the client boots-up to request a
streaming_url, before it calls endpoints whose responses are delivered
asynchronously (and most likely before calling any other endpoint).
Provide the streamId to reconnect to a previous stream.
operationId: postStreams
requestBody:
required: true
content:
application/json:
schema:
type: object
description: The parameters to be associated with a given connection.
properties:
streamId:
type: string
description: >-
streamId to be associated with the streaming connection. If
not present, the llm-bot will provide one.
example: 97555020-0276-435f-8104-c378221ba292
example:
streamId: 97555020-0276-435f-8104-c378221ba292
responses:
'200':
description: Successfully generated a new streaming URL.
content:
application/json:
schema:
type: object
description: >-
Streaming URL with its identifier and possible SSE
message-types to be received.
properties:
streamId:
type: string
description: >-
If it was provided in the request, this field will just
reaffirm the value. Otherwise, a newly generated one will
be provided.
example: 97555020-0276-435f-8104-c378221ba292
streamingUrl:
type: string
description: >-
URL for opening the SSE session. It may be used once, and
is valid for only 30 seconds.
example: >-
https://ws-co82129c.test.asapp.com/push-api/connect/sse\?token\=
messageTypes:
type: array
items:
type: string
description: Possible message types to be received from the agent.
example:
- generative-agent-message
required:
- streamId
- streamingUrl
- messageTypes
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/generativeagent/v1/state:
get:
tags:
- GenerativeAgent
summary: Get GenerativeAgent state
description: >
This API provides the current state of the generative agent for a given
conversation.
operationId: getState
parameters:
- in: query
name: criteria
description: Search criteria
style: form
explode: true
schema:
type: object
properties:
externalId:
type: string
description: >-
External conversation identifier from your external chat /
voice system
additionalProperties: false
minProperties: 1
responses:
'200':
description: Successfully fetched state of generative agent for a conversation
content:
application/json:
schema:
type: object
properties:
state:
type: string
enum:
- ready
- processing
- waitingForConfirmation
- waitingForAuth
- transferredToAgent
- transferredToSystem
description: |
The last status of the conversation:
* `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'
security:
- API-ID: []
API-Secret: []
/v1/health:
get:
tags:
- Health Check
summary: Check ASAPP's API's health.
description: >
The API Health check endpoint enables you to check the operational
status of our API platform.
responses:
'200':
description: Successfully retrieved response from Health Server.
content:
application/json:
schema:
$ref: '#/components/schemas/health-check'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/knowledge-base/v1/submissions:
post:
tags:
- Knowledge Base
summary: Create a submission
description: >-
Initiate a request to add a new article or update an existing one.
The provided title and content will be processed to create the final
version of the submission.
A `submission` is the programmatic creation or editing of an article.
All submissions need to be approved by a human in the ASAPP Console in
order to be applied.
All content in a submission may be refined by our AI in order to make it
easy to be used by GenerativeAgent
Head to [Connecting your Knowledge
Base](/generativeagent/configuring/connecting-your-knowledge-base#step-1-importing-your-knowledge-base)
to see how to enter the API from the ASAPP Console.
operationId: createSubmission
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubmissionRequest'
responses:
'201':
description: Submission successfully created
content:
application/json:
schema:
$ref: '#/components/schemas/Submission'
example:
id: fddd060c-22d7-4aed-acae-8f8dcc093a88
articleId: 8f8dcc09-22d7-4aed-acae-fddd060c3a88
submittedAt: '2024-12-12T00:00:00'
title: 5G Data Plan
content: >-
Our 5G data plans offer lightning-fast speeds and generous
data allowances. The Basic 5G plan includes 50GB of data per
month, while our Unlimited 5G plan offers truly unlimited data
with no speed caps. Both plans include unlimited calls and
texts within the country. International roaming can be added
for an additional fee.
url: https://example.com/5g-data-plans
metadata:
- key: department
value: Customer experience
queryExamples:
- What 5G plans do you offer?
- Is there an unlimited 5G plan?
additionalInstructions:
- clarificationInstruction: Emphasize that 5G coverage may vary by location
exampleResponse: >-
Our 5G plans offer great speeds and data allowances, but
please note that 5G coverage may vary depending on your
location. You can check coverage in your area on our
website.
status: PENDING_REVIEW
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/knowledge-base/v1/submissions/{id}:
get:
tags:
- Knowledge Base
summary: Retrieve a submission
description: >
This service retrieves the details of a specific submission using its
unique identifier.
A `submission` is the programmatic creation or editing of an article.
All submissions need to be approved by a human in the ASAPP Console in
order to be applied.
All content in a submission may be refined by our AI in order to make it
easy to be used by GenerativeAgent
Head to [Connecting your Knowledge
Base](/generativeagent/configuring/connecting-your-knowledge-base#step-1-importing-your-knowledge-base)
to see how to enter the API from the ASAPP Console.
operationId: getSubmission
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The unique identifier for the submission to be retrieved.
example: fddd060c-22d7-4aed-acae-8f8dcc093a88
responses:
'200':
description: Submission successfully retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/Submission'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/knowledge-base/v1/articles/{id}:
get:
tags:
- Knowledge Base
summary: Retrieve an article
description: >
Fetch a specific article by its unique identifier.
If the article has not been created because the associated submission
was not approved, a 404 status will be returned.
operationId: getArticle
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The unique identifier for the article to be retrieved.
example: 8f8dcc09-22d7-4aed-acae-fddd060c3a88
responses:
'200':
description: Article successfully retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/Article'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/metadata-ingestion/v1/single-agent-metadata:
post:
tags:
- Metadata
operationId: singleAgentMetadata
summary: Add an agent metadata
description: |
Add metadata attributes of one agent
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentMetadata'
responses:
'200':
$ref: '#/components/responses/SuccessForSingle'
'400':
$ref: '#/components/responses/BadRequestForSingle'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/metadata-ingestion/v1/many-agent-metadata:
post:
tags:
- Metadata
operationId: manyAgentMetadata
summary: Add multiple agent metadata
description: >
Add multiple agent metadata items; submit items in a batch in one
request
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentMetadataMany'
responses:
'200':
$ref: '#/components/responses/SuccessForBatch'
'400':
$ref: '#/components/responses/BadRequestForBatch'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/metadata-ingestion/v1/single-convo-metadata:
post:
tags:
- Metadata
operationId: singleConvoMetadata
summary: Add a conversation metadata
description: |
Add metadata attributes of one issue/conversation
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationMetadata'
responses:
'200':
$ref: '#/components/responses/SuccessForSingle'
'400':
$ref: '#/components/responses/BadRequestForSingle'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/metadata-ingestion/v1/many-convo-metadata:
post:
tags:
- Metadata
operationId: manyConversationMetadata
summary: Add multiple conversation metadata
description: >
Add multiple issue/conversation metadata items; submit items in a batch
in one request
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationMetadataMany'
responses:
'200':
$ref: '#/components/responses/SuccessForBatch'
'400':
$ref: '#/components/responses/BadRequestForBatch'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/metadata-ingestion/v1/single-customer-metadata:
post:
tags:
- Metadata
operationId: singleCustomerMetadata
summary: Add a customer metadata
description: |
Add metadata attributes of one customer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerMetadata'
responses:
'200':
$ref: '#/components/responses/SuccessForSingle'
'400':
$ref: '#/components/responses/BadRequestForSingle'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/metadata-ingestion/v1/many-customer-metadata:
post:
tags:
- Metadata
operationId: manyCustomerMetadata
summary: Add multiple customer metadata
description: >
Add multiple customer metadata items; submit items in a batch in one
request
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerMetadataMany'
responses:
'200':
$ref: '#/components/responses/SuccessForBatch'
'400':
$ref: '#/components/responses/BadRequestForBatch'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/mg-autotranscribe/v1/start-streaming:
post:
tags:
- AutoTranscribe Media Gateway
operationId: startStreaming
summary: Start streaming
description: >
This starts the transcription of the audio stream.
Use in conjunction with the
[stop-streaming](/apis/media-gateway/stop-streaming-audio) endpoint to
control when transcription occurs for a given call. This allow you to
prevent transcription of sensitive parts of a conversation, such as
entering PCI data.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StartStreamingRequest'
responses:
'200':
description: Router processed the request, details are in the response body
content:
application/json:
schema:
$ref: '#/components/schemas/StartStreamingResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/mg-autotranscribe/v1/stop-streaming:
post:
tags:
- AutoTranscribe Media Gateway
operationId: stopStreaming
summary: Stop streaming
description: >
This stops the transcription of the audio stream.
Use in conjunction with the
[start-streaming](/apis/media-gateway/start-streaming-audio) endpoint to
control when transcription occurs for a given call. This allow you to
prevent transcription of sensitive parts of a conversation, such as
entering PCI data.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StopStreamingRequest'
responses:
'200':
description: Router processed the request, details are in the response body
content:
application/json:
schema:
$ref: '#/components/schemas/StopStreamingResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
/mg-autotranscribe/v1/twilio-media-stream-url:
get:
tags:
- AutoTranscribe Media Gateway
operationId: getTwilioMediaStreams
summary: Get Twilio media stream url
description: >-
Returns url where [Twilio media
stream](/autotranscribe/deploying-autotranscribe-for-twilio) should be
sent to.
responses:
'200':
description: OK - Twilio media stream url in the response body
content:
application/json:
schema:
$ref: '#/components/schemas/GetTwilioMediaStreamsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
$ref: '#/components/responses/DefaultError'
security:
- API-ID: []
API-Secret: []
components:
securitySchemes:
API-ID:
type: apiKey
in: header
name: asapp-api-id
API-Secret:
type: apiKey
in: header
name: asapp-api-secret
parameters:
agentId:
name: agentId
description: Identifier of the agent, data format is expected to be UUID
in: query
required: true
schema:
type: string
responseId:
name: responseId
description: Identifier of the response, data format is expected to be UUID
in: path
required: true
schema:
type: string
folderId:
name: folderId
description: Identifier of the folder, data format is expected to be UUID
in: path
required: true
schema:
type: string
conversationId:
name: conversationId
description: The identifier for a conversation.
in: path
required: true
schema:
type: string
pattern: ^[A-Z0-9]+$
agentExternalId:
name: agentExternalId
description: Your unique identifier for the agent.
in: query
required: false
schema:
type: string
externalId:
name: externalId
description: Your identifier for a conversation.
in: query
required: true
schema:
type: string
example:
externalId: id-111
messageId:
name: messageId
description: Internal message identifier from ASAPP
in: path
required: true
schema:
type: string
pattern: ^[A-Z0-9]+$
responses:
BadRequest:
description: 400 - Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
DefaultError:
description: 500 - Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/DefaultErrorResponse'
Unauthorized:
description: 401 - Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
Forbidden:
description: 403 - Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponse'
NotFound:
description: 404 - Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
Conflict:
description: 409 - Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictResponse'
RequestEntityTooLarge:
description: 413 - Request Entity Too Large
content:
application/json:
schema:
$ref: '#/components/schemas/RequestEntityTooLargeResponse'
UnprocessableEntity:
description: 422 - Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntity'
TooManyRequests:
description: 429 - Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
ServiceUnavailable:
description: 503 - Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceUnavailableResponse'
SuccessForSingle:
description: >
200 - Success
Submit a single item to the service to be ingested. Record can be traced
back to the submitted record by the eventId.
A message sent status will be returned with no error message for
successful input checks.
content:
application/json:
schema:
$ref: '#/components/schemas/AddMetadataResponse'
SuccessForBatch:
description: >
200 - Success | Partial Success
Submit a batch of items to the service to be ingested. Record can be
traced back to the submitted record by the eventId.
If any of the records encounter issue during the ingestion, a message
sent status will be returned with an error message for each record.
A 200 success is returned as long as there is one item ingested
successfully, i.e., "partial success".
content:
application/json:
schema:
$ref: '#/components/schemas/AddManyMetadataResponse'
BadRequestForSingle:
description: >
400 - Bad request
Submit a single item to the service to be ingested. Record can be traced
back to the submitted record by the eventId.
A message sent status will be returned with an error message for bad
input failure.
content:
application/json:
schema:
$ref: '#/components/schemas/AddMetadataResponse'
BadRequestForBatch:
description: >
400 - Bad request
Submit a batch of items to the service to be ingested. Record can be
traced back to the submitted record by the eventId.
If any of the records encounter issue during the ingestion, a message
sent status will be returned with an error message for each record.
All items in the batch encountered client input validation failures.
content:
application/json:
schema:
$ref: '#/components/schemas/AddManyMetadataResponse'
schemas:
Suggestion:
description: Suggestion
type: object
properties:
text:
type: string
description: Suggestion text for the agent
example: Hello John, how can I help you?
templateText:
type: string
description: >-
Suggestion text with placeholders for metadata instead of the values
filled in
example: Hello {NAME}, how can I help you?
title:
type: string
description: The title of the response
example: Greeting
PhraseCompletion:
description: >-
Completion of the phrase the agent is currently typing, to be displayed
inline in the composer
type: object
properties:
text:
type: string
description: >-
Phrase completion text for the agent (this may be empty if the model
does not have a confident prediction for how to complete the
message)
example: Hello, how can I help you?
AutopilotMessage:
description: Recommended message for the agent to autopilot send.
type: object
properties:
text:
type: string
description: Text of the message
example: Hello John, how can I help you?
templateText:
type: string
description: >-
Text of the message with placeholders for metadata instead of the
values filled in
example: Hello {NAME}, how can I help you?
title:
type: string
description: The title of the message
example: Greeting
delaySeconds:
type: integer
description: >-
Delay before the message is sent to the customer, during which a
preview of the message is shown to the agent and they can choose to
cancel it
example: 5
triggerAfterSeconds:
type: integer
description: >-
Delay before showing the preview and starting the countdown to send
the message
example: 0
Suggestions:
description: Suggestions for next agent message
type: object
properties:
id:
description: >-
ID for the suggestions that were returned (to be used in analytics
events)
type: string
message:
$ref: '#/components/schemas/MessagesResponse'
suggestions:
type: array
items:
$ref: '#/components/schemas/Suggestion'
phraseCompletion:
$ref: '#/components/schemas/PhraseCompletion'
autopilotMessage:
$ref: '#/components/schemas/AutopilotMessage'
ProfanityResult:
description: ProfanityResult
type: object
properties:
hasProfanity:
description: A boolean value describing if the text contains a curse word.
type: boolean
example: false
SpellcheckQuery:
type: object
properties:
text:
description: text being typed by the agent, already entered into the composer
type: string
typingEvent:
type: object
properties:
cursorStart:
description: >-
position of the cursor before the typing event, to identify if a
word is being typed
type: integer
cursorEnd:
description: >-
position of the cursor after the typing event, to identify if a
word is being typed
type: integer
required:
- cursorStart
- cursorEnd
userDictionary:
description: Words that should not be corrected if they are present on the text
type: array
items:
type: string
required:
- text
- typingEvent
example:
text: 'How is tihs '
typingEvent:
cursorStart: 11
cursorEnd: 12
userDictionary:
- Hellooo
SpellcheckCorrection:
type: object
properties:
id:
description: >-
ID for the spelling correction that was returned (to be used in
analytics events)
type: string
example: 01BX5ZZKBKACTAV9WEVGEMMVS1
misspelledText:
description: misspelling that needs to be replaced with the corrected text
type: string
example: tihs
correctedText:
type: string
description: correction for the misspelling
example: this
position:
type: integer
description: position where the misspelling starts
example: 7
MessageSentEvent:
description: >-
Analytics event describing the agent's usage of AutoCompose features
while composing a message (we sometimes refer to these as augmentation
features, because they augment the agent's work).
Note that many of the fields are not technically required according to
this spec. This does not mean that they can omitted arbitrarily. They
should all be set, when they relevant for AutoCompose features a
particular ASAPP customer is using and the data is available. For some
use cases, some fields are not relevant (for example,
phraseAutocompletePresentedCt is only relevant if phrase completions are
being used). In other cases, the field may relevant but the data might
not be avaialble (for example, if the request for suggestions returns
too late, it might not be possible set initialSuggestionsId). The
customer should try to fill in all relevant fields when they can; this
information enables ASAPP to report on the performance of our features
and to improve their perforamnce over time.
When a field is omitted, it will take on a default value in the event
data. String fields default to empty string and numeric fields default
to 0.
type: object
required:
- conversationId
- messageId
- augmentationType
example:
conversationId: 01G1167H5FFQ47SMSRYGKBW7HM
messageId: 01BX5ZZKBKACTAV9WEVGEMMVS1
augmentationType:
- AUTOSUGGEST
properties:
conversationId:
description: The ASAPP conversation id for the conversation.
type: string
example: 01G1167H5FFQ47SMSRYGKBW7HM
messageId:
description: >
The ASAPP ID of the message that was sent. This is required for
every event,
to enable correlating the analytics event with the message that was
sent.
type: string
example: 01BX5ZZKBKACTAV9WEVGEMMVS1
augmentationType:
description: >
Types of AutoCompose augmentation features used for composing the
message. Ordering of augmentations and repeated uses of an
augmentation type are preserved. This is required, so that the usage
of
AutoCompose features can be measured.
type: array
items:
type: string
enum:
- FREEHAND
- AUTOSUGGEST
- AUTOCOMPLETE
- PHRASE_AUTOCOMPLETE
- CUSTOM_DRAWER
- CUSTOM_INSERT
- GLOBAL_INSERT
- FLUENCY_APPLY
- FLUENCY_UNDO
example:
- AUTOSUGGEST
- PHRASE_AUTOCOMPLETE
- FLUENCY_APPLY
numEdits:
description: >
Number of keystrokes of editing the agent did after selecting a
full-message suggestions
(one of the suggestions in the suggestions array, not
phraseCompletion). Selecting a
full-message suggestion resets the counter. Accepting a phrase
completion by hitting tab
or right arrow increments the counter just like other keystrokes.
The idea is to have a rough
idea of how much editing the agent had to do after selecting a
full-message suggestion (in the
ideal case, the message was satisfactory to send as-is and numEdits
equals 0).
type: integer
example: 2
selectedSuggestionText:
description: |
If the agent used a full-message suggestion to compose this message,
this is the text of the suggestion
type: string
example: How can I help you today?
selectedSuggestionsId:
description: >
If the agent used a full-message suggestion to compose this message,
this is the ID of
the set of suggestions that the suggestion came from. This helps
ASAPP assoicate the MessageSent
event with events emitted by AutoCompose internally. If the agent
did not use a full-message
suggestion, this field can left blank.
type: string
example: 4d2fd982640c311394008259594399a1
selectedSuggestionIndex:
description: >
If the agent used a full-message suggestion to compose this message,
this is the
index of the selected suggestion in the set of suggestions that the
agent used, starting
from 1 for the top suggestion, 2 for the second from the top, and so
on. This should be
omitted if no suggestion was selected, but it is required if the
agent selected
a suggestion, to enable identifying which of the suggestions was
used.
type: integer
example: 1
initialSuggestionsId:
description: >
The ID for the first set of suggestions the agent saw while
composing this message.
This is required for every event, if suggestions were shown to the
agent. If for some reason
suggestions were not available, it can be omitted.
type: string
example: 5e9491b203e6ecccfef964e26fb1a5d3
timeToAction:
description: |
Number of seconds between the agent sending their previous
message and their first action for composing this message.
An agent action is when one of the following occur:
- Typing in the composer
- Selecting a suggestion
- Using a phrase completion
- Inserting a custom or global response from the library
- Pasting a text into the composer
type: number
example: 1.891412
craftingTime:
description: |
Number of seconds between the agent's first action
and last action for composing this message.
type: number
example: 10.9472
dwellTime:
description: |
Number of seconds between the agent's last action
for composing this message and the message being sent.
type: number
example: 4.132985
phraseAutocompletePresentedCt:
description: |
Number of phrase autocomplete suggestions presented
to the agent.
type: integer
example: 3
phraseAutocompleteSelectedCt:
description: |
Number of phrase autocomplete suggestions selected
by the agent.
type: integer
example: 1
MessageAnalyticEvent:
description: >
Analytics event reporting actions the agent performed while composing a
message.
type: object
required:
- type
- suggestionsId
example:
type: suggestion-1-inserted
suggestionsId: 4d2fd982640c311394008259594399a1
properties:
type:
type: string
example: suggestion-1-inserted
enum:
- suggestion-1-inserted
- suggestion-2-inserted
- suggestion-3-inserted
- phrase-completion-accepted
- spellcheck-applied
- spellcheck-undone
- custom-response-drawer-inserted
- custom-panel-inserted
- global-panel-inserted
description: |
The type of message analytic event.
suggestionsId:
description: >
For suggestion-1-inserted, suggestion-2-inserted,
suggestion-3-inserted, phrase-completion-accepted,
this is the `id` from the Suggestions API response that the agent
interacted with. This allows ASAPP to connect the event with
additional information (e.g., the
text of the suggestion that was inserted).
For spellcheck-undone, custom-response-drawer-inserted,
custom-panel-inserted, and global-panel-inserted, this is the
`id` of the most recent Suggestions API response in this
conversation.
In all of these cases, providing the Suggestions `id` allows ASAPP
to associate the event with the message the agent
is composing. During the normal flow of using the AutoCompose API,
the Suggestions API will always have been called
at least once since the previous agent message by the time a message
analytic event occurs, and each time the
Suggestions API is called, ASAPP records the ID of the previous
agent message. Thus, the Suggestions `id` in the analytic event
links back to the previous agent message. This permits
the analytic event to later be linked to the new message the agent
is composing, even though the event occurs before
the message is sent.
type: string
example: 4d2fd982640c311394008259594399a1
spellcheckApplied:
type: object
description: |
The details about the spellcheck applied analytic event
nullable: true
properties:
correctionId:
description: The ID of the spellcheck correction API response
type: string
example: 75bc8912c66842594375bc8912c66842
required:
- correctionId
spellcheckUndone:
type: object
description: |
The details about the spellcheck undone analytic event
nullable: true
properties:
correctionId:
description: The ID of the spellcheck correction API response
type: string
example: 75bc8912c66842594375bc8912c66842
required:
- correctionId
customResponseDrawerInserted:
type: object
description: The details about the custom response drawer inserted analytic event
nullable: true
properties:
query:
description: >
The query the agent typed to search in the custom response
drawer
type: string
example: Hi
text:
description: >
The text of the custom response the agent inserted from the
custom response drawer
type: string
example: Hi, I'm Alice. How can I help you today?
required:
- query
- text
customPanelInserted:
type: object
description: The details about the custom panel inserted analytic event
nullable: true
properties:
text:
description: >
The text of the custom response the agent inserted using the
custom response panel
type: string
example: Hi, I'm Alice. How can I help you today?
required:
- text
globalPanelInserted:
type: object
description: The details about the global panel inserted analytic event
nullable: true
properties:
text:
description: >
The text of the custom response the agent inserted using the
global response panel
type: string
example: How can I help you today?
required:
- text
Settings:
type: object
properties:
suggestionsWhileTypingDisabled:
type: boolean
description: >-
if true, suggestions endpoint should not be called while agent is
typing
phraseCompletionsDisabled:
type: boolean
description: >-
if true, phraseCompletion from suggestions endpoint should not be
shown to the agent
spellcheckDisabled:
type: boolean
description: >-
if true, spelling corrections endpoint should not be called while
agent is typing
autopilotGreetingsDisabled:
type: boolean
description: >-
if true, autopilot greetings should not be available for
configuration
autocomposeDisabled:
type: boolean
description: >
if true, all AutoCompose features should be disabled (regardless of
the other settings); this
is intended for use in A/B tests in which a control group of agents
is not exposed to AutoCompose
Response:
type: object
properties:
id:
type: string
description: The ID of this response, data format is UUID
readOnly: true
text:
type: string
description: The text of the response
title:
type: string
description: >-
The title of the response. Always non-empty for custom responses,
but may be empty for other types of responses (global and organic).
folderId:
type: string
description: the ID of the folder the response belongs to.
metadata:
type: array
items:
type: object
properties:
name:
type: string
description: the name of this metadata item
allowedValues:
type: array
items:
type: string
description: the list of allowed values for this metadata item
description: >-
free-form metadata, in the form of a map of keys to lists of allowed
values for each key, that can be added to any response. At least one
of the values in the list for each key included here must match
what gets sent when requesting suggestions, so that responses can be
filtered appropriately.
NewCustomResponse:
type: object
properties:
text:
type: string
description: The text of the response
title:
type: string
description: The title of the response
folderId:
type: string
description: >-
the ID of the folder the response belongs to (used for custom
responses).
metadata:
type: array
items:
type: object
properties:
name:
type: string
description: the name of this metadata item
allowedValues:
type: array
items:
type: string
description: the list of allowed values for this metadata item
description: >-
free-form metadata, in the form of a map of keys to lists of allowed
values for each key, that can be added to any response. At least one
of the values in the list for each key included here must match
what gets sent when requesting suggestions, so that responses can be
filtered appropriately.
required:
- text
- title
example:
text: fold text
title: folder title
folderId: '123'
Responses:
type: object
description: A set of responses and folders for an agent
properties:
responsesList:
type: array
description: the list of responses with their associated metadata
items:
$ref: '#/components/schemas/Response'
folderList:
type: array
description: the list of folders
items:
$ref: '#/components/schemas/Folder'
pageToken:
type: string
description: the token to the next page if there is one, otherwise empty
Folder:
type: object
description: A folder of responses
properties:
id:
type: string
description: The ID of the folder
readOnly: true
parentFolderId:
type: string
description: The ID of the parent folder.
name:
type: string
description: the name of the folder
required:
- name
example:
id: '123'
parentFolderId: '456'
name: folder name
GlobalResponsesVersion:
type: object
properties:
id:
type: string
description: The ID of this version of the global responses
readOnly: true
description:
type: string
description: A human-readable description of the version
GlobalResponsesWithVersion:
type: object
properties:
responses:
$ref: '#/components/schemas/Responses'
version:
$ref: '#/components/schemas/GlobalResponsesVersion'
AutopilotGreeting:
type: object
description: Autopilot greetings for an agent
properties:
greetingGeneric:
type: string
description: Generic greeting, without any template data
greetingCustomerName:
type: string
description: Greeting with template for customer name
required:
- greetingGeneric
- greetingCustomerName
example:
greetingGeneric: Welcome!
greetingCustomerName: Welcome {NAME}!
AutopilotStatus:
type: object
description: Autopilot status for an agent
properties:
enabled:
type: boolean
description: If true, autopilot is enabled
required:
- enabled
example:
enabled: true
SuggestionsRequest:
description: >-
A suggestions request with an optional message to add to the
conversation
type: object
properties:
query:
description: text the agent has already entered into the composer
type: string
message:
$ref: '#/components/schemas/Message'
example:
query: Hello, how can
message:
text: Hello, I would like to upgrade my internet plan to GOLD.
sender:
role: customer
externalId: customer-x
timestamp: '2023-06-01T19:16:55.706Z'
ParticipantRole:
description: >
A participant role, usually the customer or an agent for human
participants. System participant is also allowed but keep in mind
that this role won't be considered a participant in a conversation, just
a message sender.
type: string
enum:
- agent
- customer
- system
Participant:
description: Represents a participant in the conversation.
type: object
properties:
role:
$ref: '#/components/schemas/ParticipantRole'
description: The role of the participant in the conversation.
externalId:
type: string
description: >-
The unique identifier for the participant in your external system.
This should be consistent across all interactions for the same
individual.
required:
- role
- externalId
Message:
description: Represents a single message within a conversation.
type: object
properties:
text:
type: string
minLength: 1
description: The content of the message.
sender:
$ref: '#/components/schemas/Participant'
description: Information about the participant who sent the message.
timestamp:
type: string
format: date-time
description: >-
The time when the message was sent. Include the timezone, otherwise
UTC will be assumed.
required:
- text
- sender
- timestamp
example:
text: Hello, I would like to upgrade my internet plan to GOLD.
sender:
role: agent
externalId: 123
timestamp: '2021-11-23T12:13:14.555Z'
DefaultErrorDetails:
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
DefaultErrorResponse:
description: Default error response
type: object
properties:
error:
$ref: '#/components/schemas/DefaultErrorDetails'
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 500-01
message: Internal server error
MessagesResponse:
description: Response for messages
type: object
properties:
id:
type: string
description: Message ID to be used for analytics
example:
id: 01BX5ZZKBKACTAV9WEVGEMMVS1
BadRequestResponse:
description: Bad request response
type: object
properties:
error:
$ref: '#/components/schemas/DefaultErrorDetails'
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 400-01
message: Bad request
UnauthorizedResponse:
description: Unauthorized response
type: object
properties:
error:
$ref: '#/components/schemas/DefaultErrorDetails'
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 401-01
message: Unauthorized
ForbiddenResponse:
description: Forbidden response
type: object
properties:
error:
$ref: '#/components/schemas/DefaultErrorDetails'
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 403-01
message: Forbidden Response
NotFoundResponse:
description: Not Found response
type: object
properties:
error:
$ref: '#/components/schemas/DefaultErrorDetails'
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 404-01
message: Not Found
ConflictResponse:
description: Conflict response
type: object
properties:
error:
$ref: '#/components/schemas/DefaultErrorDetails'
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 409-01
message: Conflict
RequestEntityTooLargeResponse:
description: Request Entity Too Large response
type: object
properties:
error:
$ref: '#/components/schemas/DefaultErrorDetails'
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 413-01
message: Request Entity Too Large
UnprocessableEntity:
description: Unprocessable Entity response
type: object
properties:
error:
$ref: '#/components/schemas/DefaultErrorDetails'
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 422-01
message: Unprocessable Entity
TooManyRequestsResponse:
description: Too Many Requests response
type: object
properties:
error:
$ref: '#/components/schemas/DefaultErrorDetails'
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 429-01
message: Too Many Requests
ServiceUnavailableResponse:
description: Service Unavailable response
type: object
properties:
error:
$ref: '#/components/schemas/DefaultErrorDetails'
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 503-01
message: Service Unavailable
FreeTextSummaryRequest:
type: object
oneOf:
- type: object
properties:
conversationId:
type: string
pattern: ^[A-Z0-9]+$
description: The identifier of the conversation from ASAPP's system.
agentExternalId:
type: string
description: Your unique identifier for the agent.
required:
- conversationId
- type: object
properties:
externalConversationId:
type: string
description: >-
Your unique identifier for the conversation. This must match to
the `externalConversationId` you used in the Conversations API.
agentExternalId:
type: string
description: Your unique identifier for the agent.
required:
- externalConversationId
- type: object
properties:
issueId:
type: string
description: >-
The identifier of the conversation from ASAPP's Messaging
Platform.
agentExternalId:
type: string
description: Your unique identifier for the agent.
required:
- issueId
example:
conversationId: 01GCS2AA9447BCQANJF2SXXVA0
agentExternalId: agent-111
FreeTextSummaryResponse:
type: object
properties:
conversationId:
type: string
description: >-
The unique identifier of the conversation for which the summary was
generated.
summaryId:
type: string
description: >
A unique identifier for this specific summary.
• Each summary request generates a new summary with a new
`summaryId`, even for the same conversation.
• The entire summary content is regenerated with each request.
• Use this ID when providing feedback on the summary.
summaryText:
type: string
description: |
The generated free-text summary of the conversation.
StructuredDataRequest:
type: object
oneOf:
- type: object
properties:
conversationId:
type: string
pattern: ^[A-Z0-9]+$
description: The identifier of the conversation from ASAPP's system.
agentExternalId:
type: string
description: >
Your agent identifier. When provided, retrieval is limited to
conversation segments involving the specified agent.
required:
- conversationId
- type: object
properties:
externalConversationId:
type: string
description: >-
Your unique identifier for the conversation. This must match to
the `externalConversationId` you used in the Conversations API.
agentExternalId:
type: string
description: >
Your agent identifier. When provided, retrieval is limited to
conversation segments involving the specified agent.
required:
- externalConversationId
- type: object
properties:
issueId:
type: string
description: >-
The identifier of the conversation from ASAPP's Messaging
Platform.
agentExternalId:
type: string
description: >
Your agent identifier. When provided, retrieval is limited to
conversation segments involving the specified agent.
required:
- issueId
example:
conversationId: 01GCS2XA9446BCQANJF2SXXVA0
agentExternalId: agent-111
StructuredDataResponse:
type: object
properties:
conversationId:
type: string
description: The id of the conversation.
id:
type: string
description: >
A unique identifier for this specific structured data.
• Each structured data request generates a new set with a new `id`,
even for the same conversation.
• The entire structured data content is regenerated with each
request.
• Use this ID when providing feedback on the structured data.
structuredDataMetrics:
type: array
items:
type: object
properties:
id:
type: string
description: |
A unique code assigned to this structured data field.
name:
type: string
description: |
The human readable name of this structured data field
value:
type: string
description: |
The value of this structured data field
description: The result of the structured data, which is a list of field values.
example:
conversationId: 01GCS2XA9447BCQANJF2SXXVA0
id: 0083d936-ff70-49fc-ac19-74f1246d8b27
structuredDataMetrics:
- id: q_abc_123
name: Issue Resolved
value: 'Yes'
- id: q_xyz_123
name: Issue Escalated
value: 'No'
- id: q_abc_124
name: Sales Made
value: 'No'
- id: e_abc_123
name: Account Number
value: 8999246118
IntentResult:
type: object
properties:
code:
type: string
description: >-
The machine-readable code for the given conversation. If no intent
was found, then "NO_INTENT" is returned.
name:
type: string
description: The human-readable name of the intent for the given conversation.
IntentResponse:
type: object
properties:
conversationId:
type: string
description: The id of the conversation.
intent:
$ref: '#/components/schemas/IntentResult'
description: |
An object containing the determined intent for the conversation.
FreeTextSummaryFeedback:
type: object
description: >
Information regarding the updated free-text summary. It must contain the
full updated summary as a string.
properties:
externalConversationId:
description: >
Your unique identifier for the conversation. This must match to the
`externalConversationId` you used in the Conversations API.
type: string
summaryId:
description: |
The identifier of the summary you are providing feedback on.
type: string
summaryText:
description: The full text of the final summary.
type: string
required:
- summaryId
- summaryText
example:
externalConversationId: 01GCS2XA9447BCQANJF2SXXVA0
summaryId: 0083d936-ff70-49fc-ac19-74f1246d8b27
summaryText: |
The customer has issues with his symmetric internet service.
The customer explained the service has not enough bandwidth.
The customer explained the service has not enough bandwidth.
The agent explained how to run a diagnosis.
The customer ran the diagnosis.
StreamingUrl:
description: Get streaming url
type: object
properties:
streamingUrl:
type: string
description: Streaming websocket URL
Conversation:
description: Represents a conversation between an agent and a customer.
type: object
properties:
id:
type: string
description: The unique identifier for the conversation within the ASAPP system.
externalId:
type: string
description: >-
The unique identifier for the conversation in your external chat or
voice system.
agent:
type: object
description: Information about the agent participating in the conversation.
properties:
externalId:
type: string
description: The unique identifier for the agent in your external system.
name:
type: string
description: The display name of the agent.
required:
- externalId
customer:
type: object
description: Information about the customer participating in the conversation.
properties:
externalId:
type: string
description: The unique identifier for the customer in your external system.
name:
type: string
description: The display name of the customer.
required:
- externalId
metadata:
type: object
additionalProperties:
type: string
description: >-
Additional key-value pairs to store custom metadata about the
conversation. Use this for filtering or categorization purposes.
required:
- externalId
- customer
example:
id: 01BX5ZZKBKACTAV9WEVGEMMVRZ
externalId: id-111
agent:
externalId: agent-111
name: agent-x
customer:
externalId: customer-x
name: customer-name-x
metadata:
organizationalGroup: some-group
subdivision: some-division
queue: some-queue
TimeBasedConversation:
description: >-
Conversation between an agent and a customer that requires a timestamp
of creation
type: object
properties:
id:
type: string
description: The identifier of the conversation.
externalId:
type: string
description: Your unique identifier for a conversation.
agent:
type: object
description: Information about the agent participating in the conversation.
properties:
externalId:
type: string
description: The unique identifier for the agent in your external system.
name:
type: string
description: The display name of the agent.
required:
- externalId
customer:
type: object
description: Information about the customer participating in the conversation.
properties:
externalId:
type: string
description: The unique identifier for the customer in your external system.
name:
type: string
description: The display name of the customer.
required:
- externalId
metadata:
type: object
additionalProperties:
type: string
description: >-
Additional key-value pairs to store custom metadata about the
conversation. Use this for filtering or categorization purposes.
timestamp:
type: string
format: date-time
description: >-
The time when the conversation was created. Include the timezone,
otherwise UTC will be assumed.
required:
- externalId
- customer
- timestamp
example:
externalId: id-111
agent:
externalId: agent-111
name: agent-x
customer:
externalId: customer-x
name: customer-name-x
metadata:
organizationalGroup: some-group
subdivision: some-division
queue: some-queue
timestamp: '2021-11-23T12:13:14.555Z'
BatchMessages:
description: A batch of messages for conversation
type: object
properties:
messages:
type: array
items:
$ref: '#/components/schemas/Message'
minItems: 1
maxItems: 300
example:
messages:
- text: Hello, I would like to upgrade my internet plan to GOLD.
sender:
role: customer
externalId: customer-xyz
timestamp: '2021-11-23T12:13:14.555Z'
- text: Let me help you with that
sender:
role: agent
externalId: agent-111
timestamp: '2021-11-23T12:13:16.666Z'
ConversationResponse:
description: Response for conversation
type: object
properties:
id:
type: string
description: The identifier of the conversation.
example:
id: 01BX5ZZKBKACTAV9WEVGEMMVRZ
Conversations:
description: A list of conversations
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Conversation'
BatchMessagesResponse:
description: Response for batch messages
type: object
GetMessagesResponse:
description: Response for GetMessages
type: object
properties:
items:
type: array
items:
description: A message sent by a participant of a conversation
type: object
properties:
text:
type: string
minLength: 1
description: Text sent
sender:
description: A participant within a conversation
type: object
properties:
role:
$ref: '#/components/schemas/ParticipantRole'
externalId:
type: string
nullable: true
description: The unique identifier for the relevant participant role.
required:
- role
messageId:
type: string
minLength: 1
description: The identifier of the message.
createdTimestamp:
type: string
format: date-time
description: >-
The time when the message objectwas created in the ASAPP
system.
clientTimestamp:
type: string
format: date-time
description: The timestamp of when the message was sent.
required:
- text
- sender
- messageId
- createdTimestamp
- clientTimestamp
example:
text: Hello, I would like to upgrade my internet plan to GOLD.
sender:
role: customer
externalId: '123456'
messageId: 01GMXE90AEV7H3J4DPBDKB1R79
createdTimestamp: '2021-11-23T12:13:16.853Z'
clientTimestamp: '2021-11-23T12:13:14.555Z'
GetMessageResponse:
description: Response for GetMessage
type: object
properties:
text:
type: string
minLength: 1
description: Text sent
sender:
description: A participant within a conversation
type: object
properties:
role:
$ref: '#/components/schemas/ParticipantRole'
externalId:
type: string
nullable: true
description: The unique identifier for the relevant participant role.
required:
- role
messageId:
type: string
minLength: 1
description: The identifier of the message.
createdTimestamp:
type: string
format: date-time
description: The time when the message object was created in the ASAPP system.
clientTimestamp:
type: string
format: date-time
description: The timestamp of when the message was sent.
required:
- text
- sender
- messageId
- createdTimestamp
- clientTimestamp
example:
text: Hello, I would like to upgrade my internet plan to GOLD.
sender:
role: customer
externalId: '123456'
messageId: 01GMXE90AEV7H3J4DPBDKB1R79
createdTimestamp: '2021-11-23T12:13:16.853Z'
clientTimestamp: '2021-11-23T12:13:14.555Z'
AuthObject:
type: object
description: Contains authentication information for a customer in a conversation.
properties:
streamId:
type: string
description: >-
The unique identifier for the connection where responses should be
sent.
example: 97555020-0276-435f-8104-c378221ba292
customerExternalId:
type: string
description: The unique identifier for the customer in your external system.
example: a03839d6-461c-479c-99db-8160174ef12d
auth:
type: object
description: >
An authentication payload that could contain different types of
credentials, such as a token, used to
authenticate an end user. All of the fields are optional, but at
least one will be required
minProperties: 1
properties:
body:
type: object
description: >-
Any authentication data to be sent in the request body, if
applicable.
cookies:
type: object
description: Any authentication data to be sent as cookies, if applicable.
headers:
type: object
description: >-
Any authentication data to be sent in the request headers, if
applicable.
token:
type: string
description: An authentication token for the user, if applicable.
required:
- customerExternalId
- auth
example:
customerExternalId: customer-xyz
token: cGFzc3dvcmQ=
ListFeedsResponse:
description: Get feed names for a company
type: object
properties:
feeds:
type: array
items:
type: string
example:
- feed_1
- feed_2
- feed_3
ListFeedVersionsRequest:
description: Get versions for a company feed
type: object
properties:
feed:
type: string
example: feed_test
required:
- feed
example:
feed: feed_test
ListFeedVersionsResponse:
description: Get versions for a company feed
type: object
properties:
feed:
type: string
example: feed_test
versions:
type: array
items:
type: string
example:
- '1'
- '2'
- '3'
ListFeedFormatsRequest:
description: Get format for a company feed/version
type: object
properties:
feed:
type: string
example: feed_test
version:
type: string
example: '1'
required:
- feed
- version
example:
feed: feed_test
version: '1'
ListFeedFormatsResponse:
description: Get formats for a company feed
type: object
properties:
feed:
type: string
example: feed_test
version:
type: string
example: '1'
formats:
type: array
items:
type: string
example:
- jsonl
- csv
ListFeedDatesRequest:
description: Get dates for a company feed/version/format
type: object
properties:
feed:
type: string
example: feed_test
version:
type: string
example: '1'
format:
type: string
example: jsonl
required:
- feed
- version
- format
example:
feed: feed_test
version: '1'
format: jsonl
ListFeedDatesResponse:
description: Get Dates for a company feed/version/format
type: object
properties:
feed:
type: string
example: feed_test
version:
type: string
example: '1'
format:
type: string
example: format=jsonl
dates:
type: array
items:
type: string
example:
- '2022-06-27'
- '2022-05-20'
- '2022-05-21'
ListFeedIntervalsRequest:
description: Get intervals for a company feed/version/format/date
type: object
properties:
feed:
type: string
example: feed_test
version:
type: string
example: '1'
format:
type: string
example: jsonl
date:
type: string
example: '2022-06-27'
required:
- feed
- version
- format
- date
example:
feed: feed_test
version: '1'
format: jsonl
date: '2022-06-27'
ListFeedIntervalsResponse:
description: Get Dates for a company feed/version/format
type: object
properties:
feed:
type: string
example: feed_test
version:
type: string
example: '1'
format:
type: string
example: jsonl
date:
type: string
example: '2022-06-27'
intervals:
type: array
items:
type: string
example:
- hr=01/mi=01
- hr=01/mi=02
ListFeedFilesRequest:
description: Get files for a company feed/version/format/date/interval
type: object
properties:
feed:
type: string
example: feed_test
version:
type: string
example: '1'
format:
type: string
example: jsonl
date:
type: string
example: '2022-06-27'
interval:
type: string
example: hr=23
required:
- feed
- version
- format
- date
example:
feed: feed_test
version: '1'
format: jsonl
date: '2022-06-27'
interval: hr=23
ListFeedFilesResponse:
description: Get files for a company feed/version/format/date/interval
type: object
properties:
feed:
type: string
example: feed_test
version:
type: string
example: '1'
format:
type: string
example: jsonl
date:
type: string
example: '2022-06-27'
interval:
type: string
example: hr=23
files:
type: array
items:
type: string
example:
- file1.jsonl
- file2.json1
GetFeedFileRequest:
description: Get file for a company feed/version/format/interval/file
type: object
properties:
feed:
type: string
example: feed_test
version:
type: string
example: '1'
format:
type: string
example: jsonl
date:
type: string
example: '2022-06-27'
interval:
type: string
example: hr=23
fileName:
type: string
example: file1.jsonl
required:
- feed
- version
- format
- date
- fileName
example:
feed: feed_test
version: '1'
format: jsonl
date: '2022-06-27'
interval: hr=23
fileName: file1.jsonl
GetFeedFileResponse:
description: Get a presigned url for a file
type: object
properties:
feed:
type: string
example: feed_test
version:
type: string
example: '1'
format:
type: string
example: jsonl
date:
type: string
example: '2022-06-27'
interval:
type: string
example: hr=23
fileName:
type: string
example: file1.json1
url:
type: string
example: www.example.com/12381273972817312/file1.json1
GenerativeAgentSignal:
type: object
description: |
The type of signals the GenerativeAgent sends through webhooks.
oneOf:
- $ref: '#/components/schemas/GenerativeAgentSignalReply'
- $ref: '#/components/schemas/GenerativeAgentSignalProcessingStart'
- $ref: '#/components/schemas/GenerativeAgentSignalProcessingEnd'
- $ref: '#/components/schemas/GenerativeAgentSignalAuthenticationRequested'
- $ref: '#/components/schemas/GenerativeAgentSignalTransferToAgent'
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
health-check:
description: Response for health check.
type: object
properties:
healthCheck:
type: string
description: Health Check status of the ASAPP services.
example:
healthCheck: SUCCESS
SubmissionRequest:
description: >-
A proposal for creating a new article or updating an existing one in the
Knowledge Base.
type: object
properties:
articleId:
type: string
description: The unique identifier for the article being updated.
example: 8f8dcc09-22d7-4aed-acae-fddd060c3a88
title:
type: string
description: >-
The proposed title of the article, which will be refined
automatically. This is required for new articles.
minLength: 1
maxLength: 256
example: 5G Data Plan
content:
type: string
description: >-
The article content in plain text, expected to be in English and
limited to 200,000 Unicode characters. This will be refined during
submission. Required for new articles.
minLength: 1
maxLength: 200000
example: >-
Our 5G data plans offer lightning-fast speeds and generous data
allowances. The Basic 5G plan includes 50GB of data per month, while
our Unlimited 5G plan offers truly unlimited data with no speed
caps. Both plans include unlimited calls and texts within the
country. International roaming can be added for an additional fee.
url:
type: string
description: >-
A reference URL for the article, used for informational purposes
only.
example: https://example.com/5g-data-plans
metadata:
type: array
items:
$ref: '#/components/schemas/Metadata'
description: Additional key-value pairs related to the article.
example:
- key: department
value: Customer experience
queryExamples:
type: array
items:
type: string
description: >-
Examples of customer questions related to the article, such as "Why
is my bill so high?". Defaults to an empty list if not provided.
example:
- What 5G plans do you offer?
- Is there an unlimited 5G plan?
additionalInstructions:
type: array
items:
$ref: '#/components/schemas/AdditionalInstruction'
description: >-
Specific instructions to ensure responses are relevant and address
exceptions.
example:
- clarificationInstruction: Emphasize that 5G coverage may vary by location
exampleResponse: >-
Our 5G plans offer great speeds and data allowances, but please
note that 5G coverage may vary depending on your location. You
can check coverage in your area on our website.
example:
title: 5G Data Plan
content: >-
Our 5G data plans offer lightning-fast speeds and generous data
allowances. The Basic 5G plan includes 50GB of data per month, while
our Unlimited 5G plan offers truly unlimited data with no speed caps.
Both plans include unlimited calls and texts within the country.
International roaming can be added for an additional fee.
url: https://example.com/5g-data-plans
metadata:
- key: department
value: Customer experience
queryExamples:
- What 5G plans do you offer?
- Is there an unlimited 5G plan?
additionalInstructions:
- clarificationInstruction: Emphasize that 5G coverage may vary by location
exampleResponse: >-
Our 5G plans offer great speeds and data allowances, but please
note that 5G coverage may vary depending on your location. You can
check coverage in your area on our website.
Submission:
description: >-
Information about a successfully submitted proposal to update an article
in the Knowledge Base.
type: object
properties:
id:
type: string
description: The unique identifier for the submission.
example: fddd060c-22d7-4aed-acae-8f8dcc093a88
articleId:
type: string
description: The unique identifier for the article related to the submission.
example: 8f8dcc09-22d7-4aed-acae-fddd060c3a88
submittedAt:
type: string
format: date-time
description: The timestamp when the submission was created.
example: '2024-12-12T00:00:00Z'
title:
type: string
description: The article title, either original or refined.
example: 5G Data Plan
content:
type: string
description: The article content, either original or refined.
example: >-
Our 5G data plans offer lightning-fast speeds and generous data
allowances. The Basic 5G plan includes 50GB of data per month, while
our Unlimited 5G plan offers truly unlimited data with no speed
caps. Both plans include unlimited calls and texts within the
country. International roaming can be added for an additional fee.
url:
type: string
description: >-
The reference URL of the article. Defaults to an empty string if not
provided.
example: https://example.com/5g-data-plans
metadata:
type: array
items:
$ref: '#/components/schemas/Metadata'
description: Additional key-value pairs related to the article.
example:
- key: department
value: Customer experience
queryExamples:
type: array
items:
type: string
description: >-
Examples of customer questions related to the article. Defaults to
an empty array if not provided.
example:
- What 5G plans do you offer?
- Is there an unlimited 5G plan?
additionalInstructions:
type: array
items:
$ref: '#/components/schemas/AdditionalInstruction'
description: >-
Specific instructions to ensure responses are relevant and address
exceptions.
example:
- clarificationInstruction: Emphasize that 5G coverage may vary by location
exampleResponse: >-
Our 5G plans offer great speeds and data allowances, but please
note that 5G coverage may vary depending on your location. You
can check coverage in your area on our website.
status:
$ref: '#/components/schemas/SubmissionStatus'
description: The current status of the submission.
example: PENDING_REVIEW
Article:
description: An article stored within the Knowledge Base.
type: object
properties:
id:
type: string
description: The unique identifier for the article.
example: fddd060c-22d7-4aed-acae-8f8dcc093a88
title:
type: string
description: >-
The refined title of the article, resulting from the cleanup
process.
example: 5G Data Plan Overview
content:
type: string
description: >-
The refined content of the article, resulting from the cleanup
process.
example: >-
Our 5G data plans includes 75GB of data per month, while the
Unlimited 5G plan offers unlimited data with no speed caps. Both
plans include unlimited calls and texts within the country.
International roaming is available for an additional fee.
url:
type: string
description: The reference URL of the article. Defaults to null if not provided.
example: https://example.com/5g-data-plans
updatedAt:
type: string
format: date-time
description: >-
The timestamp indicating when the article was last updated. This
field is null if the initial submission is still pending review.
example: '2024-12-12T00:00:00Z'
updatedBy:
type: string
description: >-
The email address of the user who last updated the article. This
field is null if the initial submission is still pending review.
example: user@company.com
metadata:
type: array
items:
$ref: '#/components/schemas/Metadata'
description: Additional key-value pairs related to the article.
example:
- key: department
value: Customer experience
originalContent:
type: string
description: The original content of the article prior to the cleanup process.
example: >-
Our 5G data plans offer lightning-fast speeds and generous data
allowances. The Basic 5G plan now includes 75GB of data per month,
while our Unlimited 5G plan offers truly unlimited data with no
speed caps. Both plans include unlimited calls and texts within the
country. International roaming can be added for an additional fee.
originalTitle:
type: string
description: The original title of the article prior to the cleanup process.
example: 5G Data Plan
queryExamples:
type: array
items:
type: string
description: >-
Examples of customer questions related to the article. Defaults to
an empty array if not provided.
example:
- What 5G plans do you offer?
- Is there a family plan for 5G?
additionalInstructions:
type: array
items:
$ref: '#/components/schemas/AdditionalInstruction'
description: >-
Specific instructions to ensure responses are relevant and address
exceptions.
example:
- clarificationInstruction: >-
Emphasize that 5G coverage may vary by location and mention the
new Family Plan option
exampleResponse: >-
Our 5G plans offer great speeds and data allowances, including
our new Family Plan. Please note that 5G coverage may vary
depending on your location. You can check coverage in your area
on our website.
pendingSubmissionId:
type: string
description: >-
The unique identifier for the submission currently under review for
this article. This field is null if there are no pending
submissions.
example: 86ba487a-6d58-4b4c-82de-9d422f1166ae
currentVersion:
type: string
description: >-
The current version label of the article. This field is null if the
initial submission is still pending review.
example: v1
deploymentStatus:
$ref: '#/components/schemas/DeploymentStatus'
description: The current deployment status of the article.
example: DRAFT
example:
id: fddd060c-22d7-4aed-acae-8f8dcc093a88
updatedAt: '2024-12-12T00:00:00'
updatedBy: user@company.com
title: 5G Data Plan Overview
content: >-
Our 5G data plans includes 75GB of data per month, while the Unlimited
5G plan offers unlimited data with no speed caps. Both plans include
unlimited calls and texts within the country. International roaming is
available for an additional fee.
url: https://example.com/5g-data-plans
metadata:
- key: department
value: Customer experience
originalContent: >-
Our 5G data plans offer lightning-fast speeds and generous data
allowances. The Basic 5G plan now includes 75GB of data per month,
while our Unlimited 5G plan offers truly unlimited data with no speed
caps. Both plans include unlimited calls and texts within the country.
International roaming can be added for an additional fee.
originalTitle: 5G Data Plan
queryExamples:
- What 5G plans do you offer?
- Is there a family plan for 5G?
additionalInstructions:
- clarificationInstruction: >-
Emphasize that 5G coverage may vary by location and mention the
new Family Plan option
exampleResponse: >-
Our 5G plans offer great speeds and data allowances, including our
new Family Plan. Please note that 5G coverage may vary depending
on your location. You can check coverage in your area on our
website.
pendingSubmissionId: 86ba487a-6d58-4b4c-82de-9d422f1166ae
currentVersion: v1
deploymentStatus: DRAFT
Metadata:
description: A key-value pair providing additional information about the article.
type: object
required:
- key
- value
properties:
key:
type: string
minLength: 1
description: The key for the metadata entry.
example: department
value:
type: string
minLength: 1
description: The value for the metadata entry.
example: Customer experience
AdditionalInstruction:
description: Guidelines and responses to enhance the article.
type: object
properties:
clarificationInstruction:
type: string
description: A guideline to improve the article's content.
example: Emphasize that 5G coverage may vary by location
exampleResponse:
type: string
description: >-
A sample response applicable if the clarification instruction is
followed.
example: >-
Our 5G plans offer great speeds and data allowances, but please note
that 5G coverage may vary depending on your location. You can check
coverage in your area on our website.
SubmissionStatus:
description: The current status of the submission.
type: string
enum:
- PENDING_REVIEW
- ACCEPTED
- REJECTED
example: PENDING_REVIEW
DeploymentStatus:
description: The current deployment status of the article.
type: string
enum:
- NONE
- DRAFT
- SANDBOX
- PRODUCTION
- SANDBOX_AND_PRODUCTION
example: DRAFT
Attribute:
description: A key-value pair of additional metadata attributes
type: object
properties:
name:
description: The name of the attribute
type: string
maxLength: 256
value:
description: The value of the named attribute
type: string
maxLength: 1024
example:
- name: attr1_name
value: attr1_value
- name: attr2_name
value: attr2_value
MessageSentStatus:
description: A response with the status of a sent message
type: object
properties:
eventId:
description: An UUID identifier string computed for the submitted event message
type: string
example: 5484e507-feaf-11ec-bfc1-fda566fa9333
error:
description: >-
Status of the failed message if value is not blank; the error is
contained in the string
type: string
example: 'FAIL_BAD_PARAMS: ERROR: agent id cannot be blank'
example:
eventId: 5484e507-feaf-11ec-bfc1-fda566fa9333
error: 'FAIL_BAD_PARAMS: ERROR: agent id cannot be blank'
AgentMetadata:
description: A set of agent metadata attributes
type: object
properties:
externalAgentId:
description: The agent id in question
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 256
example: agent158
eventId:
description: >
An event id used to track the submission; if none is provided,
service will generate one
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 256
nullable: true
example: eventId-158
startTs:
description: The date and time when the agent is hired in ISO-8601
type: string
format: date-time
nullable: true
example: '2022-07-08T11:15:53.237517000Z'
lobId:
description: The line of business id
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 256
nullable: true
example: '1038'
lobName:
description: The descriptive name of the line of business
type: string
maxLength: 256
nullable: true
example: manufacturing
groupId:
description: The group id of which the agent belong to
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 256
nullable: true
example: group5
groupName:
description: The descriptive name of the group
type: string
maxLength: 256
nullable: true
example: XYZ
agentName:
description: The name of the agent
type: string
maxLength: 256
nullable: true
example: Jane Doe
agentLocation:
description: The location (or address) of where the agent worked
type: string
maxLength: 256
nullable: true
example: Northern-California
supervisorId:
description: The supervisor id of who the agent report to
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 256
nullable: true
example: '3080'
supervisorName:
description: The name of the agent's supervisor
type: string
maxLength: 256
nullable: true
example: Linda Lemon
languages:
description: |
A list of agent's known language codes in ISO 639
e.g., English (United States) code = en-US
type: array
items:
type: string
pattern: '[a-zA-Z0-9\-]+'
maxLength: 16
nullable: true
example:
- en-us
- zh-hans-hk
concurrency:
description: The number of issues that an agent can take at a time
type: integer
nullable: true
example: 3
categoryLabel:
description: >-
The category label that indicates the types of workflows an agent
have access to or problems they solved
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 256
nullable: true
example: Tier-2-Escalation
accountAccessLevel:
description: >-
The levels of mapping that an agent have access to make changes to
customer accounts
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 256
nullable: true
example: High-Profile
ranking:
description: >-
Some numerical value indicating relative or absolute performance on
a single scale
type: integer
nullable: true
example: 78
vendor:
description: >-
Vendor or BPO (Business Process Outsourcing) that the agent is part
of
type: string
maxLength: 256
nullable: true
example: Contracting
jobTitle:
description: The agent's job title
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 256
nullable: true
example: Booking-Manager
jobRole:
description: The agent's role
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 256
nullable: true
example: booking
workShift:
description: The hours or shift name they work
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 256
nullable: true
example: afternoon
emailAddress:
description: The agent's email address
type: string
format: email
nullable: true
example: jdoe@example.com
attributes:
description: A map of key-value pairs for extra metadata attributes
type: array
items:
$ref: '#/components/schemas/Attribute'
maxItems: 10
nullable: true
example:
- name: attr1_name
value: attr1_value
- name: attr2_name
value: attr2_value
required:
- externalAgentId
example:
externalAgentId: agent158
startTs: '2022-07-08T11:15:53.237517000Z'
lobId: '1038'
lobName: manufacturing
groupId: group5
groupName: XYZ
agentName: Jane Doe
agentLocation: Northern-California
supervisorId: '3080'
supervisorName: Linda Lemon
languages:
- en-us
- zh-hans-hk
concurrency: 3
categoryLabel: Tier-2-Escalation
accountAccessLevel: High-Profile
ranking: 78
vendor: Contracting
jobTitle: Booking-Manager
jobRole: booking
workShift: afternoon
emailAddress: jdoe@example.com
attributes:
- name: attr1_name
value: attr1_value
- name: attr2_name
value: attr2_value
AgentMetadataMany:
description: A request to send more than one agent metadata; send a list of items
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/AgentMetadata'
minItems: 1
maxItems: 1000
example:
items:
- externalAgentId: agent158
startTs: '2022-07-08T11:15:53.237517000Z'
lobId: '1038'
lobName: manufacturing
groupId: group5
groupName: XYZ
agentName: Jane Doe
agentLocation: Northern-California
supervisorId: '3080'
supervisorName: Linda Lemon
languages:
- en-us
- zh-hans-hk
- es-pe
concurrency: 3
categoryLabel: Tier-2-Escalation
accountAccessLevel: High-Profile
ranking: 78
vendor: Contracting
jobTitle: Booking-Manager
jobRole: booking
workShift: afternoon
emailAddress: jdoe@example.com
attributes:
- name: attr1_name
value: attr1_value
- name: attr2_name
value: attr2_value
- externalAgentId: agent392
startTs: '2021-09-02T11:15:53.237517000Z'
lobId: '968'
lobName: insurance
groupId: group3
groupName: DFG
agentName: Jonathan Master
agentLocation: Southern-California
supervisorId: '1290'
supervisorName: John Luna
languages:
- en-us
concurrency: 3
categoryLabel: Tier-1-Service
accountAccessLevel: High-Profile
ranking: 75
vendor: Contracting
jobTitle: Customer-Service
jobRole: Support
workShift: afternoon
emailAddress: jmaster@example.com
attributes:
- name: attr1_name
value: attr1_value
- externalAgentId: agent6922
startTs: null
- externalAgentId: agent222
- externalAgentId: agent333
emailAddress: jdoe@example.com
ConversationMetadata:
description: A set of conversation metadata attributes
type: object
properties:
externalConversationId:
description: Conversation ID from the external chat / voice system
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 256
example: issue1389
eventId:
description: >
An event id used to track the submission; if none is provided,
service will generate one
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 256
nullable: true
example: eventId-1388
lobId:
description: The line of business id
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 256
nullable: true
example: '1038'
lobName:
description: The descriptive name of the line of business
type: string
maxLength: 256
nullable: true
example: manufacturing
groupId:
description: The group id of which the agent belong to
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 256
nullable: true
example: group59
groupName:
description: The descriptive name of the group
type: string
maxLength: 256
nullable: true
example: groupXYZ
agentRoutingCode:
description: The agent's routing attribute
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 256
nullable: true
example: route-13988
campaign:
description: The activities related to the issue
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 256
nullable: true
example: campaign-A
deviceType:
description: The client's device type
type: string
enum:
- TABLET
- PHONE
- DESKTOP
- WATCH
- OTHER
nullable: true
example: TABLET
platform:
description: |
The client's platform type
WAB: WhatsApp Business
type: string
enum:
- SMS
- WEB
- IOS
- ANDROID
- APP
- LOCAL
- VOICE
- VOICE_IOS
- VOICE_ANDROID
- VOICE_ECHO
- VOICE_HOMEPOD
- VOICE_GGLHOME
- VOICE_WEB
- APPLEBIZ
- GOOGLEBIZ
- GBM
- WAB
nullable: true
example: IOS
companySegment:
description: The company's segment of which the issue belongs to
type: array
items:
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 64
nullable: true
example:
- Sales
- Marketing
companySubdivision:
description: The company's subdivision of which the issue belongs to
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 256
nullable: true
example: Operating
businessRule:
description: The business rule to use
type: string
maxLength: 256
nullable: true
example: Apply customer's discount
entryType:
description: The way the issue started and created in the system
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 256
nullable: true
example: reactive
operatingSystem:
description: The operating system used to enter the issue
type: string
enum:
- MAC_OS
- LINUX
- WINDOWS
- ANDROID
- IOS
- OTHER
nullable: true
example: MAC_OS
browserType:
description: The browser type used
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 64
nullable: true
example: Safari
browserVersion:
description: The browser version used
type: string
pattern: '[a-zA-Z0-9\-\_\.]+'
maxLength: 16
nullable: true
example: 14.1.2
attributes:
description: A map of key-value pairs for extra metadata attributes
type: array
items:
$ref: '#/components/schemas/Attribute'
maxItems: 10
nullable: true
example:
- name: attr1_name
value: attr1_value
- name: attr2_name
value: attr2_value
required:
- externalConversationId
example:
externalConversationId: id-1389
eventId: eventId-1388
lobId: '1038'
lobName: manufacturing
groupId: group59
groupName: groupXYZ
agentRoutingCode: route-13988
campaign: campaign-A
deviceType: TABLET
platform: IOS
companySegment:
- Sales
- Marketing
companySubdivision: operating
businessRule: Apply customer's discount
entryType: reactive
operatingSystem: MAC_OS
browserType: Safari
browserVersion: 14.1.2
attributes:
- name: attr1_name
value: attr1_value
- name: attr2_name
value: attr2_value
ConversationMetadataMany:
description: >
A request to send more than one conversation metadata attributes; send a
list of items
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/ConversationMetadata'
minItems: 1
maxItems: 1000
example:
items:
- externalConversationId: id-1389
eventId: eventId-1388
lobId: '1038'
lobName: manufacturing
groupId: group59
groupName: groupXYZ
agentRoutingCode: route-13988
campaign: campaign-A
deviceType: TABLET
platform: IOS
companySegment:
- Sales
- Marketing
companySubdivision: operating
businessRule: Apply customer's discount
entryType: reactive
operatingSystem: MAC_OS
browserType: Safari
browserVersion: 14.1.2
attributes:
- name: attr1_name
value: attr1_value
- name: attr2_name
value: attr2_value
- externlConversationId: issue1390
eventId: eventId-1268
lobId: '930'
lobName: retail
groupId: store-93
groupName: PlazaA
agentRoutingCode: route-1983
campaign: campaign-B
deviceType: PHONE
platform: ANDROID
companySegment:
- SALES
- FINANCE
companySubdivision: operating
businessRule: Apply customer's discount
entryType: proactive
operatingSystem: ANDROID
browserType: Chrome
browserVersion: 103.0.5060.128
attributes:
- name: attr1_name
value: attr1_value
- name: attr2_name
value: attr2_value
CustomerMetadata:
description: A set of customer metadata attributes
type: object
properties:
externalConversationId:
description: Conversation ID from the external chat / voice system
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 256
example: issue509
externalCustomerId:
description: The customer id involved in respect to the issue in question
type: string
pattern: '[a-zA-Z0-9\-\_\.\@]+'
maxLength: 256
example: 555.555.0100-jdoe@example.com
eventId:
description: >
An event id used to track the submission; if none is provided,
service will generate one
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 256
nullable: true
example: eventId-1938
status:
description: The descriptive label to describe the customer's status and/or type
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 256
nullable: true
example: new
phoneNumber:
description: The customer's phone number
type: string
pattern: '[0-9\-\.\(\)\+]+'
maxLength: 32
nullable: true
example: (555)555-0100
emailAddress:
description: The customer's email address
type: string
format: email
nullable: true
example: jdoe@example.com
userId:
description: The customer's user Id
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 256
nullable: true
example: user908038
addressCountry:
description: The country portion of the customer's address
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 128
nullable: true
example: United-States
addressState:
description: The state portion of the customer's address
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 128
nullable: true
example: New-York
addressZipcode:
description: The zipcode/postal code portion of the customer's address
type: string
pattern: '[a-zA-Z0-9\-\_]+'
maxLength: 16
nullable: true
example: '10001'
attributes:
description: A map of key-value pairs for extra metadata attributes
type: array
items:
$ref: '#/components/schemas/Attribute'
maxItems: 10
nullable: true
example:
- name: attr1_name
value: attr1_value
- name: attr2_name
value: attr2_value
required:
- externalConversationId
- externalCustomerId
example:
externalConversationId: id-509
externalCustomerId: 555.555.0100-jdoe@example.com
eventId: eventId-1938
status: new
phoneNumber: (555)555-0100
emailAddress: jdoe@example.com
userId: user908038
addressCountry: United-States
addressState: New-York
addressZipcode: '10001'
attributes:
- name: attr1_name
value: attr1_value
- name: attr2_name
value: attr2_value
CustomerMetadataMany:
description: A request to send more than one customer metadata; send a list of items
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/CustomerMetadata'
minItems: 1
maxItems: 1000
example:
items:
- externalConversationId: id-509
externalCustomerId: 555.555.0100-jdoe@example.com
eventId: eventId-1938
status: new
phoneNumber: (555)555-0100
emailAddress: jdoe@example.com
userId: user908038
addressCountry: United-States
addressState: New-York
addressZipcode: '10001'
attributes:
- name: attr1_name
value: attr1_value
- name: attr2_name
value: attr2_value
- externalConversationId: id-203
externalCustomerId: 555.555.0101-mdoe@example.com
eventId: eventId-1331
status: existing
phoneNumber: (555)555-0101
emailAddress: mdoe@example.com
userId: user3201033
addressCountry: United-States
addressState: New-York
addressZipcode: '10002'
attributes:
- name: attr1_name
value: attr1_value
- name: attr2_name
value: attr2_value
- externalConversationId: id-69221
externalCustomerId: 555.555.0191
attributes: null
- externalConversationId: id-69223
externalCustomerId: 555.555.0193
- externalConversationId: id-69229
externalCustomerId: zdoe@example.com
phoneNumber: null
userId: null
addressCountry: null
AddMetadataResponse:
type: object
properties:
result:
$ref: '#/components/schemas/MessageSentStatus'
required:
- result
example:
result:
eventId: 5484e507-feaf-11ec-bfc1-fda566fa9333
error: 'FAIL_BAD_PARAMS: ERROR: agent id cannot be blank'
AddManyMetadataResponse:
type: object
properties:
errorCount:
description: Number of message sent with error(s)
type: integer
results:
description: A list of send result
type: array
items:
$ref: '#/components/schemas/MessageSentStatus'
required:
- errorCount
- results
example:
errorCount: 1
results:
- eventId: 5484e507-feaf-11ec-bfc1-fda566fa9333
error: 'FAIL_BAD_PARAMS: ERROR: agent id cannot be blank'
- eventId: fcf99667-feaf-11ec-a42e-11799134528c
error: ''
StartStreamingRequest:
type: object
properties:
namespace:
description: The media gateway platform or protocol you are using.
type: string
enum:
- siprec
- twilio
- amazonconnect
- genesysaudiohook
guid:
description: >-
The globally unique Id for the call, also sometimes called Unique
Call Id (UCID). Must be in decimal form.
type: string
autotranscribeParams:
$ref: '#/components/schemas/StartStreamingAutotranscribeParams'
siprecParams:
$ref: '#/components/schemas/StartStreamingSiprecParams'
twilioParams:
$ref: '#/components/schemas/StartStreamingTwilioParams'
amazonConnectParams:
$ref: '#/components/schemas/StartStreamingAmazonConnectParams'
customerId:
description: >-
Id of the customer on the call. Usually taken from Call Center CTI
information.
type: string
agentId:
description: >-
The Id of the agent on the call. Usually taken from Call Center CTI
information.
type: string
required:
- namespace
- guid
- customerId
- agentId
example:
namespace: siprec
guid: 0867617078-0032318833-2221801472-0002236962
customerId: customerId
agentId: agentId
autotranscribeParams:
language: en-US
siprecParams:
mediaLineOrder: CUSTOMER_FIRST
StartStreamingAutotranscribeParams:
type: object
properties:
language:
description: IETF language tag
type: string
default: en-US
detailedToken:
description: >
Determines whether AutoTranscribe outputs word-level details like
word content, timestamp and word type
type: boolean
default: false
audioRecordingAllowed:
description: >
Determines whether ASAPP may record and store the audio for this
conversation for the purposes of model training
type: boolean
default: false
redactionOutput:
description: >
Determines whether the transcription output is redacted.
If detailedToken is true, requests with value "redacted" or
"redacted_and_unredacted" will be rejected.
If no redaction rules configured by the client for "redacted" or
"redacted_and_unredacted", the request will be rejected.
type: string
default: redacted
enum:
- redacted
- unredacted
- redacted_and_unredacted
example:
language: en-US
detailedToken: false
audioRecordingAllowed: false
redactionOutput: redacted
StartStreamingSiprecParams:
type: object
properties:
mediaLineOrder:
$ref: '#/components/schemas/SiprecMediaLineOrder'
SiprecMediaLineOrder:
description: >
Defines the mapping of media lines (m-lines) in SDP of SIPREC protocol.
- `CUSTOMER_FIRST` will map top audio m-line to customer side of
conversation (usual for inbound calls to call center, default)
- `AGENT_FIRST` will map top audio m-line to agent side of the
conversation (usual for outbound calls from call center)
type: string
default: CUSTOMER_FIRST
enum:
- CUSTOMER_FIRST
- AGENT_FIRST
StartStreamingTwilioParams:
type: object
properties:
trackMap:
$ref: '#/components/schemas/TwilioTrackMap'
example:
trackMap:
inbound: customer
outbound: agent
TwilioTrackMap:
type: object
properties:
inbound:
type: string
description: The inbound twilio track
default: customer
enum:
- customer
- agent
outbound:
type: string
description: The outbound twilio track
default: agent
enum:
- customer
- agent
StartStreamingAmazonConnectParams:
type: object
properties:
streamArn:
type: string
description: Amazon stream arn
startSelectorType:
type: string
description: >-
Identifies the fragment on the Kinesis video stream where you want
to start getting the data from
enum:
- NOW
- FRAGMENT_NUMBER
afterFragmentNumber:
type: string
description: >-
Amazon fragment number from where you want to start returning the
fragments - mandatory if startSelectorType is FRAGMENT_NUMBER
example:
streamArn: >-
arn:aws:kinesisvideo:us-east-1:000000000000:stream/streamtest-connect-asappconnect-contact-1117e864-690f-4e1e-9dcf-6fbfcc288e41/1654194145007
startSelectorType: FRAGMENT_NUMBER
afterFragmentNumber: '91343852333181476958523476930058290730435475343'
StartStreamingResponse:
type: object
properties:
autotranscribeResponse:
$ref: '#/components/schemas/StartStreamingAutotranscribeResponse'
isOk:
type: boolean
errorMessage:
type: string
example:
isOk: true
autotranscribeResponse:
customer:
streamId: 5ce2b755-3f38-11ed-b755-7aed4b5c38d5
status:
code: 1000
description: OK
agent:
streamId: cf31116-3f38-11ed-9116-7a0a36c763f1
status:
code: 1000
description: OK
StartStreamingAutotranscribeResponse:
type: object
properties:
customer:
$ref: '#/components/schemas/StartStreamingAutotranscribeResponseDetails'
agent:
$ref: '#/components/schemas/StartStreamingAutotranscribeResponseDetails'
StartStreamingAutotranscribeResponseDetails:
type: object
properties:
streamId:
type: string
example: 5ce2b755-3f38-11ed-b755-7aed4b5c38d5
status:
$ref: '#/components/schemas/AutotranscribeResponseStatus'
AutotranscribeResponseStatus:
type: object
properties:
code:
type: integer
example: 1000
description:
type: string
example: OK
StopStreamingRequest:
type: object
properties:
namespace:
description: The media gateway platform or protocol you are using.
type: string
enum:
- siprec
- twilio
- amazonconnect
- genesysaudiohook
guid:
description: >-
The globally unique Id for the call, also sometimes called Unique
Call Id (UCID). Must be in decimal form.
type: string
example:
namespace: siprec
guid: 0867617078-0032318833-2221801472-0002236962
StopStreamingResponse:
type: object
properties:
autotranscribeResponse:
$ref: '#/components/schemas/StopStreamingAutotranscribeResponse'
isOk:
type: boolean
errorMessage:
type: string
StopStreamingAutotranscribeResponse:
type: object
properties:
customer:
$ref: '#/components/schemas/StopStreamingAutotranscribeResponseDetails'
agent:
$ref: '#/components/schemas/StopStreamingAutotranscribeResponseDetails'
StopStreamingAutotranscribeResponseDetails:
type: object
properties:
streamId:
type: string
example: 5ce2b755-3f38-11ed-b755-7aed4b5c38d5
status:
$ref: '#/components/schemas/AutotranscribeResponseStatus'
summary:
$ref: '#/components/schemas/StopStreamingResponseSummary'
StopStreamingResponseSummary:
type: object
properties:
totalAudioBytes:
type: integer
audioDurationMs:
type: integer
streamingSeconds:
type: integer
transcripts:
type: integer
example:
totalAudioBytes: 1334720
audioDurationMs: 83420
streamingSeconds: 84
transcripts: 2
GetTwilioMediaStreamsResponse:
type: object
properties:
streamingUrl:
description: The websocket URL you provide to Twilio for media streaming.
type: string
example: >-
wss://localhost/mg-twilio-autotranscribe/twilio-media/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
x-tagGroups:
- name: AutoCompose API
tags:
- AutoCompose
- name: AutoSummary API
tags:
- AutoSummary
- name: AutoTranscribe API
tags:
- AutoTranscribe
- name: Conversations API
tags:
- Conversations
- name: File Exporter API
tags:
- File Exporter
- name: GenerativeAgent API
tags:
- GenerativeAgent
- name: Health Check API
tags:
- Health Check
- name: Knowledge Base API
tags:
- Knowledge Base
- name: Metadata Ingestion API
tags:
- Metadata
- name: MG Autotranscribe API Router
tags:
- AutoTranscribe Media Gateway