Skip to main content
REST One HTTPS request per turn. Works in any Python or Node 20+ process, including serverless functions. The streaming way to report the same turn is 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

str
required
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.
str
required
Message role. Must be "user" or "assistant".
str
required
The message text.
str
required
External user identifier (your application’s user ID). Required so the message is scoped to the right end user.
str
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.
str
Optional session identifier. Auto-generated if not provided. A value that is not a UUID comes back as its UUID5 form.
Dict[str, Any]
Free-form metadata to attach to the message (e.g., model name, latency, custom tags).
Dict[str, str]
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).
str
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.
int
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.
str
Server-assigned message identifier.
str
Echo of the supplied conversation id.
str
Session id (the one you passed, or the auto-generated one).
str
ISO-8601 timestamp of when the message was accepted.
int
Messages recorded in this conversation so far, including this one.

Example

Raises

  • InvalidInputError, before any request: role is not "user" or "assistant" (Python 0.5.19 and JavaScript 0.5.17 and later; earlier Python raised ValueError).
  • InvalidInputError, before any request: an empty conversation_id or user_id, or no role or content (Python 0.5.19 and later).
  • InvalidConversationIdError, a subclass of InvalidInputError: conversation_id is not a valid UUID.
  • InvalidInputError: a B2B message without customer_id (the server refuses it with 400).
  • CustomerIdNotAcceptedError, a subclass of InvalidInputError: a customer_id on a B2C instance (Python 0.5.12 and JavaScript 0.5.11 and later).
  • AuthenticationError with the message “SDK not initialized”: when called before await 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. ConnectionError is the same class in both SDKs.

See also