Skip to content

AIChatSendMessage

POST ai/chat/message

Queues a question and returns at once with a runId. It does not wait for the model — an answer takes tens of seconds and the platform closes a call after five, so the interface shows an indicator and then either listens to events or polls AIChatGetRun.

Access Control

Allowed: client, manager, admin. Only inside a conversation of the current session.

Request

POST request
POST https://{broker_domain}/ai/chat/message
Authorization: <JWT_TOKEN>
Content-Type: application/json

{
  "conversationId": "cnv_8f3a…",
  "content": "Why was position 500103 closed?",
  "requestId": "b1f0-4c2e-…",
  "route": "/backoffice/trades"
}

{
  "command": "AIChatSendMessage",
  "extID": "1",
  "data": {
    "conversationId": "cnv_8f3a…",
    "content": "Why was position 500103 closed?",
    "requestId": "b1f0-4c2e-…"
  }
}

const run = await platform.AIChatSendMessage({
  conversationId, content: 'Why was position 500103 closed?', requestId
});

Parameters

Parameter Type Description
conversationId string Conversation to ask in
content string The question, 1 to 8000 characters
requestId string Optional but recommended, up to 128 characters. See below
route string Optional. The current interface screen, for example /backoffice/groups
accountLogin int Account context. Required for a client session of an account owner
symbol string Optional. The instrument the user is looking at
ui object Optional. Current interface state: theme, language, platform, route, activePanel, timeframe
capability string StScript assistant only: stscript.assistant, must match the conversation
protocolVersion int StScript assistant only: 1
operation string StScript assistant only: auto (the assistant decides), generate, explain, analyze, fix or modify. A hint, not an obligation: a question about the code gets an answer without a proposal
editorContext object StScript assistant only, required in that mode: the snapshot of the open editor document. Strict schema — see editor snapshot

The StScript fields belong only to a conversation created with capability. Sending them to a regular conversation, or omitting them in a code conversation, is AI_CAPABILITY_MISMATCH. Never put the source into content: the snapshot goes to editorContext.source (up to 64 000 UTF-16 code units), content stays the task description.

requestId is generated by the interface. Repeating it returns the existing run with idempotent: true instead of paying for a second answer — protection against a double click, a network retry and a page reload during send.

ui keeps the assistant from stating the obvious. Knowing the current theme, language and open panel, it stops offering to enable what is already on — see Interface actions. Every field is optional on its own; send what you know.

route improves the answer. A knowledge document attached to that screen is ranked higher, so the same question asked from the groups screen and from the trades screen gets different, more specific answers.

Response Data

{
  "runId": "run_55b…",
  "messageId": "msg_1c7…",
  "state": "queued",
  "idempotent": false
}

messageId is the id of the user message that was just stored — use it to render the bubble immediately. The answer gets its own id, returned by AIChatGetRun in result.messageId.

Errors

Code Error Description
402 AI_BUDGET_EXCEEDED The agent's daily request, token or cost limit is reached
403 AI_ACCESS_DENIED The conversation belongs to another session
404 AI_CONVERSATION_NOT_FOUND No such conversation in this scope
409 AI_CONVERSATION_BUSY A run is already active in this conversation
409 AI_AGENT_DISABLED The conversation's agent is disabled or not allowed in this chat
503 AI_QUEUE_FULL The service queue is full
503 AI_KNOWLEDGE_NOT_READY The knowledge index is still building

StScript assistant requests add the errors below. All of them are returned before the model is called.

Code Error Description
400 AI_STSCRIPT_CONTEXT_REQUIRED No editorContext
400 AI_STSCRIPT_CONTEXT_INVALID Wrong schema or unknown field, unknown operation, invalid selection, sourceHash does not match, empty source for an operation that needs code
400 AI_STSCRIPT_KIND_MISMATCH editorContext.kind contradicts the script(...) declaration
403 AI_CAPABILITY_DISABLED The capability is not available in this scope
409 AI_CAPABILITY_MISMATCH Capability or protocol do not match the conversation
409 AI_REQUEST_ID_CONFLICT The requestId was already used with a different payload or by another session
409 AI_STSCRIPT_RUNTIME_UNSUPPORTED runtimeId / referenceVersion are not the ones of AIGetCapabilities
413 AI_STSCRIPT_SOURCE_TOO_LARGE Source over 64 000 UTF-16 code units or body over 1 MiB
429 AI_RATE_LIMITED Another code request of this session is running, or an hourly quota is reached
503 AI_STSCRIPT_VALIDATOR_UNAVAILABLE The server check cannot run now

In this mode a repeated requestId returns the existing run only when the payload is the same; the same key with another text, operation or source is a conflict, not a new answer.

AI_CONVERSATION_BUSY is expected behaviour, not a failure: one run per conversation. Disable the input while an answer is being written instead of catching the error.