ai.v1.AssistantService

SendMessage

SendMessage records the caller's message and starts a run that answers it. It returns once the run is recorded; follow the run with WatchRun. A conversation runs one run at a time. It is idempotent per caller and key: repeat the request unchanged to resolve an unknown outcome. Errors: - INVALID_ARGUMENT: malformed request. - NOT_FOUND: CONVERSATION_NOT_FOUND. - FAILED_PRECONDITION: RUN_ACTIVE; nothing is recorded. - ALREADY_EXISTS: IDEMPOTENCY_CONFLICT; the original run stands. - RESOURCE_EXHAUSTED: USAGE_LIMIT_REACHED; retry later. - UNAVAILABLE, DEADLINE_EXCEEDED: SERVICE_UNAVAILABLE or an unknown outcome; retry the same request. - UNAUTHENTICATED: missing or invalid credentials.

Method

POST

Path

ai.v1.AssistantService/SendMessage

Service

ai.v1.AssistantService

Visibility

Authentication required

Authentication

Session token

MFA Requirement

Not required

POST

ai.v1.AssistantService/SendMessage

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/ai.v1.AssistantService/SendMessage' \
  --header 'Content-Type: application/json' \
  --header 'Connect-Protocol-Version: 1' \
  --data '{
  "conversationId": "1",
  "destinations": [
    {
      "description": "Example configuration for the API playground.",
      "id": "value",
      "title": "My Trading Board"
    }
  ],
  "idempotencyKey": "idem_01J5EXAMPLE0000000000000",
  "subaccountId": "6789012345678",
  "text": "example"
}'

Responses

{
  "conversationId": "1",
  "runId": "1"
}

Request

ai.v1.SendMessageRequest

Response

ai.v1.SendMessageResponse

conversationId string (fixed64) > 0

Conversation to continue. Omit to start a new conversation.

text string 1-16000 chars

Message text, plain text or Markdown, 1 to 16000 characters.

idempotencyKey string /^[A-Za…,128}$/

Client-chosen key, unique per caller, that makes sending idempotent: the same key and request return the same run and conversation, also for a new conversation; another request with the same key is IDEMPOTENCY_CONFLICT.

subaccountId string (fixed64) > 0

Trading account (subaccount) the run reads and acts on. It must be one the caller's account owns; any other value, also one that does not exist, is INVALID_ARGUMENT. Omit it to answer without account data: the run then has no account tools. It is part of the request the idempotency key covers. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).

destinations object[] max 100 items

The places in the client the run may suggest to the user, at most 100, each id at most once; their order does not matter. Omit them for a client that cannot take the user anywhere: the run then suggests nothing. They are part of the request the idempotency key covers.

Edit in JSON

runId string (fixed64)

The run that answers the message. Follow it with WatchRun.

conversationId string (fixed64)

The conversation of the message: the requested one, or the new one.

Possible errors: 5

Key	HTTP status	Connect code	Error	When
unauthenticated	401	unauthenticated	Unauthenticated	Authentication required.
permission-denied	403	permission_denied	Permission Denied	Permission denied.
invalid-argument	400	invalid_argument	Invalid Argument	Invalid argument.
not-found	404	not_found	Not Found	Not found.
unavailable	503	unavailable	Unavailable	Service unavailable.