instance.send_message, which also lets Synap push context for the next turn back to your process.
Records a single message turn against a conversation. Synap uses recorded messages to build conversation-scoped context (facts, preferences, episodes) and as input for compaction. Both user and assistant turns should be recorded so the system has the full transcript.
Parameters
Stable identifier for the conversation. All messages sharing the same
conversation_id form one transcript. Must be a valid UUID: generate one with str(uuid.uuid4()) and reuse it for every turn in the conversation. This call is what registers a conversation.External user identifier (your application’s user ID). Required so the message is scoped to the right end user.
External customer/tenant identifier.Required on B2B. Not accepted on B2C: passing it is rejected with HTTP 400. See B2C vs B2B. Required for B2B instances (multi-tenant), where each message must be scoped to a tenant. Must be omitted on B2C instances (
user_context_isolation: "equals_customer"), where the field is not accepted at all and a message carrying it is rejected with HTTP 400.Optional session identifier. Auto-generated if not provided. A value that is not a UUID comes back as its UUID5 form.
The level of your scope ladder this conversation belongs to, for example
{"customer": "acme", "team": "payments", "user": "dana"}. Usually needed once per user: once a user has been placed at a level, customer_id and user_id alone reach their whole chain.Sending it once per conversation is enough: Synap fills in a missing path and never overwrites one, so sending it on every turn does no harm. Python 0.4.11 and later. JavaScript and TypeScript 0.5.1 and later, as scope_path (or scopePath).The model your agent runs on, for example
"gpt-4o". Synap uses its context window to decide when to compact. A compaction starts when the conversation since the last compaction, including that compaction’s own text, reaches about 11.7% of the window (15K tokens on a 128K model), or after 30 new turns once they add up to at least 2,000 tokens, whichever comes first. A name is enough for common models. Overrides SDKConfig.agent_model for this turn. With neither a model nor a window, Synap assumes a 128K window. Python 0.5.11 and later. JavaScript and TypeScript 0.5.9 and later.Your agent model’s context window, in tokens. Only needed for a model Synap does not know by name. Overrides
SDKConfig.agent_context_window for this turn. It takes precedence over the model name. Python 0.5.11 and later. JavaScript and TypeScript 0.5.9 and later, as context_window (or contextWindow).Returns
A dict describing the recorded message.Example
Raises
InvalidInputError, before any request:roleis not"user"or"assistant"(Python 0.5.19 and JavaScript 0.5.17 and later; earlier Python raisedValueError).InvalidInputError, before any request: an emptyconversation_idoruser_id, or noroleorcontent(Python 0.5.19 and later).InvalidConversationIdError, a subclass ofInvalidInputError:conversation_idis not a valid UUID.InvalidInputError: a B2B message withoutcustomer_id(the server refuses it with 400).CustomerIdNotAcceptedError, a subclass ofInvalidInputError: acustomer_idon a B2C instance (Python 0.5.12 and JavaScript 0.5.11 and later).AuthenticationErrorwith the message “SDK not initialized”: when called beforeawait sdk.initialize()(Python). JavaScript resolves the client’s identity on the first call instead.AuthenticationError: when the API key is invalid or revoked. A missing key fails earlier, when the client is created (JavaScript) or initialized (Python).NetworkTimeoutError: the SDK could not reach Synap (a timeout, or a refused or dropped connection) after its retries.ConnectionErroris the same class in both SDKs.