Turn Events

Handle user and assistant turn lifecycle events for transcriptions and turn tracking

Overview

Turn events provide hooks into the conversation turn lifecycle, allowing you to know when users and assistants start or stop speaking. These events are emitted by the context aggregators (LLMUserAggregator and LLMAssistantAggregator) and are particularly useful for:

• Collecting transcriptions - Get complete user and assistant transcripts when turns end
• Turn tracking - Monitor conversation flow and timing
• Analytics - Measure turn durations, detect timeouts, and track conversation patterns

Events Summary

Event	Emitter	Description
on_user_turn_started	user_aggregator	User begins speaking
on_user_turn_inference_triggered	user_aggregator	Enough signal to start LLM inference
on_user_turn_stopped	user_aggregator	User finishes speaking (includes transcript)
on_user_turn_message_added	user_aggregator	A user message was written to the LLM context
on_user_turn_stop_timeout	user_aggregator	User turn ended due to timeout
on_user_turn_idle	user_aggregator	User has been idle (not speaking) for timeout
on_user_mute_started	user_aggregator	User input was muted
on_user_mute_stopped	user_aggregator	User input was unmuted
on_assistant_turn_started	assistant_aggregator	Assistant begins responding
on_assistant_turn_stopped	assistant_aggregator	Assistant finishes responding (includes transcript)
on_assistant_thought	assistant_aggregator	Assistant produced a thought (reasoning models)
on_summary_applied	assistant_aggregator	Context summarization was applied

User Turn Events

User turn events are registered on the user_aggregator from an LLMContextAggregatorPair.

on_user_turn_started

Fired when a user turn is detected to have started, based on the configured start strategies.

@user_aggregator.event_handler("on_user_turn_started")
async def on_user_turn_started(aggregator, strategy):
    print(f"User started speaking (detected by {strategy})")

Parameters:

Parameter	Type	Description
aggregator	LLMUserAggregator	The user aggregator instance
strategy	BaseUserTurnStartStrategy	The strategy that triggered the turn start

on_user_turn_inference_triggered

Fired when a stop strategy has enough signal to start LLM inference for the current turn. For the default strategies this fires together with on_user_turn_stopped. When a strategy gates finalization on a separate signal — for example FilterIncompleteUserTurnStrategies, where the public stop event waits for the LLM’s ✓ verdict — this event fires first (and may fire multiple times in one turn) while on_user_turn_stopped is deferred.

@user_aggregator.event_handler("on_user_turn_inference_triggered")
async def on_user_turn_inference_triggered(aggregator, strategy):
    print(f"Inference triggered by {strategy}")

Parameters:

Parameter	Type	Description
aggregator	LLMUserAggregator	The user aggregator instance
strategy	BaseUserTurnStopStrategy	The strategy that triggered the inference

Bind on_user_turn_inference_triggered to react when inference starts, and on_user_turn_stopped to react when the turn is semantically final. With the default strategies the two fire together, so most applications only need on_user_turn_stopped.

on_user_turn_stopped

Fired when a user turn is detected to have ended, based on the configured stop strategies. This event includes the complete user transcript for the turn.

@user_aggregator.event_handler("on_user_turn_stopped")
async def on_user_turn_stopped(aggregator, strategy, message: UserTurnStoppedMessage):
    print(f"User said: {message.content}")
    print(f"Turn started at: {message.timestamp}")
    if message.user_id:
        print(f"User ID: {message.user_id}")

Parameters:

Parameter	Type	Description
aggregator	LLMUserAggregator	The user aggregator instance
strategy	BaseUserTurnStopStrategy	The strategy that triggered the turn stop
message	UserTurnStoppedMessage	Contains the user’s transcript and metadata

In realtime mode (realtime_service_mode=True on LLMContextAggregatorPair), the user message isn’t finalized at turn-stop time, so message.content is None. Subscribe to on_user_turn_message_added instead to get the finalized user text. Behavior in cascade (STT → LLM → TTS) pipelines is unchanged.

