Skip to main content
await sdk.conversation.record_message(
    conversation_id: str,
    role: str,
    content: str,
    user_id: str,
    customer_id: Optional[str] = None,
    session_id: Optional[str] = None,
    metadata: Optional[Dict[str, Any]] = None,
) -> Dict[str, Any]
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

​
conversation_id
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.
​
role
str
required
Message role. Must be "user" or "assistant".
​
content
str
required
The message text.
​
user_id
str
required
External user identifier (your application’s user ID). Required so the message is scoped to the right end user.
​
customer_id
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.
​
session_id
str
Optional session identifier. Auto-generated if not provided.
​
metadata
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.
​
message_id
str
Server-assigned message identifier.
​
conversation_id
str
Echo of the supplied conversation id.
​
session_id
str
Session id (the one you passed, or the auto-generated one).
​
recorded_at
str
ISO-8601 timestamp of when the message was accepted.

​
Example

import uuid
from maximem_synap import MaximemSynapSDK

sdk = MaximemSynapSDK(api_key="synap_your_key_here")
await sdk.initialize()

# conversation_id must be a valid UUID; generate once and reuse for the whole transcript
conversation_id = str(uuid.uuid4())

await sdk.conversation.record_message(
    conversation_id=conversation_id,
    role="user",
    content="I prefer dark mode and concise answers.",
    user_id="user_alice",
    customer_id="customer_acme",  # required for B2B; omit on B2C (auto-resolved)
    metadata={"channel": "web"},
)

await sdk.conversation.record_message(
    conversation_id=conversation_id,
    role="assistant",
    content="Got it — I'll keep answers short and assume dark mode.",
    user_id="user_alice",
    customer_id="customer_acme",
)

​
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