Skip to main content
gRPC stream Sent over the stream that instance.listen() opens, so it needs a long-running process. The REST way to report a turn is conversation.record_message.
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 Synap promotes those raw turns into the same ingestion pipeline memories.create() uses: after every 5 new turns, after 5 minutes without a new message, and when the session ends. Separately, a compaction starts when the conversation since the last compaction reaches about 11.7% of your model’s context window (15K tokens on a 128K model), after 30 new turns, or after 5 minutes without a new message, whichever comes first. The 5 minutes is a default; an instance can change it. Promotion is deferred, not conditional: every conversation gets there.For an agent reporting conversation turns this is sufficient on its own; see Agent Integration. 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

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. The anticipation agent reads them in its working thread, which keeps the 80 most recent events, expires 30 minutes after the last event and is deleted when the session ends. The debugging records keep only the shape of each step, for 30 days. See Traces and tool calls. Persisted turns feed both layers of context. They are the conversation that context compaction condenses as it grows, and Synap also turns them into long-term memory in the background.
A user_message or assistant_message needs user_id, and on a B2B instance customer_id too. On a B2C instance send user_id only: a customer_id there is refused before sending with CustomerIdNotAcceptedError. An event missing a required id is refused on the stream (except that a B2B event with customer_id and no user_id is not refused, and is not recorded either). send_message has already returned by then, so your code gets no exception and the turn is not recorded; the SDK logs the server’s reason (Python 0.5.20 and JavaScript 0.5.18 and later).
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
The conversation this event belongs to. Use the same id as for this conversation’s other calls. Neither SDK checks its format here.
string
External user identifier. Required for user_message and assistant_message events.
string
External customer identifier. Required on B2B. Not accepted on B2C: passing it raises CustomerIdNotAcceptedError before anything is sent. 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 InvalidInputError naming the real ones, rather than travelling to the server to be ignored there (Python 0.5.20 and JavaScript 0.5.18 and later).
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.
string
The model your agent runs on, for example "gpt-4o", as on conversation.record_message. Synap uses its context window to decide when to compact this conversation. Overrides SDKConfig.agent_model for this event. Python 0.5.11 and later. JavaScript and TypeScript 0.5.9 and later.
integer
Your agent model’s context window, in tokens. Only needed for a model Synap does not know by name. It takes precedence over the model name. Overrides SDKConfig.agent_context_window for this event. Python 0.5.11 and later. JavaScript and TypeScript 0.5.9 and later, as context_window (or contextWindow).
dict[str, str]
The level of your scope ladder this conversation belongs to, for example {"customer": "acme", "team": "payments", "user": "dana"}. Sent with the event; Synap keeps the first path it sees for a conversation and never overwrites it. Usually needed once per user: once a user has been placed at a level, customer_id and user_id alone reach their whole chain. Python 0.5.20 and later. JavaScript and TypeScript 0.5.18 and later, as scope_path (or scopePath).

Returns

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

Example

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.
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.
  • InvalidInputError: an unknown event_type, or no content (Python 0.5.20 and JavaScript 0.5.18 and later).
  • CustomerIdNotAcceptedError, a subclass of InvalidInputError: a customer_id on a B2C instance (Python 0.5.12 and JavaScript 0.5.18 and later).
See Error Codes for the full SDK exception hierarchy.

See also