Skip to main content
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; auto-resolved on B2C. See B2C vs B2B. Required for B2B instances (multi-tenant), where each message must be scoped to a tenant. Optional for B2C instances, where the customer is auto-resolved from the user. If omitted, Synap derives it automatically. Passing it on a B2C instance is harmless but unnecessary.
str
Optional session identifier. Auto-generated if not provided.
Dict[str, Any]
Free-form metadata to attach to the message (e.g., model name, latency, custom tags).

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.

Example

Raises

  • InvalidInputError: when role is not "user" or "assistant", or when required identifiers are missing.
  • AuthenticationError: when the API key is missing or invalid.
  • NetworkError: when the SDK cannot reach Synap.

See also