ASAPP Conversations API
Operations to send conversational inputs to ASAPP AI services
Operations to send conversational inputs to ASAPP AI services
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/asapp-conversations-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: AutoCompose Conversations 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: Conversations
description: Operations to send conversational inputs to ASAPP AI services
x-displayName: Conversations
paths:
/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: []
components:
schemas:
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
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
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
- 'null'
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'
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'
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'
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
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 \nauthenticate an end user. All of the fields are optional, but at least one will be required\n"
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=
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'
ConflictResponse:
description: Conflict response
type: object
properties:
error:
$ref: '#/components/schemas/DefaultErrorDetails'
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 409-01
message: Conflict
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
BatchMessagesResponse:
description: Response for batch messages
type: object
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
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
UnauthorizedResponse:
description: Unauthorized response
type: object
properties:
error:
$ref: '#/components/schemas/DefaultErrorDetails'
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 401-01
message: Unauthorized
MessagesResponse:
description: Response for messages
type: object
properties:
id:
type: string
description: Message ID to be used for analytics
example:
id: 01BX5ZZKBKACTAV9WEVGEMMVS1
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
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
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
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
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'
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
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
- 'null'
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'
responses:
RequestEntityTooLarge:
description: 413 - Request Entity Too Large
content:
application/json:
schema:
$ref: '#/components/schemas/RequestEntityTooLargeResponse'
Conflict:
description: 409 - Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictResponse'
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'
ServiceUnavailable:
description: 503 - Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceUnavailableResponse'
TooManyRequests:
description: 429 - Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
NotFound:
description: 404 - Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
BadRequest:
description: 400 - Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
UnprocessableEntity:
description: 422 - Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntity'
Forbidden:
description: 403 - Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponse'
parameters:
messageId:
name: messageId
description: Internal message identifier from ASAPP
in: path
required: true
schema:
type: string
pattern: ^[A-Z0-9]+$
externalId:
name: externalId
description: Your identifier for a conversation.
in: query
required: true
schema:
type: string
example:
externalId: id-111
conversationId:
name: conversationId
description: The identifier for a conversation.
in: path
required: true
schema:
type: string
pattern: ^[A-Z0-9]+$
securitySchemes:
API-ID:
type: apiKey
in: header
name: asapp-api-id
API-Secret:
type: apiKey
in: header
name: asapp-api-secret
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