conversation.ingest_transcript

await sdk.conversation.ingest_transcript(
    conversation_id: str,
    user_id: str,
    transcript: Union[str, List[TranscriptTurn]],
    customer_id: Optional[str] = None,
    conversation_type: Optional[str] = None,
    analysis: Optional[Dict[str, Any]] = None,
    metadata: Optional[Dict[str, Any]] = None,
    started_at: Optional[datetime] = None,
    ended_at: Optional[datetime] = None,
) -> TranscriptIngestResponse

Push a whole conversation transcript in a single call at the end of a session. Synap records the transcript, enqueues background extraction, and fires a summary compaction, then returns immediately — nothing here sits on a hot path. This is the call-end half of the async integration pattern; the call-start half is sdk.fetch(context_mode="conversation-summary"). Poll completion with sdk.memories.status(ingestion_id) or sdk.memories.wait_for_completion(ingestion_id).

Parameters

str

required

The client’s own call/conversation id. Any string is accepted — it is not validated as a UUID (unlike record_message). The server coerces it and echoes the original back as external_conversation_id. Reuse a stable id per call (e.g. your telephony provider’s call id, or "{phone}:{call_start_iso}").

str

required

Caller identity — e.g. an E.164 phone number for a voice call.

str | List[TranscriptTurn]

required

The conversation content. A plain string is split by the server on the turn grammar; a List[TranscriptTurn] is preferred because it preserves per-turn timestamps and speaker labels.

from maximem_synap import TranscriptTurn

TranscriptTurn(
    role: Literal["user", "assistant"],
    content: str,
    timestamp: Optional[datetime] = None,   # turn time; server time if absent
    speaker: Optional[str] = None,          # display label, e.g. "Agent Priya"
    metadata: Optional[Dict[str, Any]] = None,
)

str

Required on B2B (strict-isolation) instances; omit on B2C (equals_customer), where the server collapses it from user_id.

str

Free-form label, ≤ 64 chars (e.g. "voice", "text", "video").

Dict[str, Any]

Your own per-call analysis JSON (≤ 64 KB). Stored verbatim (returned by conversation-summary fetches and shown in the dashboard) and fed to extraction as high-confidence hints.

Dict[str, Any]

Open-ended metadata (≤ 64 KB).

datetime

Conversation start time.

datetime

Conversation end time.

Returns

A TranscriptIngestResponse.

str

The server-coerced (UUID-form) conversation id.

str

The original id you supplied, echoed verbatim.

UUID

Handle for sdk.memories.status() / wait_for_completion(). Always set on success — never null, even on the duplicate branch.

str

"queued" (recorded + enqueued) or "duplicate" (an identical transcript was already pushed).

int

Number of turns persisted.

str

"in_progress" (compaction enqueued), "already_compacted" (duplicate where the summary already exists), or "skipped" (no turns to summarize).

datetime

When the push was accepted.

Every response also exposes .raw — the untyped response dict, for forward compatibility with fields a newer server may add.

Idempotency

The push is idempotent on (conversation_id, transcript):

Same transcript, same id → status="duplicate" with the original ingestion_id. Retries are free.
Different transcript, same id → TranscriptConflictError (HTTP 409). A call’s transcript is immutable; mint a new conversation_id for a new call.

Example

from datetime import datetime, timezone
from maximem_synap import MaximemSynapSDK, TranscriptTurn

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

resp = await sdk.conversation.ingest_transcript(
    conversation_id="call_01H8XZ",                 # any client string
    user_id="+919812345678",                       # E.164 caller id
    conversation_type="voice",
    transcript=[
        TranscriptTurn(role="assistant", content="Hi, is this a good time?", speaker="Agent Priya"),
        TranscriptTurn(role="user", content="Yes — I'm looking for a 3 BHK in Baner.", speaker="Caller"),
    ],
    analysis={"disposition": "interested", "sentiment": "positive"},
    started_at=datetime(2026, 7, 15, 10, 0, tzinfo=timezone.utc),
    ended_at=datetime(2026, 7, 15, 10, 6, tzinfo=timezone.utc),
)

# Optionally wait for extraction to finish before the next call.
await sdk.memories.wait_for_completion(resp.ingestion_id)

Raises

InvalidInputError: empty transcript, oversized analysis/metadata, or a B2B push missing customer_id (HTTP 400/422).
TranscriptConflictError: a different transcript was already ingested under this conversation_id (HTTP 409). Subclass of ConflictError.
RateLimitError / InsufficientCreditsError: as applicable.
AuthenticationError: when the API key is missing or invalid.

Introduction

Lifecycle

Memory ingestion

Memory management

Conversation

Conversation context

Scoped context

User profile

Real-time streaming

Cache management

Credits & billing

Reference

Limits & Pricing

conversation.ingest_transcript

Parameters

Returns

Idempotency

Example

Raises

See also

​Parameters

​Returns

​Idempotency

​Example

​Raises

​See also

Parameters

Returns

Idempotency

Example

Raises

See also