on_user_turn_message_added

Fired when a user message is written to the LLM context, carrying the finalized turn text. In cascade pipelines this coincides with on_user_turn_stopped. In realtime mode (realtime_service_mode=True) the write is triggered by the assistant response start rather than the user-turn-end frame, so this event — not on_user_turn_stopped — is the canonical way to subscribe to “context just updated, here’s the user text.”

@user_aggregator.event_handler("on_user_turn_message_added")
async def on_user_turn_message_added(aggregator, message: UserTurnMessageAddedMessage):
    print(f"User said: {message.content}")
    print(f"Turn started at: {message.timestamp}")

Parameters:

Parameter	Type	Description
aggregator	LLMUserAggregator	The user aggregator instance
message	UserTurnMessageAddedMessage	Contains the finalized user text and metadata

on_user_turn_stop_timeout

Fired when a user turn times out without any stop strategy triggering. This is a fallback mechanism that ends the turn after a configurable timeout period (default: 5.0 seconds) when the user has stopped speaking according to VAD but no transcription-based stop has occurred. Commonly, this event is used to retrigger the LLM response after the user has stopped speaking.

@user_aggregator.event_handler("on_user_turn_stop_timeout")
async def on_user_turn_stop_timeout(aggregator):
    message = {
        "role": "developer",
        "content": "Continue.",
    }
    await user_aggregator.queue_frame(LLMMessagesAppendFrame([message], run_llm=True))

Parameters:

Parameter	Type	Description
aggregator	LLMUserAggregator	The user aggregator instance

After on_user_turn_stop_timeout fires, on_user_turn_stopped will also be called with the accumulated transcript.

on_user_turn_idle

Fired when the user has been idle (not speaking) for a configured timeout period. This event is useful for re-engaging users who may have stepped away or need a prompt to continue the conversation. The idle timer starts when the bot finishes speaking and is cancelled when the user or bot starts speaking again.

@user_aggregator.event_handler("on_user_turn_idle")
async def on_user_turn_idle(aggregator):
    # Re-engage the user with a contextual prompt
    message = {
        "role": "developer",
        "content": "The user has been quiet. Politely and briefly ask if they're still there.",
    }
    await aggregator.push_frame(LLMMessagesAppendFrame([message], run_llm=True))

Parameters:

Parameter	Type	Description
aggregator	LLMUserAggregator	The user aggregator instance

The idle timer starts when the bot stops speaking and is cancelled when the user or bot starts speaking. It is suppressed during function calls and active user turns. This event can fire multiple times if the user remains idle.

on_user_mute_started

Fired when user input is muted. See User Input Muting for details on muting.

@user_aggregator.event_handler("on_user_mute_started")
async def on_user_mute_started(aggregator):
    print("User input muted")

Parameters:

Parameter	Type	Description
aggregator	LLMUserAggregator	The user aggregator instance

on_user_mute_stopped

Fired when user input is unmuted.

@user_aggregator.event_handler("on_user_mute_stopped")
async def on_user_mute_stopped(aggregator):
    print("User input unmuted")

Parameters:

Parameter	Type	Description
aggregator	LLMUserAggregator	The user aggregator instance

Assistant Turn Events

Assistant turn events are registered on the assistant_aggregator from an LLMContextAggregatorPair.

on_assistant_turn_started

Fired when the assistant begins generating a response.

@assistant_aggregator.event_handler("on_assistant_turn_started")
async def on_assistant_turn_started(aggregator):
    print("Assistant started responding")

Parameters:

Parameter	Type	Description
aggregator	LLMAssistantAggregator	The assistant aggregator instance

on_assistant_turn_stopped

Fired when the assistant finishes responding or is interrupted. This event includes the complete assistant transcript for the turn.

@assistant_aggregator.event_handler("on_assistant_turn_stopped")
async def on_assistant_turn_stopped(aggregator, message: AssistantTurnStoppedMessage):
    if message.content:
        print(f"Assistant said: {message.content}")
    print(f"Turn started at: {message.timestamp}")
    print(f"Was interrupted: {message.interrupted}")

