> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maximem.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# instance.send_message

> Send a conversation event over the active gRPC stream so Synap can anticipate context for the agent's next turn.

```python theme={null}
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,
)
```

<Note>
  Advanced: for real-time integrations. Requires an active [`instance.listen`](/sdk-reference/instance/listen) stream. If the stream is not active, this call raises `ListeningNotActiveError`.
</Note>

`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

<ParamField path="content" type="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.
</ParamField>

<ParamField path="role" type="string" default="user">
  Either `"user"` or `"assistant"`.
</ParamField>

<ParamField path="conversation_id" type="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`](/concepts/context-end-to-end#short-term-context).
</ParamField>

<ParamField path="user_id" type="string">
  External user identifier. Omit for customer- or client-scope events.
</ParamField>

<ParamField path="customer_id" type="string">
  External customer identifier. Required on B2B; auto-resolved on B2C. See [B2C vs B2B](/concepts/memory-scopes#b2c-vs-b2b-which-scopes-apply-to-you).
</ParamField>

<ParamField path="session_id" type="string">
  External session identifier.
</ParamField>

<ParamField path="event_type" type="string" default="user_message">
  The kind of event being reported. Common values: `user_message`, `assistant_message`, `tool_call`, `context_request`.
</ParamField>

<ParamField path="metadata" type="dict[str, str]">
  Additional string key-value metadata attached to the event.
</ParamField>

<ParamField path="tool_name" type="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.
</ParamField>

<ParamField path="tool_args" type="dict">
  For `tool_call` events: a JSON-encodable arguments dict for the tool invocation.
</ParamField>

<ParamField path="search_queries" type="list[string]">
  For `tool_call` or `context_request` events: the retrieval queries the agent plans to run. Used as direct anticipation hints.
</ParamField>

<ParamField path="context_types" type="list[string]">
  For `tool_call` or `context_request` events: the memory categories the agent plans to fetch.
</ParamField>

### Returns

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

### Example

```python theme={null}
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`](/sdk-reference/instance/listen) has not been called or the stream has been closed.

See [Error Codes](/sdk-reference/errors) for the full SDK exception hierarchy.

### See also

* [instance.listen](/sdk-reference/instance/listen): open the stream this method writes to.
* [instance.stop\_listening](/sdk-reference/instance/stop-listening): close the stream.