ASAPP Conversations API
Create/update conversations and messages, authenticate customers, and list/retrieve conversation history.
OpenAPI Specification
openapi: 3.0.1
info:
title: Conversations API
description: Operations to manage ASAPP conversations
contact:
email: api-info@asapp.com
license:
name: ASAPP Software License
url: https://api.asapp.com/LICENSE
version: '0.1'
servers:
- url: https://api.sandbox.asapp.com
tags:
- name: Conversations
description: Operations to send conversational inputs to ASAPP AI services
security:
- API-ID: []
API-Secret: []
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:
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'
responses:
'200':
description: Successfully created or updated conversation
content:
application/json:
schema:
description: Response for conversation
type: object
properties:
id:
type: string
description: The identifier of the conversation.
example:
id: 01BX5ZZKBKACTAV9WEVGEMMVRZ
'400':
description: 400 - Bad request
content:
application/json:
schema:
description: Bad request response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 400-01
message: Bad request
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'401':
description: 401 - Unauthorized
content:
application/json:
schema:
description: Unauthorized response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 401-01
message: Unauthorized
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'403':
description: 403 - Forbidden
content:
application/json:
schema:
description: Forbidden response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 403-01
message: Forbidden Response
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'404':
description: 404 - Not Found
content:
application/json:
schema:
description: Not Found response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 404-01
message: Not Found
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'409':
description: 409 - Conflict
content:
application/json:
schema:
description: Conflict response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 409-01
message: Conflict
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'413':
description: 413 - Request Entity Too Large
content:
application/json:
schema:
description: Request Entity Too Large response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 413-01
message: Request Entity Too Large
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'422':
description: 422 - Unprocessable Entity
content:
application/json:
schema:
description: Unprocessable Entity response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 422-01
message: Unprocessable Entity
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'429':
description: 429 - Too Many Requests
content:
application/json:
schema:
description: Too Many Requests response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 429-01
message: Too Many Requests
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'503':
description: 503 - Service Unavailable
content:
application/json:
schema:
description: Service Unavailable response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 503-01
message: Service Unavailable
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
default:
description: 500 - Internal Server Error
content:
application/json:
schema:
description: Default error response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 500-01
message: Internal server error
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
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:
- name: externalId
description: Your identifier for a conversation.
in: query
required: true
schema:
type: string
example:
externalId: id-111
responses:
'200':
description: Successfully fetched conversations
content:
application/json:
schema:
description: A list of conversations
type: object
properties:
items:
type: array
items:
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
'400':
description: 400 - Bad request
content:
application/json:
schema:
description: Bad request response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 400-01
message: Bad request
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'401':
description: 401 - Unauthorized
content:
application/json:
schema:
description: Unauthorized response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 401-01
message: Unauthorized
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'403':
description: 403 - Forbidden
content:
application/json:
schema:
description: Forbidden response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 403-01
message: Forbidden Response
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'404':
description: 404 - Not Found
content:
application/json:
schema:
description: Not Found response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 404-01
message: Not Found
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'422':
description: 422 - Unprocessable Entity
content:
application/json:
schema:
description: Unprocessable Entity response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 422-01
message: Unprocessable Entity
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'429':
description: 429 - Too Many Requests
content:
application/json:
schema:
description: Too Many Requests response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 429-01
message: Too Many Requests
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'503':
description: 503 - Service Unavailable
content:
application/json:
schema:
description: Service Unavailable response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 503-01
message: Service Unavailable
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
default:
description: 500 - Internal Server Error
content:
application/json:
schema:
description: Default error response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 500-01
message: Internal server error
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
/conversation/v1/conversations/{conversationId}:
parameters:
- name: conversationId
description: The identifier for a conversation.
in: path
required: true
schema:
type: string
pattern: ^[A-Z0-9]+$
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:
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
'400':
description: 400 - Bad request
content:
application/json:
schema:
description: Bad request response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 400-01
message: Bad request
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'401':
description: 401 - Unauthorized
content:
application/json:
schema:
description: Unauthorized response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 401-01
message: Unauthorized
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
# --- truncated at 32 KB (144 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/asapp/refs/heads/main/openapi/asapp-conversations-openapi.yml