instance.send_message

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,
)

await sdk.instance.send_message(options: SendMessageOptions)

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.

send_message() does not ingest the turn when you call it, but the turn is not discarded either. Conversation events are persisted to conversation history, and when the conversation compacts (by default at 3,000 tokens or 10 messages), those raw turns are promoted into the same ingestion pipeline memories.create() uses.For an agent reporting conversation turns this is sufficient on its own; see Agent Integration. It is deferred, not conditional: compaction fires at 3,000 tokens, 10 messages, or 5 minutes of inactivity, so every conversation gets there. Call memories.create only for content that is not a conversation turn, or that must be retrievable sooner. Never for the same text you streamed, which would extract it twice.

What the platform does with the event

`event_type`	When to send it	What the platform does
`user_message`	The user’s turn arrives, before you retrieve	Persists the turn to conversation history; signals a new turn
`assistant_message`	After your agent produces its reply	Persists the turn; triggers anticipation for the next turn
`tool_call`	Your agent decides to call a tool	Observed mid-turn. Prefer `record_tool_call`, which sets the role for you
`tool_result`	A tool returned	Observed mid-turn. Prefer `record_tool_result`
`agent_thinking`	Your agent reasons between the turns	Observed mid-turn. Prefer `record_thinking`
`context_request`	Your agent plans a retrieval	Supplies `search_queries` / `context_types` as direct anticipation hints
`context_fetch`	Sent for you after each `fetch()`	Records what was retrieved, so anticipation can score itself
`session_start` / `session_end`	Sent for you	Opens the session that warms the first turn; closes it and finalises the turn

Only user_message and assistant_message become conversation history. Tool calls, tool results and reasoning are short-lived hints for anticipation: never compacted, never extracted into long-term memory, and held for at most seven days in the debugging trail. Persisted turns feed both layers of context. They advance the conversation toward automatic context compaction once it crosses the configured token or message threshold, and that same compaction promotes the raw turns into long-term memory.

A user_message or assistant_message is persisted only when both user_id and customer_id are present. If either is missing, the platform skips persistence and logs server-side, and your application receives no error and no exception. On a B2C instance send user_id only: customer_id is not accepted there, and an event without one is persisted normally.

Emit assistant_message after your agent produces its reply, not before. Anticipation runs between turns, so this event is what warms the cache for the next turn.

Parameters

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.

string

default:"user"

Either "user" or "assistant".

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.

string

External user identifier. Omit for customer- or client-scope events.

string

External customer identifier. Required on B2B. Not accepted on B2C: passing it is rejected with HTTP 400. See B2C vs B2B.

string

External session identifier.

string

default:"user_message"

The kind of event being reported, from the table above. An unrecognised value is refused with an error naming the real ones, rather than travelling to the server to be ignored there.

dict[str, str]

Additional string key-value metadata attached to the event.

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.

any

For tool_result events: what the tool returned. JSON-encodable, or a plain string.

string

Ties a tool_result to the tool_call that asked for it.

dict

For tool_call events: a JSON-encodable arguments dict for the tool invocation.

list[string]

For tool_call or context_request events: the retrieval queries the agent plans to run. Used as direct anticipation hints.

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"],
)

import { randomUUID } from 'node:crypto';

// conversation_id must be a valid UUID; reuse the one for the active conversation
let conversation_id = randomUUID();

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'],
});

import { randomUUID } from 'node:crypto';

// conversation_id must be a valid UUID; reuse the one for the active conversation
let conversation_id = randomUUID();

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'],
});

A whole turn, in order

The five kinds of event a turn produces, with the typed methods where they exist. The typed methods set event_type and role together, which is the pair that has to agree.

# 1. the user speaks
await sdk.instance.send_message(
    content="where is my order",
    role="user",
    event_type="user_message",
    conversation_id=conversation_id,
    user_id="user_789",
    customer_id="cust_456",
)

# 2. your agent thinks
await sdk.instance.record_thinking(
    content="Check the order status before quoting the refund policy.",
    conversation_id=conversation_id,
    user_id="user_789",
    customer_id="cust_456",
    step_index=1,
    thought_type="plan",
)

# 3. it calls a tool
await sdk.instance.record_tool_call(
    "lookup_order",
    {"order_id": "A-1042"},
    tool_call_id="call_1",
    conversation_id=conversation_id,
    user_id="user_789",
    customer_id="cust_456",
)

# 4. the tool answers
await sdk.instance.record_tool_result(
    {"status": "shipped", "eta": "2026-10-02"},
    tool_name="lookup_order",
    tool_call_id="call_1",
    conversation_id=conversation_id,
    user_id="user_789",
    customer_id="cust_456",
)

# 5. your agent replies — this is the anticipation moment
await sdk.instance.send_message(
    content="Your order shipped and arrives on 2 October.",
    role="assistant",
    event_type="assistant_message",
    conversation_id=conversation_id,
    user_id="user_789",
    customer_id="cust_456",
)

await sdk.instance.send_message({
  content: 'where is my order', role: 'user', event_type: 'user_message',
  conversation_id: conversationId, user_id: 'user_789', customer_id: 'cust_456',
});

await sdk.instance.record_thinking({
  content: 'Check the order status before quoting the refund policy.',
  conversation_id: conversationId, user_id: 'user_789', customer_id: 'cust_456',
  step_index: 1, thought_type: 'plan',
});

await sdk.instance.record_tool_call({
  tool_name: 'lookup_order', tool_args: { order_id: 'A-1042' }, tool_call_id: 'call_1',
  conversation_id: conversationId, user_id: 'user_789', customer_id: 'cust_456',
});

await sdk.instance.record_tool_result({
  result: { status: 'shipped', eta: '2026-10-02' },
  tool_name: 'lookup_order', tool_call_id: 'call_1',
  conversation_id: conversationId, user_id: 'user_789', customer_id: 'cust_456',
});

await sdk.instance.send_message({
  content: 'Your order shipped and arrives on 2 October.',
  role: 'assistant', event_type: 'assistant_message',
  conversation_id: conversationId, user_id: 'user_789', customer_id: 'cust_456',
});

No session call anywhere in that turn. The SDK opens one on the first event and closes it when you stop listening. Call end_session yourself only when a conversation ends and your process keeps running.

Raises

ListeningNotActiveError: when instance.listen has not been called or the stream has been closed.

See Error Codes for the full SDK exception hierarchy.

Introduction

Lifecycle

Memory ingestion

Memory management

Conversation

Conversation context

Scoped context

User profile

Real-time streaming

Cache management

Credits & billing

Reference

Limits & Pricing

What the platform does with the event

Parameters

Returns

Example

A whole turn, in order

Raises

See also

​What the platform does with the event

​Parameters

​Returns

​Example

​A whole turn, in order

​Raises

​See also

What the platform does with the event

Parameters

Returns

Example

A whole turn, in order

Raises

See also