Send Group Message
Process a user message and return the group's response. This endpoint accepts a message from a user and processes it through through agents in the group based on the specified pattern
ParametersExpand Collapse
group_id: str
The ID of the group in the format 'group-
Deprecatedassistant_message_tool_kwarg: Optional[str]
The name of the message argument in the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward.
Deprecatedassistant_message_tool_name: Optional[str]
The name of the designated message tool. Still supported for legacy agent types, but deprecated for letta_v1_agent onward.
Deprecatedenable_thinking: Optional[str]
If set to True, enables reasoning before responses or tool calls from the agent.
Only return specified message types in the response. If None (default) returns all messages.
input: Optional[Union[str, Iterable[InputUnionMember1], null]]
Syntactic sugar for a single user message. Equivalent to messages=[{'role': 'user', 'content': input}].
InputUnionMember1 = Iterable[InputUnionMember1]
class TextContent: …
text: str
The text content of the message.
signature: Optional[str]
Stores a unique identifier for any reasoning associated with this text content.
type: Optional[Literal["text"]]
The type of the message.
class ImageContent: …
source: Source
The source of the image.
class SourceURLImage: …
url: str
The URL of the image.
type: Optional[Literal["url"]]
The source type for the image.
class SourceBase64Image: …
data: str
The base64 encoded image data.
media_type: str
The media type for the image.
detail: Optional[str]
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
type: Optional[Literal["base64"]]
The source type for the image.
class SourceLettaImage: …
file_id: str
The unique identifier of the image file persisted in storage.
data: Optional[str]
The base64 encoded image data.
detail: Optional[str]
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
media_type: Optional[str]
The media type for the image.
type: Optional[Literal["letta"]]
The source type for the image.
type: Optional[Literal["image"]]
The type of the message.
class ToolCallContent: …
id: str
A unique identifier for this specific tool call instance.
input: Dict[str, object]
The parameters being passed to the tool, structured as a dictionary of parameter names to values.
name: str
The name of the tool being called.
signature: Optional[str]
Stores a unique identifier for any reasoning associated with this tool call.
type: Optional[Literal["tool_call"]]
Indicates this content represents a tool call event.
class ToolReturnContent: …
content: str
The content returned by the tool execution.
is_error: bool
Indicates whether the tool execution resulted in an error.
tool_call_id: str
References the ID of the ToolCallContent that initiated this tool call.
type: Optional[Literal["tool_return"]]
Indicates this content represents a tool return event.
class ReasoningContent: …
Sent via the Anthropic Messages API
is_native: bool
Whether the reasoning content was generated by a reasoner model that processed this step.
reasoning: str
The intermediate reasoning or thought process content.
signature: Optional[str]
A unique identifier for this reasoning step.
type: Optional[Literal["reasoning"]]
Indicates this is a reasoning/intermediate step.
class RedactedReasoningContent: …
Sent via the Anthropic Messages API
data: str
The redacted or filtered intermediate reasoning content.
type: Optional[Literal["redacted_reasoning"]]
Indicates this is a redacted thinking step.
class OmittedReasoningContent: …
A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions)
signature: Optional[str]
A unique identifier for this reasoning step.
type: Optional[Literal["omitted_reasoning"]]
Indicates this is an omitted reasoning step.
class InputUnionMember1SummarizedReasoningContent: …
The style of reasoning content returned by the OpenAI Responses API
id: str
The unique identifier for this reasoning step.
summary: Iterable[InputUnionMember1SummarizedReasoningContentSummary]
Summaries of the reasoning content.
index: int
The index of the summary part.
text: str
The text of the summary part.
encrypted_content: Optional[str]
The encrypted reasoning content.
type: Optional[Literal["summarized_reasoning"]]
Indicates this is a summarized reasoning step.
max_steps: Optional[int]
Maximum number of steps the agent should take to process the request.
messages: Optional[Iterable[Message]]
The messages to be sent to the agent.
class MessageCreate: …
Request to create a message
The content of the message.
class TextContent: …
text: str
The text content of the message.
signature: Optional[str]
Stores a unique identifier for any reasoning associated with this text content.
type: Optional[Literal["text"]]
The type of the message.
class ImageContent: …
source: Source
The source of the image.
class SourceURLImage: …
url: str
The URL of the image.
type: Optional[Literal["url"]]
The source type for the image.
class SourceBase64Image: …
data: str
The base64 encoded image data.
media_type: str
The media type for the image.
detail: Optional[str]
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
type: Optional[Literal["base64"]]
The source type for the image.
class SourceLettaImage: …
file_id: str
The unique identifier of the image file persisted in storage.
data: Optional[str]
The base64 encoded image data.
detail: Optional[str]
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
media_type: Optional[str]
The media type for the image.
type: Optional[Literal["letta"]]
The source type for the image.
type: Optional[Literal["image"]]
The type of the message.
class ToolCallContent: …
id: str
A unique identifier for this specific tool call instance.
input: Dict[str, object]
The parameters being passed to the tool, structured as a dictionary of parameter names to values.
name: str
The name of the tool being called.
signature: Optional[str]
Stores a unique identifier for any reasoning associated with this tool call.
type: Optional[Literal["tool_call"]]
Indicates this content represents a tool call event.
class ToolReturnContent: …
content: str
The content returned by the tool execution.
is_error: bool
Indicates whether the tool execution resulted in an error.
tool_call_id: str
References the ID of the ToolCallContent that initiated this tool call.
type: Optional[Literal["tool_return"]]
Indicates this content represents a tool return event.
class ReasoningContent: …
Sent via the Anthropic Messages API
is_native: bool
Whether the reasoning content was generated by a reasoner model that processed this step.
reasoning: str
The intermediate reasoning or thought process content.
signature: Optional[str]
A unique identifier for this reasoning step.
type: Optional[Literal["reasoning"]]
Indicates this is a reasoning/intermediate step.
class RedactedReasoningContent: …
Sent via the Anthropic Messages API
data: str
The redacted or filtered intermediate reasoning content.
type: Optional[Literal["redacted_reasoning"]]
Indicates this is a redacted thinking step.
class OmittedReasoningContent: …
A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions)
signature: Optional[str]
A unique identifier for this reasoning step.
type: Optional[Literal["omitted_reasoning"]]
Indicates this is an omitted reasoning step.
role: Literal["user", "system", "assistant"]
The role of the participant.
batch_item_id: Optional[str]
The id of the LLMBatchItem that this message is associated with
group_id: Optional[str]
The multi-agent group that the message was sent in
name: Optional[str]
The name of the participant.
otid: Optional[str]
The offline threading id associated with this message
sender_id: Optional[str]
The id of the sender of the message, can be an identity id or agent id
type: Optional[Literal["message"]]
The message type to be created.
class ApprovalCreate: …
Input to approve or deny a tool call request
Deprecatedapproval_request_id: Optional[str]
The message ID of the approval request
approvals: Optional[List[Approval]]
The list of approval responses
class ApprovalApprovalReturn: …
approve: bool
Whether the tool has been approved
tool_call_id: str
The ID of the tool call that corresponds to this approval
reason: Optional[str]
An optional explanation for the provided approval status
type: Optional[Literal["approval"]]
The message type to be created.
class ToolReturn: …
status: Literal["success", "error"]
type: Optional[Literal["tool"]]
The message type to be created.
Deprecatedapprove: Optional[bool]
Whether the tool has been approved
group_id: Optional[str]
The multi-agent group that the message was sent in
Deprecatedreason: Optional[str]
An optional explanation for the provided approval status
type: Optional[Literal["approval"]]
The message type to be created.
Whether the server should parse specific tool call arguments (default send_message) as AssistantMessage objects. Still supported for legacy agent types, but deprecated for letta_v1_agent onward.
ReturnsExpand Collapse
class LettaResponse: …
Response object from an agent interaction, consisting of the new messages generated by the agent and usage statistics.
The type of the returned messages can be either Message or LettaMessage, depending on what was specified in the request.
Attributes: messages (List[Union[Message, LettaMessage]]): The messages returned by the agent. usage (LettaUsageStatistics): The usage statistics
The messages returned by the agent.
class SystemMessage: …
A message generated by the system. Never streamed back on a response, only used for cursor pagination.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system
content: str
The message content sent by the system
message_type: Optional[Literal["system_message"]]
The type of the message.
class UserMessage: …
A message sent by the user. Never streamed back on a response, only used for cursor pagination.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts)
The message content sent by the user (can be a string or an array of multi-modal content parts)
class TextContent: …
text: str
The text content of the message.
signature: Optional[str]
Stores a unique identifier for any reasoning associated with this text content.
type: Optional[Literal["text"]]
The type of the message.
class ImageContent: …
source: Source
The source of the image.
class SourceURLImage: …
url: str
The URL of the image.
type: Optional[Literal["url"]]
The source type for the image.
class SourceBase64Image: …
data: str
The base64 encoded image data.
media_type: str
The media type for the image.
detail: Optional[str]
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
type: Optional[Literal["base64"]]
The source type for the image.
class SourceLettaImage: …
file_id: str
The unique identifier of the image file persisted in storage.
data: Optional[str]
The base64 encoded image data.
detail: Optional[str]
What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)
media_type: Optional[str]
The media type for the image.
type: Optional[Literal["letta"]]
The source type for the image.
type: Optional[Literal["image"]]
The type of the message.
message_type: Optional[Literal["user_message"]]
The type of the message.
class ReasoningMessage: …
Representation of an agent's internal reasoning.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message source (Literal["reasoner_model", "non_reasoner_model"]): Whether the reasoning content was generated natively by a reasoner model or derived via prompting reasoning (str): The internal reasoning of the agent signature (Optional[str]): The model-generated signature of the reasoning step
message_type: Optional[Literal["reasoning_message"]]
The type of the message.
source: Optional[Literal["reasoner_model", "non_reasoner_model"]]
class HiddenReasoningMessage: …
Representation of an agent's internal reasoning where reasoning content has been hidden from the response.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message state (Literal["redacted", "omitted"]): Whether the reasoning content was redacted by the provider or simply omitted by the API hidden_reasoning (Optional[str]): The internal reasoning of the agent
state: Literal["redacted", "omitted"]
message_type: Optional[Literal["hidden_reasoning_message"]]
The type of the message.
class ToolCallMessage: …
A message representing a request to call a tool (generated by the LLM to trigger tool execution).
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (Union[ToolCall, ToolCallDelta]): The tool call
Deprecatedtool_call: ToolCall
class ToolCall: …
class ToolCallDelta: …
message_type: Optional[Literal["tool_call_message"]]
The type of the message.
tool_calls: Optional[ToolCalls]
class ToolCallDelta: …
class ToolReturnMessage: …
A message representing the return value of a tool call (generated by Letta executing the requested tool).
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_return (str): The return value of the tool (deprecated, use tool_returns) status (Literal["success", "error"]): The status of the tool call (deprecated, use tool_returns) tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns) stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns) stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns) tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support
Deprecatedstatus: Literal["success", "error"]
message_type: Optional[Literal["tool_return_message"]]
The type of the message.
status: Literal["success", "error"]
type: Optional[Literal["tool"]]
The message type to be created.
class AssistantMessage: …
A message sent by the LLM in response to user input. Used in the LLM context.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts)
The message content sent by the agent (can be a string or an array of content parts)
text: str
The text content of the message.
signature: Optional[str]
Stores a unique identifier for any reasoning associated with this text content.
type: Optional[Literal["text"]]
The type of the message.
message_type: Optional[Literal["assistant_message"]]
The type of the message.
class ApprovalRequestMessage: …
A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution).
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call
Deprecatedtool_call: ToolCall
The tool call that has been requested by the llm to run
class ToolCall: …
class ToolCallDelta: …
message_type: Optional[Literal["approval_request_message"]]
The type of the message.
tool_calls: Optional[ToolCalls]
The tool calls that have been requested by the llm to run, which are pending approval
class ToolCallDelta: …
class ApprovalResponseMessage: …
A message representing a response form the user indicating whether a tool has been approved to run.
Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message approve: (bool) Whether the tool has been approved approval_request_id: The ID of the approval request reason: (Optional[str]) An optional explanation for the provided approval status
Deprecatedapproval_request_id: Optional[str]
The message ID of the approval request
approvals: Optional[List[Approval]]
The list of approval responses
class ApprovalApprovalReturn: …
approve: bool
Whether the tool has been approved
tool_call_id: str
The ID of the tool call that corresponds to this approval
reason: Optional[str]
An optional explanation for the provided approval status
type: Optional[Literal["approval"]]
The message type to be created.
class ToolReturn: …
status: Literal["success", "error"]
type: Optional[Literal["tool"]]
The message type to be created.
Deprecatedapprove: Optional[bool]
Whether the tool has been approved
message_type: Optional[Literal["approval_response_message"]]
The type of the message.
Deprecatedreason: Optional[str]
An optional explanation for the provided approval status
class SummaryMessage: …
A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider.
message_type: Optional[Literal["summary"]]
class EventMessage: …
A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window.
event_type: Literal["compaction"]
message_type: Optional[Literal["event"]]
stop_reason: StopReason
The stop reason from Letta indicating why agent loop stopped execution.
The reason why execution stopped.
message_type: Optional[Literal["stop_reason"]]
The type of the message.
usage: Usage
The usage statistics of the agent.
completion_tokens: Optional[int]
The number of tokens generated by the agent.
message_type: Optional[Literal["usage_statistics"]]
prompt_tokens: Optional[int]
The number of tokens in the prompt.
run_ids: Optional[List[str]]
The background task run IDs associated with the agent interaction
step_count: Optional[int]
The number of steps taken by the agent.
total_tokens: Optional[int]
The total number of tokens processed by the agent.
Send Group Message
- HTTP
- TypeScript
- Python
from letta_client import Letta
client = Letta(
api_key="My API Key",
)
letta_response = client.groups.messages.send(
group_id="group-123e4567-e89b-42d3-8456-426614174000",
)
print(letta_response.messages)
{
"messages": [
{
"id": "id",
"content": "content",
"date": "2019-12-27T18:11:19.117Z",
"is_err": true,
"message_type": "system_message",
"name": "name",
"otid": "otid",
"run_id": "run_id",
"sender_id": "sender_id",
"seq_id": 0,
"step_id": "step_id"
}
],
"stop_reason": {
"stop_reason": "end_turn",
"message_type": "stop_reason"
},
"usage": {
"completion_tokens": 0,
"message_type": "usage_statistics",
"prompt_tokens": 0,
"run_ids": [
"string"
],
"step_count": 0,
"total_tokens": 0
}
}Returns Examples
{
"messages": [
{
"id": "id",
"content": "content",
"date": "2019-12-27T18:11:19.117Z",
"is_err": true,
"message_type": "system_message",
"name": "name",
"otid": "otid",
"run_id": "run_id",
"sender_id": "sender_id",
"seq_id": 0,
"step_id": "step_id"
}
],
"stop_reason": {
"stop_reason": "end_turn",
"message_type": "stop_reason"
},
"usage": {
"completion_tokens": 0,
"message_type": "usage_statistics",
"prompt_tokens": 0,
"run_ids": [
"string"
],
"step_count": 0,
"total_tokens": 0
}
}