Transcripts

TranscriptEntry shape, streaming semantics, and how to consume transcripts from the session.

Transcripts stream in real time from both the user (via STT) and the assistant (via LLM / TTS). The SDK delivers them through one event — 'transcript' — and you branch on the entry’s role.

The TranscriptEntry type

A discriminated union on role:

type TranscriptEntry =
  | { id: string; role: 'user';      text: string; isComplete: boolean }
  | { id: string; role: 'assistant'; text: string; isComplete: boolean }
  | { id: string; role: 'tool_call'; functionName: string; isComplete: boolean };

Streaming semantics

The same id is emitted multiple times as partial text arrives. Use it as a stable key (React / DOM) so partials update in place instead of creating new bubbles.

Example trace — user says “Hey hi, how are you?“:

{ id: 'abc', role: 'user', text: 'hey',              isComplete: false }
{ id: 'abc', role: 'user', text: 'hey hi',           isComplete: false }
{ id: 'abc', role: 'user', text: 'hey hi how',       isComplete: false }
{ id: 'abc', role: 'user', text: 'hey hi how are',   isComplete: false }
{ id: 'abc', role: 'user', text: 'hey hi how are you', isComplete: true }

Same pattern applies to assistant transcripts (LLM tokens streamed in real time).

Consuming transcripts — the main way

Subscribe to the 'transcript' event and branch on role. This is the recommended pattern for all transcript handling:

session.on('transcript', (entry) => {
  switch (entry.role) {
    case 'user':
      renderUserBubble(entry.id, entry.text, entry.isComplete);
      break;
    case 'assistant':
      renderAssistantBubble(entry.id, entry.text, entry.isComplete);
      break;
    case 'tool_call':
      renderToolBadge(entry.id, entry.functionName, entry.isComplete);
      break;
  }
});

TypeScript narrows entry inside each case — no casts needed, full type safety on text vs functionName.

Common patterns

Live chat UI

const bubbles = new Map<string, HTMLElement>();

session.on('transcript', (entry) => {
  if (entry.role === 'tool_call') return; // handle tool calls separately

  let bubble = bubbles.get(entry.id);
  if (!bubble) {
    bubble = createBubble(entry.role);
    bubbles.set(entry.id, bubble);
    container.append(bubble);
  }
  bubble.textContent = entry.text;
  bubble.classList.toggle('partial', !entry.isComplete);
});

Commit-on-final (command parsing)

session.on('transcript', (entry) => {
  if (entry.role !== 'user' || !entry.isComplete) return;
  const text = entry.text.toLowerCase();
  if (text.includes('transfer')) transferCall();
  if (text.includes('hang up')) session.close();
});

Tool-call indicator

session.on('transcript', (entry) => {
  if (entry.role !== 'tool_call') return;
  if (entry.isComplete) {
    toast(`Finished: ${entry.functionName}`);
  } else {
    toast(`Calling: ${entry.functionName}…`);
  }
});

Accessing full history

getState().transcripts returns a cloned snapshot of all entries so far. Useful for exporting transcripts, debugging, or re-rendering after hot-reload:

const { transcripts } = session.getState();
exportAsJson(transcripts);

The array is a clone — mutating it won’t affect session state.

Transcript vs speaking: pick the right one

Two closely-related but distinct streams for “what the assistant said”:

Rule of thumb:

• Want what the model said → onAssistantTranscript
• Want what the user is hearing right now → onAssistantSpeaking
• In stream mode → onAssistantSpeaking is your primary text stream (transcript doesn’t fire without an LLM)

The helper for onAssistantSpeaking lives in Speaking. The transcript helpers are below.

Single-role helpers

type Unsubscribe = () => void;

session.onUserTranscript(
  (entry: UserTranscript) => void
): Unsubscribe;

session.onAssistantTranscript(
  (entry: AssistantTranscript) => void
): Unsubscribe;

session.onToolCall(
  (entry: ToolCallTranscript) => void
): Unsubscribe;

Example:

const off = session.onUserTranscript((e) => {
  if (e.isComplete) handle(e.text);
});

// later
off();