Saving Conversation Transcripts

Learn how to collect and save conversation transcripts between users and your bot

Overview

Recording transcripts of conversations between users and your bot is useful for debugging, analysis, and creating a record of interactions. Pipecat’s turn events make it easy to collect both user and assistant messages as they occur.

How It Works

Transcripts are collected using turn events on the context aggregators:

1. Capturing what the user says via on_user_turn_stopped
2. Capturing what the assistant says via on_assistant_turn_stopped
3. Each event provides the complete transcript for that turn
4. Allowing you to handle these events with custom logic

Turn events are emitted by the context aggregators (LLMUserAggregator and LLMAssistantAggregator), which are created as part of the LLMContextAggregatorPair.

Basic Implementation

Step 1: Create Context Aggregators

First, create the context aggregator pair and get references to both aggregators:

from pipecat.processors.aggregators.llm_response_universal import (
    LLMContextAggregatorPair,
    UserTurnStoppedMessage,
    AssistantTurnStoppedMessage,
)

# Create context aggregator pair
user_aggregator, assistant_aggregator = LLMContextAggregatorPair(context)

Step 2: Add to Your Pipeline

Include the aggregators in your pipeline:

pipeline = Pipeline(
    [
        transport.input(),
        stt,                              # Speech-to-text
        user_aggregator,
        llm,
        tts,                              # Text-to-speech
        transport.output(),
        assistant_aggregator,
    ]
)

Step 3: Handle Turn Events

Register event handlers to capture transcripts when turns complete:

@user_aggregator.event_handler("on_user_turn_stopped")
async def on_user_turn_stopped(aggregator, strategy, message: UserTurnStoppedMessage):
    print(f"[{message.timestamp}] user: {message.content}")

@assistant_aggregator.event_handler("on_assistant_turn_stopped")
async def on_assistant_turn_stopped(aggregator, message: AssistantTurnStoppedMessage):
    if message.content:
        print(f"[{message.timestamp}] assistant: {message.content}")
    if message.interrupted:
        print(f"[{message.timestamp}] (assistant was interrupted)")

In addition to console logging, you can save transcripts to a database or file for later analysis.

With a realtime (speech-to-speech) service and LLMContextAggregatorPair(context, realtime_service_mode=True), capture the user transcript from on_user_turn_message_added instead of on_user_turn_stopped, whose message.content is None in that mode.

Next Steps

Turn Events Reference

Learn about all available turn events and their parameters.

Transcriptions Reference

See more examples for collecting and processing transcriptions.

Consider implementing transcript recording in your application for debugging during development and preserving important conversations in production. The transcript data can also be useful for analyzing conversation patterns and improving your bot’s responses over time.