Parameters:

Parameter	Type	Description
aggregator	LLMAssistantAggregator	The assistant aggregator instance
message	AssistantTurnStoppedMessage	Contains the assistant’s transcript and metadata

This event fires when the LLM response completes, when the user interrupts, or when a user image is appended to context. The event always fires when a turn ends, even if content is empty (e.g., the turn was interrupted before any tokens were generated).

on_assistant_thought

Fired when the assistant produces a thought from a reasoning model (e.g., extended thinking in Claude). This event provides visibility into the model’s reasoning process.

@assistant_aggregator.event_handler("on_assistant_thought")
async def on_assistant_thought(aggregator, message: AssistantThoughtMessage):
    print(f"Assistant thought: {message.content}")

Parameters:

Parameter	Type	Description
aggregator	LLMAssistantAggregator	The assistant aggregator instance
message	AssistantThoughtMessage	Contains the thought content and timestamp

on_summary_applied

Fired when context summarization is successfully applied. This event is useful for monitoring context management and logging compression metrics.

from pipecat.processors.aggregators.llm_context_summarizer import SummaryAppliedEvent

@assistant_aggregator.event_handler("on_summary_applied")
async def on_summary_applied(aggregator, summarizer, event: SummaryAppliedEvent):
    print(
        f"Context summarized: {event.original_message_count} -> "
        f"{event.new_message_count} messages "
        f"({event.summarized_message_count} summarized, "
        f"{event.preserved_message_count} preserved)"
    )

Parameters:

Parameter	Type	Description
aggregator	LLMAssistantAggregator	The assistant aggregator instance
summarizer	LLMContextSummarizer	The summarizer that applied the summary
event	SummaryAppliedEvent	Contains summarization metrics and metadata

This event requires enable_auto_context_summarization=True in the LLMAssistantAggregatorParams or manual triggering via LLMSummarizeContextFrame. See Context Summarization for details.

Message Types

UserTurnStoppedMessage

Contains the user’s complete transcript when their turn ends.

from pipecat.processors.aggregators.llm_response_universal import UserTurnStoppedMessage

content · str | None

The complete transcribed text from the user’s turn. None in realtime mode (realtime_service_mode=True), where the user message isn’t finalized at turn-stop time — subscribe to on_user_turn_message_added for the finalized text instead.

timestamp · str

ISO 8601 timestamp indicating when the user turn started.

user_id · str | None

Optional identifier for the user, if available from the transport.

UserTurnMessageAddedMessage

Accompanies on_user_turn_message_added, carrying the finalized user text written to the LLM context.

from pipecat.processors.aggregators.llm_response_universal import UserTurnMessageAddedMessage

content · str

The aggregated, finalized user transcript for the turn. Always populated.

timestamp · str

ISO 8601 timestamp indicating when the user turn started.

user_id · str | None

Optional identifier for the user, if available from the transport.

AssistantTurnStoppedMessage

Contains the assistant’s complete transcript when their turn ends.

from pipecat.processors.aggregators.llm_response_universal import AssistantTurnStoppedMessage

content · str

The complete text content from the assistant’s turn. May be empty if the LLM returned zero tokens (e.g., turn was interrupted before any tokens were received or pushed).

interrupted · bool

Whether the assistant turn was interrupted. True if the turn ended due to user interruption or cancellation, False if it completed normally.

timestamp · str

ISO 8601 timestamp indicating when the assistant turn started.

AssistantThoughtMessage

Contains an assistant’s thought content from reasoning models.

from pipecat.processors.aggregators.llm_response_universal import AssistantThoughtMessage

content · str

The thought/reasoning text from the assistant.

timestamp · str

ISO 8601 timestamp indicating when the thought started.

Related

• Transcriptions - Collect conversation transcripts using turn events
• User Turn Strategies - Configure turn detection behavior
• Turn Tracking Observer - Track complete turn cycles with timing