Skip to main content
await sdk.instance.send_message(
    content,
    role="user",
    conversation_id=None,
    user_id=None,
    customer_id=None,
    session_id=None,
    event_type="user_message",
    metadata=None,
    tool_name=None,
    tool_args=None,
    search_queries=None,
    context_types=None,
)
Advanced: for real-time integrations. Requires an active instance.listen stream. If the stream is not active, this call raises ListeningNotActiveError.
send_message() publishes a single agent activity event onto the bidirectional gRPC stream that listen() established. Each event tells the Synap platform what just happened in your agent (a user turn, an assistant reply, a tool call, or an explicit context request) so the platform can anticipate what context the agent will need next and push it back over the stream.

​
Parameters

​
content
string
required
The message content. For user_message and assistant_message events this is the natural-language turn; for tool_call events it can be a short description of the tool invocation.
​
role
string
default:"user"
Either "user" or "assistant".
​
conversation_id
string
External identifier for the conversation this event belongs to. Required to associate the event with the right conversation scope. Must be a valid UUID registered via record_message.
​
user_id
string
External user identifier. Omit for customer- or client-scope events.
​
customer_id
string
External customer identifier. Required on B2B; auto-resolved on B2C. See B2C vs B2B.
​
session_id
string
External session identifier.
​
event_type
string
default:"user_message"
The kind of event being reported. Common values: user_message, assistant_message, tool_call, context_request.
​
metadata
dict[str, str]
Additional string key-value metadata attached to the event.
​
tool_name
string
For tool_call events: the name of the tool the agent is invoking. The platform uses this to classify the tool call and anticipate the agent’s next data needs.
​
tool_args
dict
For tool_call events: a JSON-encodable arguments dict for the tool invocation.
​
search_queries
list[string]
For tool_call or context_request events: the retrieval queries the agent plans to run. Used as direct anticipation hints.
​
context_types
list[string]
For tool_call or context_request events: the memory categories the agent plans to fetch.

​
Returns

Returns None. The coroutine resolves once the event has been written to the stream.

​
Example

import uuid

# conversation_id must be a valid UUID; reuse the one for the active conversation
conversation_id = str(uuid.uuid4())

await sdk.instance.send_message(
    content="search_orders",
    role="assistant",
    event_type="tool_call",
    conversation_id=conversation_id,
    user_id="user_789",
    customer_id="cust_456",
    tool_name="search_orders",
    tool_args={"status": "shipped", "limit": 5},
    search_queries=["recent shipped orders"],
    context_types=["order_history"],
)

​
Raises

  • ListeningNotActiveError: when instance.listen has not been called or the stream has been closed.
See Error Codes for the full SDK exception hierarchy.

​
See also