Conversations and Messages
Send Message (Streaming)
POST /api/v1/chatbots/{chatbotId}/completions/
Parameters
chatbotId
✅
string
Request Body
Request Parameters
conversation
string (uuid)
No
Unique identifier of the conversation. If empty, a new conversation is created (optional)
message
object (9 properties: content, contentPayload, queryMetadata...)
Yes
The message content to send
message.content
string
Yes
Text content of the message; may be an empty string if attachments are provided
message.contentPayload
object
No
Additional content payload of the message, in JSON format (optional)
message.queryMetadata
object
No
Query metadata, in JSON format (optional)
message.metadata
object
No
Environment metadata of the message, such as time zone, in JSON format (optional)
message.attachments
array[AttachmentInput]
No
List of attachments for the message (optional)
message.toolIds
array[string]
No
List of tool IDs to enable for this message (optional)
message.clientTools
array[any]
No
List of tool definitions provided by the client (such as a Chrome extension) for this message (optional). Each entry must include name(str), description(str), and input_schema(dict). When the LLM calls one, the backend does not execute it; instead it returns a clientToolCall content and ends the turn.
message.sender
string (uuid)
No
Contact ID of the sender (optional); mutually exclusive with externalUser
message.externalUser
object (4 properties: id, name, email...)
No
Ask as a user of the calling system (optional): MaiAgent finds or creates a contact by the external user ID, and the conversation is recorded under that contact; mutually exclusive with sender, and providing both returns 400
message.externalUser.id
string
Yes
The calling system's own user ID (required; matched exactly as a string, case-sensitive; an empty or whitespace-only string returns 400). MaiAgent finds or creates a contact by (organization, external user ID); if an organization has multiple external systems, adding a system prefix is recommended, for example projects:usr_123
message.externalUser.name
string
No
Contact name (optional); updated if provided, unchanged if omitted (or null/empty string); when a contact is newly created without a name, the external user ID is used as the name
message.externalUser.email
object
No
Contact email (optional); updated if provided, unchanged if omitted (or null/empty string); a non-empty but invalid format returns 400
message.externalUser.metadata
object
No
Custom contact information (optional), in the same format as the metadata of the Contact API; if provided, it replaces the whole object, and if omitted (or null) it is unchanged
isStreaming
boolean
No
Whether to respond in streaming mode; defaults to false (optional). In non-streaming mode (false), the server has a wait limit: if the response completes within the limit, it returns 200 with the full response; if it exceeds the limit, it returns 202 (status is processing), and the Location response header points to the status resource for this reply. Poll that URL with GET at the interval given by Retry-After to get the result. Streaming mode is not subject to this limit.
waitForAttachments
boolean
No
Whether to wait for attachment processing to finish before entering the agent workflow; defaults to true (optional)
Request Schema Example
Request Example Values
Code Examples
Response
Status Code: 200 - Conversation response content; for streaming, an event stream
Status Code: 202 - 202 is returned in two cases, distinguished by `status`: - `processing`: a non-streaming call (`isStreaming` omitted or false) exceeded the server-side wait limit without completing. The message has been received, and the platform continues generating and saving the reply (credits are deducted only once); the body contains only identifying information and no `content`; **do not resend**. - `pending_attachments`: attachments in the conversation are still being processed (same for non-streaming and streaming calls). In normal mode, the AI...
Response Schema Example
Response Example Values
Status Code: 400 - Invalid request parameters. Possible causes include: the Contact ID does not belong to the organization Error codes (X-Error-Code): `contact_not_found`, `contact_organization_mismatch`, `contact_inbox_not_linked`, `contact_permission_denied`, `message_content_required`, `...
Status Code: 401 - Error codes (X-Error-Code): `not_authenticated`, `authentication_failed`.
Status Code: 402 - Error codes (X-Error-Code): `insufficient_credits`, `insufficient_quota`, `no_active_plan`.
Status Code: 403 - Error codes (X-Error-Code): `permission_denied`.
Status Code: 404 - Error codes (X-Error-Code): `conversation_not_found`, `not_found`.
Status Code: 429 - Error codes (X-Error-Code): `throttled`.
Status Code: 504 - An AI assistant in Agent mode reached its execution time limit before the submitted message was saved (the limit is counted from when the request is received, and the number of seconds is the same as the AI assistant's Agent timeout; team mode uses the team timeout). Usually the platform has not created a conversation or saved the message; however, if the message was being written when the limit was reached, it may still be saved in the conversation (with no AI reply and no charge), and when you resend with the same `conversation`, the conversation will show a duplicate question. `detail` is the timeout messa...
Response Schema Example
Response Example Values
Send Message (Create)
POST /api/v1/messages/
Request Body
Request Parameters
conversation
string (uuid)
Yes
type
string
No
content
string
No
contentPayload
object
No
attachments
array[MessageAttachmentInput]
No
canvas
object
No
canvas.name
string
Yes
canvas.canvasType
object
Yes
canvas.title
string
Yes
canvas.content
string
Yes
slideTemplate
object (with 3 properties: slug, displayName, thumbnailUrls)
No
slideTemplate.slug
string
Yes
slideTemplate.displayName
string
Yes
slideTemplate.thumbnailUrls
array[string]
No
queryMetadata
object
No
Query metadata that controls which knowledge can be searched; see each endpoint's description for details
queryMetadata.knowledgeBases
array[object]
No
List of searchable knowledge bases; an empty array or null means none can be searched (no permission); omitting it imposes no restriction
queryMetadata.labelRelations
object
No
Label filter conditions; an empty conditions array means no label filtering is applied (it does not mean no permission). Must be provided together with knowledgeBases — when provided alone, knowledge base retrieval does not apply label filtering (equivalent to no restriction)
queryMetadata.labelRelations.operator
string (enum: AND, OR)
Yes
How the label conditions are combined
queryMetadata.labelRelations.conditions
array[any]
No
List of label conditions; supports nested operator/conditions combinations
metadata
object
No
Message metadata, such as timezone and other environment information
broadcast
boolean
No
skipCopilotTrigger
boolean
No
spokenAt
number (double)
No
Voice agent only: when this transcript turn started (epoch seconds); dates the message by it.
suggestedForId
string (uuid)
No
skillIds
array[string]
No
Per-message selected skill IDs from the WebChat client (camelCase: skillIds).
toolIds
array[string]
No
Per-message selected tool IDs from the WebChat client (camelCase: toolIds).
templateId
string (uuid)
No
Document/sheet template ID for file-level compilation (camelCase: templateId).
Request Schema Example
Example Request Values
Code Examples
Response Body
Status Code: 201
Response Schema Example
Example Response Values
Send Outgoing Message
POST /api/v1/messages/outgoing/
Request Body
Request Parameters
conversation
string (uuid)
Yes
type
string
No
content
string
No
contentPayload
object
No
attachments
array[MessageAttachmentInput]
No
canvas
object
No
canvas.name
string
Yes
canvas.canvasType
object
Yes
canvas.title
string
Yes
canvas.content
string
Yes
slideTemplate
object (with 3 properties: slug, displayName, thumbnailUrls)
No
slideTemplate.slug
string
Yes
slideTemplate.displayName
string
Yes
slideTemplate.thumbnailUrls
array[string]
No
queryMetadata
object
No
Query metadata that controls which knowledge can be queried; see each endpoint's description
queryMetadata.knowledgeBases
array[object]
No
List of queryable knowledge bases; an empty array or null = nothing is queryable (no permission); omitted = no restriction
queryMetadata.labelRelations
object
No
Label filter conditions; an empty conditions array = no label filtering (not a lack of permission). Must be provided together with knowledgeBases; when provided alone, knowledge base retrieval does not apply label filtering (equivalent to no restriction)
queryMetadata.labelRelations.operator
string (enum: AND, OR)
Yes
How the label conditions are combined
queryMetadata.labelRelations.conditions
array[any]
No
List of label conditions; supports nested operator/conditions combinations
metadata
object
No
Message metadata, such as timezone and other environment information
broadcast
boolean
No
skipCopilotTrigger
boolean
No
spokenAt
number (double)
No
Voice agent only: when this transcript turn started (epoch seconds); dates the message by it.
suggestedForId
string (uuid)
No
skillIds
array[string]
No
Per-message selected skill IDs from the WebChat client (camelCase: skillIds).
toolIds
array[string]
No
Per-message selected tool IDs from the WebChat client (camelCase: toolIds).
templateId
string (uuid)
No
Document/sheet template ID for file-level compilation (camelCase: templateId).
Request Schema Example
Example Request Values
Code Examples
Response Body
Status Code: 201
Response Schema Example
Example Response Values
Create a New Conversation
POST /api/v1/conversations/
Request Body
Request Parameters
webChat
string (uuid)
Yes
contact
string (uuid)
No
clientPlatform
string (enum: web, desktop, extension)
No
web: Web ; desktop: Desktop ; extension: Extension;
workingDirectory
string
No
Request Schema Example
Request Example Value
Code Examples
Response Body
Status Code: 201
Response Schema Example
Response Example Value
Status code: 4XX - Error response; X-Error-Code carries its code (see "Error codes").
List Messages
GET /api/v1/messages/
Parameters
conversation
✅
string
Conversation ID
cursor
❌
string
The pagination cursor value.
pageSize
❌
integer
Number of results to return per page.
Code Examples
Response Body
Status Code: 200
Response Schema Example
Example Response Values
Retrieve a Specific Message
GET /api/v1/messages/{id}/
Parameters
id
✅
string
A UUID string identifying this Message.
conversation
✅
string
Conversation ID
Code Examples
Response
Status Code: 200
Response Schema Example
Response Example Value
List Conversations
GET /api/v1/conversations/
Parameters
assignee
❌
string
chatbot
❌
string
contact
❌
string
Contact ID
contactTags
❌
array
Multiple values may be separated by commas.
cursor
❌
string
The pagination cursor value.
endDate
❌
string
externalConversationId
❌
string
externalSource
❌
string
inbox
❌
string
Inbox ID
isPinned
❌
string
keyword
❌
string
Keyword search (title or message content); returns 400 if the search times out
kind
❌
string
`chat`: Chat ; `secretary`: Secretary;
mine
❌
boolean
mode
❌
string
`chat`: Chat ; `cowork`: Cowork;
pageSize
❌
integer
Number of results to return per page.
slackChannel
❌
string
startDate
❌
string
status
❌
array
`open`: Open ; `resolved`: Resolved ; `queued`: Queued;
tags
❌
array
Multiple values may be separated by commas.
unassigned
❌
boolean
updatedAfter
❌
string
Code Examples
Response
Status code: 200
Response Schema Example
Response Example Values
Status Code: 400 - The `keyword` search found no result within the time limit (about 16 seconds): enter a longer keyword, or specify a conversation platform and search again
Retrieve a Specific Conversation
GET /api/v1/conversations/{id}/
Parameters
id
✅
string
A UUID string identifying this Conversation.
Code Examples
Response
Status Code: 200
Response Schema Example
Response Example Value
Status code: 4XX - Error response; X-Error-Code carries its code (see "Error codes").
Rename Conversation
PATCH /api/v1/conversations/{id}/rename/
Parameters
id
✅
string
A UUID string identifying this Conversation.
Request Body
Request Parameters
title
string
No
Request Schema Example
Example Request Values
Code Examples
Response
Status code: 200
Response Schema Example
Example response values
Status code: 4XX - Error response; X-Error-Code carries its code (see "Error codes").
Delete Conversation
DELETE /api/v1/conversations/{id}/
Parameters
id
✅
string
A UUID string identifying this Conversation.
Code Examples
Response Body
204
No response body
4XX
Error response; X-Error-Code carries its code (see "Error codes").
Stop AI Response
POST /api/v1/conversations/{conversationId}/stop-response/
Parameters
conversationId
✅
string
Code Examples
Response Body
200
No response body
4XX
Error response; X-Error-Code carries its code (see "Error codes").
Submit Conversation Satisfaction
POST /api/v1/conversations/{id}/satisfaction/
Parameters
id
✅
string
A UUID string identifying this Conversation.
Request Body
Request Parameters
satisfactionScore
integer
Yes
Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied)
satisfactionComment
string
No
Request Schema Example
Example Request Values
Code Examples
Response Body
Status Code: 201
Response Schema Example
Example Response Values
Status Code: 409 - Satisfaction has already been submitted for this conversation
List Conversation Events
GET /api/v1/conversations/{id}/events/
Parameters
id
✅
string
A UUID string identifying this Conversation.
Code Examples
Response
Status code: 200
Response Schema Example
Response Example Values
Status code: 4XX - Error response; X-Error-Code carries its code (see "Error codes").
Assign Conversation to Member
PATCH /api/v1/conversations/{id}/assign/
Parameters
id
✅
string
A UUID string identifying this Conversation.
Request Body
Request Parameters
assignee
string (uuid)
No
transferReason
string
No
tagIds
array[string]
No
Request Schema Example
Request Example Values
Code Examples
Response
Status code: 200
Response Schema Example
Response Example Values
Status Code: 4XX - Error response; X-Error-Code carries its code (see "Error codes").
Claim Conversation
PATCH /api/v1/conversations/{id}/claim/
Parameters
id
✅
string
A UUID string identifying this Conversation.
Request Body
Request Parameters
transferReason
string
No
tagIds
array[string]
No
Request Schema Example
Request Example Values
Code Examples
Response Body
Status Code: 200
Response Schema Example
Example Response Values
Status Code: 4XX - Error response; X-Error-Code carries its code (see "Error codes").
Transfer a Conversation to Another Member
PATCH /api/v1/conversations/{id}/transfer/
Parameters
id
✅
string
A UUID string identifying this Conversation.
Request Body
Request Parameters
assignee
string (uuid)
No
transferReason
string
No
tagIds
array[string]
No
Request Schema Example
Example Request Values
Code Examples
Response Body
Status Code: 200
Response Schema Example
Response Example Values
Status Code: 4XX - Error response; X-Error-Code carries its code (see "Error codes").
Return to AI Reply
PATCH /api/v1/conversations/{id}/return-to-ai/
Parameters
id
✅
string
A UUID string identifying this Conversation.
Request Body
Request Parameters
requireContextReady
boolean
No
Request Schema Example
Request Example Values
Code Examples
Response Body
Status Code: 200
Response Schema Example
Response example
Status code: 409 - Agent context not ready: `detail` plus `agentContext` (pending / failed writes)
List Conversation Output Files
GET /api/v1/conversations/{conversationId}/outputs/
Parameters
conversationId
✅
string
Code Examples
Response Body
200
No response body
4XX
Error response; X-Error-Code carries its code (see "Error codes").
Share a Conversation
POST /api/v1/conversations/{conversationPk}/share/
Parameters
conversationPk
✅
string
Request Body
Request Parameters
shareScope
string (enum: organization, group, member)
Yes
organization: Organization ; group: Group ; member: Member;
permission
object
No
title
string
No
description
string
No
groupIds
array[string]
No
memberIds
array[string]
No
Example Request Schema
Example Request Values
Code Examples
Response Body
Status Code: 201
Example Response Schema
Example Response Values
Status Code: 4XX - Error response; X-Error-Code carries its code (see "Error codes").
Quick Share a Conversation
POST /api/v1/conversations/{conversationPk}/share/quick/
Parameters
conversationPk
✅
string
Request Body
Request Parameters
shareScope
string (enum: organization, group, member)
Yes
organization: Organization ; group: Group ; member: Member;
permission
object
No
title
string
No
description
string
No
groupIds
array[string]
No
memberIds
array[string]
No
Example Request Schema
Example Request Values
Code Examples
Response Body
Status Code: 200
Example Response Schema
Example Response Values
Status Code: 4XX - Error response; X-Error-Code carries its code (see "Error codes").
List Shared Conversations
GET /api/v1/shared-conversations/
Parameters
page
❌
integer
A page number within the paginated result set.
pageSize
❌
integer
Number of results to return per page.
Code Examples
Response Body
Status Code: 200
Example Response Schema
Example Response Values
Retrieve a Shared Conversation
GET /api/v1/shared-conversations/{id}/
Parameters
id
✅
string
A UUID string identifying this Shared Conversation.
Code Examples
Response Body
Status Code: 200
Example Response Schema
Example Response Values
Update a Shared Conversation
PATCH /api/v1/shared-conversations/{id}/
Parameters
id
✅
string
A UUID string identifying this Shared Conversation.
Request Body
Request Parameters
title
string
No
description
string
No
permission
string (enum: readonly, copy)
No
readonly: Read Only ; copy: Copyable;
shareScope
string (enum: organization, group, member)
No
organization: Organization ; group: Group ; member: Member;
groupIds
array[string]
No
memberIds
array[string]
No
Example Request Schema
Example Request Values
Code Examples
Response Body
Status code: 200
Example Response Schema
Example Response Values
Delete a Shared Conversation
DELETE /api/v1/shared-conversations/{id}/
Parameters
id
✅
string
A UUID string identifying this Shared Conversation.
Code Examples
Response Body
204
No response body
Fork a Shared Conversation
POST /api/v1/shared-conversations/{id}/fork/
Parameters
id
✅
string
A UUID string identifying this Shared Conversation.
Code Examples
Response Body
Status Code: 200
Example Response Schema
Example Response Values
Retrieve My Shared Conversations
GET /api/v1/shared-conversations/my-shares/
Code Examples
Response Body
Status Code: 200
Example Response Schema
Example Response Values
Create Message Feedback
POST /api/v1/messages/{messagePk}/feedback/
Parameters
messagePk
✅
string
Request Body
Request Parameters
type
object
Yes
suggestion
string
No
Example Request Schema
Example Request Values
Code Examples
Response Body
Status Code: 201
Example Response Schema
Example Response Values
Status Code: 400 - This message already has feedback. Use PATCH to update it.
Update Message Feedback
PUT /api/v1/messages/{messagePk}/feedback/{id}/
Parameters
id
✅
string
A UUID string identifying this Message Feedback.
messagePk
✅
string
Request Body
Request Parameters
type
object
Yes
suggestion
string
No
Example Request Schema
Example Request Values
Code Examples
Response Body
Status Code: 200
Example Response Schema
Example Response Values
Delete Message Feedback
DELETE /api/v1/messages/{messagePk}/feedback/{id}/
Parameters
id
✅
string
A UUID string identifying this Message Feedback.
messagePk
✅
string
Code Examples
Response Body
204
Feedback deleted successfully
400
This feedback does not belong to the specified message
List Conversation Records
GET /api/v1/records/
Parameters
callerMember
❌
array
Multiple values may be separated by commas.
chatbot
❌
string
Filter by a specific AI assistant (UUID)
endDate
❌
string
End date (format: YYYY-MM-DD, e.g., 2025-01-31)
endDatetime
❌
string
errorType
❌
array
Multiple values may be separated by commas. `system`: System ; `llm`: LLM ; `embedding`: Embedding ; `reranker`: Reranker ; `vector_db`: Vector DB ; `workflow`: Workflow ; `tool`: Tool ; `tool_limit`:...
excludeBuiltIn
❌
boolean
When true, excludes data from official built-in Agents (locked instances created by renting from the Agent marketplace) and keeps only assistants built by the organization; copies created via "Copy as custom" count as self-built. Omitting it or setting it to false behaves the same as not applying this filter.
feedbackType
❌
array
Multiple values may be separated by commas. `like`: Like ; `dislike`: Dislike;
hasError
❌
boolean
hasFeedback
❌
boolean
keyword
❌
string
Keyword search (searches both user messages and bot reply content). When a keyword is provided, the total is not calculated: `count` is a lower bound up to the first item of the next page, and `countLimited` set to true means there is a next page; only on the last page is `count` the exact total. If the search exceeds the time limit, a 400 is returned; narrow the date range or enter a more complete keyword
largeLanguageModel
❌
string
Filter by a specific large language model (UUID)
page
❌
integer
A page number within the paginated result set.
pageSize
❌
integer
Number of results to return per page.
source
❌
string
Filter by record source, comma-separated; when omitted, both sources are returned. interactive = user conversation, scheduled = scheduled run.
startDate
❌
string
Start date (format: YYYY-MM-DD, e.g., 2025-01-01)
startDatetime
❌
string
tool
❌
string
Code Examples
Response Body
Status code: 200
Response Schema Example
Example Response Values
Get a Specific Conversation Record
GET /api/v1/records/{id}/
Parameters
id
✅
string
A UUID string identifying this Chatbot Record.
Code Examples
Response Body
Status code: 200
Response Schema Example
Example Response Values
Status code: 404 - The specified conversation record was not found
Create Conversation Record Export Request
POST /api/v1/records/export-excel-requests/
Request Body
Request Parameters
chatbot
string
No
UUID of the Chatbot to export. Multiple UUIDs can be separated by commas. If left empty, all Chatbots in the organization that you have permission to access are exported.
chatbotId
string (uuid)
No
UUID of the Chatbot to export (an alias of chatbot; only a single UUID is supported).
keyword
string
No
Filter conversation records that contain a specific keyword (searches user messages and bot replies).
largeLanguageModel
string
No
UUID of the large language model to export. Multiple UUIDs can be separated by commas.
startDate
string (date)
No
Start date (YYYY-MM-DD), inclusive.
endDate
string (date)
No
End date (YYYY-MM-DD), inclusive.
startDatetime
string (timestamp)
No
Exact start time (ISO 8601, inclusive), with the same semantics as the list drill-down filter.
endDatetime
string (timestamp)
No
Exact end time (ISO 8601, exclusive), with the same semantics as the list drill-down filter.
hasError
boolean
No
Filter records by whether they have errors (true returns only records with errors, false returns only records without errors).
errorType
string
No
Filter by error type. Multiple values can be separated by commas (OR logic), with the same value range as the conversation record list.
hasFeedback
boolean
No
Filter by whether there is user feedback (true returns only records with a like/dislike, false returns only records without feedback).
feedbackType
string
No
Filter by user feedback type (like / dislike). Multiple values can be separated by commas (OR logic).
callerMember
string
No
Filter by speaking member UUID. Multiple values can be separated by commas (OR logic).
tool
string (uuid)
No
Filter Q&A in which the tool was called (tool UUID, including built-in platform tools; failed executions also count).
excludeBuiltIn
boolean
No
When true, excludes data from official built-in Agents (locked instances created by renting from the Agent marketplace) and keeps only assistants built by the organization; copies created with "Copy as custom" count as custom-built. Omitting it or setting it to false is the same as not applying this condition.
Request Schema Example
Example Request Values
Code Examples
Response Body
Status Code: 201
Response Schema Example
Example Response Values
Status Code: 4XX - Error response; X-Error-Code carries its code (see "Error codes").
Get Conversation Record Export Status
GET /api/v1/records/export-excel-requests/{exportId}/
Parameters
exportId
✅
string
Code Examples
Response Content
Status Code: 200
Response Schema Example
Response Example Values
Status Code: 4XX - Error response; X-Error-Code carries its code (see "Error codes").
Last updated
Was this helpful?