Message
Chat message
Usage profiles
| Usage | Fields and validation |
|---|---|
| In requests | View fields |
| In responses | View fields |
| In webhook payloads | View fields |
In requests
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
role | string (ROLE_SYSTEM, ROLE_USER, ROLE_ASSISTANT, ROLE_TOOL) or integer (int32) (1, 2, 3, 4) | Required in requests | Role of the participant that produced the chat message. |
content | Array of ContentPart | Optional | Content parts composing the chat message. |
toolCalls | Array of ToolCall | Optional | Assistant-to-tool invocations. |
name | string | Optional | Name identifying the sender of the chat message. |
timestamp | string (date-time) | Optional | Timestamp associated with the conversation message or event. |
messageId | string | Optional | Unique message identifier. |
annotations | Array of Annotation | Optional | Structured annotations (e.g., standardized web search URL citations, PDF reuse tokens) |
sequence | string (int64) | Optional | Monotonic, per-conversation sequence number for stable ordering (1-based) Pattern: ^-?\d+$. |
generatedBy | string | Optional | Workflow run id or generator key that produced this message (e.g., workflow run key) |
usage | Usage | Optional | Token usage for this generation (populated for assistant messages) |
model | string | Optional | Model that generated this message (e.g., "anthropic/claude-sonnet-4") |
generationContext | GenerationContext | Optional | Dynamic context that shaped this generation (memories, search params, turn info) |
clientContext | ClientContext | Optional | Arbitrary client-supplied context attached by the client for this message |
feedback | Array of MessageFeedback | Optional | Feedback on an assistant message, with one entry per rater identified by rated_by. A later rating by the same rater replaces their earlier entry. |
sourceUserMessageId | string | Optional | Identifier of the user message that opened this conversation turn. Generated messages in the same turn share this value; a user message carries its own message_id. Empty on historical messages that predate turn attribution. |
finishReason | string | Optional | Why the model stopped, verbatim from the provider: "stop", "tool_calls", "length", "error". Empty for historical messages. |
Values of role
Participant role attached to a conversation message and forwarded in model context.
| Value | No. | Form | Meaning |
|---|---|---|---|
ROLE_SYSTEM | 1 | Canonical | Instructions or context provided as a system message. |
ROLE_USER | 2 | Canonical | Input supplied by the user or customer application. |
ROLE_ASSISTANT | 3 | Canonical | Content produced by the assistant, including its tool-call requests. |
ROLE_TOOL | 4 | Canonical | A tool result supplied back to the assistant. |
Request validation
These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules.
| Applies to | Rule | Requirement |
|---|---|---|
| Message | message_content_or_tool_calls | content or tool_calls required |
role | Defined enum value | true |
role | Disallowed values | 0 |
In responses
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
role | string (ROLE_SYSTEM, ROLE_USER, ROLE_ASSISTANT, ROLE_TOOL) or integer (int32) | Required in requests | Role of the participant that produced the chat message. |
content | Array of ContentPart | Optional | Content parts composing the chat message. |
toolCalls | Array of ToolCall | Optional | Assistant-to-tool invocations. |
name | string | Optional | Name identifying the sender of the chat message. |
timestamp | string (date-time) | Optional | Timestamp associated with the conversation message or event. |
messageId | string | Optional | Unique message identifier. |
annotations | Array of Annotation | Optional | Structured annotations (e.g., standardized web search URL citations, PDF reuse tokens) |
sequence | string (int64) | Optional | Monotonic, per-conversation sequence number for stable ordering (1-based) Pattern: ^-?\d+$. |
generatedBy | string | Optional | Workflow run id or generator key that produced this message (e.g., workflow run key) |
usage | Usage | Optional | Token usage for this generation (populated for assistant messages) |
model | string | Optional | Model that generated this message (e.g., "anthropic/claude-sonnet-4") |
generationContext | GenerationContext | Optional | Dynamic context that shaped this generation (memories, search params, turn info) |
clientContext | ClientContext | Optional | Arbitrary client-supplied context attached by the client for this message |
feedback | Array of MessageFeedback | Optional | Feedback on an assistant message, with one entry per rater identified by rated_by. A later rating by the same rater replaces their earlier entry. |
sourceUserMessageId | string | Optional | Identifier of the user message that opened this conversation turn. Generated messages in the same turn share this value; a user message carries its own message_id. Empty on historical messages that predate turn attribution. |
finishReason | string | Optional | Why the model stopped, verbatim from the provider: "stop", "tool_calls", "length", "error". Empty for historical messages. |
Values of role
Participant role attached to a conversation message and forwarded in model context.
| Value | No. | Form | Meaning |
|---|---|---|---|
ROLE_SYSTEM | 1 | Canonical | Instructions or context provided as a system message. |
ROLE_USER | 2 | Canonical | Input supplied by the user or customer application. |
ROLE_ASSISTANT | 3 | Canonical | Content produced by the assistant, including its tool-call requests. |
ROLE_TOOL | 4 | Canonical | A tool result supplied back to the assistant. |
Request validation
These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules.
| Applies to | Rule | Requirement |
|---|---|---|
| Message | message_content_or_tool_calls | content or tool_calls required |
role | Defined enum value | true |
role | Disallowed values | 0 |
In webhook payloads
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
role | string (ROLE_SYSTEM, ROLE_USER, ROLE_ASSISTANT, ROLE_TOOL) or integer (int32) | Required in requests | Role of the participant that produced the chat message. |
content | Array of ContentPart | Optional | Content parts composing the chat message. |
tool_calls | Array of ToolCall | Optional | Assistant-to-tool invocations. |
name | string | Optional | Name identifying the sender of the chat message. |
timestamp | string (date-time) | Optional | Timestamp associated with the conversation message or event. |
message_id | string | Optional | Unique message identifier. |
annotations | Array of Annotation | Optional | Structured annotations (e.g., standardized web search URL citations, PDF reuse tokens) |
sequence | string (int64) | Optional | Monotonic, per-conversation sequence number for stable ordering (1-based) Pattern: ^-?\d+$. |
generated_by | string | Optional | Workflow run id or generator key that produced this message (e.g., workflow run key) |
usage | Usage | Optional | Token usage for this generation (populated for assistant messages) |
model | string | Optional | Model that generated this message (e.g., "anthropic/claude-sonnet-4") |
generation_context | GenerationContext | Optional | Dynamic context that shaped this generation (memories, search params, turn info) |
client_context | ClientContext | Optional | Arbitrary client-supplied context attached by the client for this message |
feedback | Array of MessageFeedback | Optional | Feedback on an assistant message, with one entry per rater identified by rated_by. A later rating by the same rater replaces their earlier entry. |
source_user_message_id | string | Optional | Identifier of the user message that opened this conversation turn. Generated messages in the same turn share this value; a user message carries its own message_id. Empty on historical messages that predate turn attribution. |
finish_reason | string | Optional | Why the model stopped, verbatim from the provider: "stop", "tool_calls", "length", "error". Empty for historical messages. |
Values of role
Participant role attached to a conversation message and forwarded in model context.
| Value | No. | Form | Meaning |
|---|---|---|---|
ROLE_SYSTEM | 1 | Canonical | Instructions or context provided as a system message. |
ROLE_USER | 2 | Canonical | Input supplied by the user or customer application. |
ROLE_ASSISTANT | 3 | Canonical | Content produced by the assistant, including its tool-call requests. |
ROLE_TOOL | 4 | Canonical | A tool result supplied back to the assistant. |
Request validation
These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules.
| Applies to | Rule | Requirement |
|---|---|---|
| Message | message_content_or_tool_calls | content or tool_calls required |
role | Defined enum value | true |
role | Disallowed values | 0 |
Where used
| Reference | Relationship |
|---|---|
| Append a message without generating | POST /api/v1/llm/append-message |
| Send a message to a conversation | POST /api/v1/llm/send-message |
| Send a message and wait for the result | POST /api/v1/llm/send-message-sync |
| Withdraw your rating on a message | POST /api/v1/llm/delete-message-rating |
| Get full conversation state | POST /api/v1/llm/conversation-state |
| Rate an assistant message | POST /api/v1/llm/rate-message |
| Submit client-side tool results and wait for the next segment | POST /api/v1/llm/submit-client-tool-results-sync |
| llm.message_published | Webhook JSON uses protobuf field names (snake_case). |
| LLMMessagePublishedEvent | Nested in model |
Download the public reference contract.
Document: DOC-API-MODEL-message.