Conversations

MCP tools for the Conversations module. See the Conversations module docs for permissions and data model.

list-conversations

List conversations

Arguments

Argument	Type	Required	Description
project_id	string	no	Project ID (optional)
actor_id	string	no	Filter by actor ID
limit	number	no	Maximum number of results to return
offset	number	no	Number of results to skip

create-conversation

Create a conversation

Arguments

Argument	Type	Required	Description
project_id	string	no	Project ID. Required for JWT auth; omit when using an project key.
status	string	no	Initial conversation status
name	string | null	no	Optional name for the conversation
actor_id	string | null	no	Actor ID to associate with this conversation

get-conversation

Get a conversation by ID

Arguments

Argument	Type	Required	Description
conversation_id	string	yes	Conversation ID

update-conversation

Update a conversation

Arguments

Argument	Type	Required	Description
conversation_id	string	yes	Conversation ID
status	string	no	New conversation status
name	string | null	no	New conversation name

delete-conversation

Delete a conversation

Arguments

Argument	Type	Required	Description
conversation_id	string	yes	Conversation ID

list-conversation-messages

List conversation messages

Arguments

Argument	Type	Required	Description
conversation_id	string	yes	Conversation ID
limit	number	no	Maximum number of results to return
offset	number	no	Number of results to skip

add-conversation-message

Add a message to a conversation

Arguments

Argument	Type	Required	Description
conversation_id	string	yes	Conversation ID
message	string	yes	Message text content to add to the conversation
role	string	yes	Role of the message sender
actor_id	string | null	no	Optional actor ID to associate with this message (user identity)
position	number	no	Zero-based position. Defaults to MAX+1 (append).
metadata	object | null	no	Optional structured metadata to attach to the message (e.g. phone number, channel). Stored as-is and injected into the AI prompt context.

generate-conversation-message

Generate the next message in a conversation

Arguments

Argument	Type	Required	Description
conversation_id	string	yes	—
wait	boolean	no	When omitted or false (default), the generation runs in the background and 202 Accepted is returned immediately. Pass true to block until the generation settles and receive the result. A builtin tool call always waits.
agent_id	string	yes	ID of the agent that will produce the next message.
model	string	no	Optional model override.
stream	boolean	no	If true, stream tokens via SSE. NOT IMPLEMENTED in v1 — returns 501.
tool_context	object | null	no	Key-value pairs forwarded as X-Soat-Context-<key> headers on every http, mcp and builtin tool call in this generation. The header name is the deployment's configured context prefix (X-Soat-Context- by default) plus the key verbatim — no character is re-cased and keys are never case-converted, so they round-trip exactly as sent. An invalid or colliding key is rejected with 400 INVALID_TOOL_CONTEXT_KEY.

remove-conversation-message

Remove a message from a conversation

Arguments

Argument	Type	Required	Description
conversation_id	string	yes	Conversation ID
document_id	string	yes	Document ID

get-conversation-tags

Get conversation tags

Arguments

Argument	Type	Required	Description
conversation_id	string	yes	Conversation ID

replace-conversation-tags

Replace conversation tags

Arguments

Argument	Type	Required	Description
conversation_id	string	yes	Conversation ID

merge-conversation-tags

Merge conversation tags

Arguments

Argument	Type	Required	Description
conversation_id	string	yes	Conversation ID