Turn Events

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_user_backchannel`	`user_aggregator`	User acknowledged the bot without interrupting
`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_assistant_backchannel`	`assistant_aggregator`	Assistant said a short acknowledgment
`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. With EagerUserTurnStrategies, this event may fire speculatively from a predicted end of turn before the turn has ended. The UserTurnController adds a third parameter, speculation, carrying the turn text the inference was run against when the turn is still open. Handlers registered on LLMUserAggregator or UserTurnProcessor remain unchanged and do not receive this parameter.

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

For UserTurnController, the handler signature is:

@controller.event_handler("on_user_turn_inference_triggered")
async def on_user_turn_inference_triggered(controller, strategy, speculation):
    if speculation:
        print(f"Speculative inference from predicted turn: {speculation.text}")
    else:
        print(f"Confirmed inference triggered by {strategy}")

Parameters:

Parameter	Type	Description
`aggregator`	`LLMUserAggregator`	The user aggregator instance (for handlers on the aggregator)
`controller`	`UserTurnController`	The turn controller instance (for handlers on the controller)
`strategy`	`BaseUserTurnStopStrategy`	The strategy that triggered the inference
`speculation`	`UserTurnSpeculation \| None`	Set when the inference answers a turn that hasn’t ended yet, carrying the turn text (controller only)

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, which LLMContextAggregatorPair turns on with a speech-to-speech service, 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 (with a speech-to-speech service) 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 an active user turn ends on inactivity: the user isn’t speaking and no VAD event or transcript has arrived for user_turn_stop_timeout seconds (default: 5.0).

@user_aggregator.event_handler("on_user_turn_stop_timeout")
async def on_user_turn_stop_timeout(aggregator):
    logger.info("User turn ended by the stop timeout")

A turn that times out often has no transcript at all, for example a cough, background noise, or speech the STT could not recognize. To get the bot to respond after such a turn, use empty_user_turn instead of running the LLM from this event. It’s on by default for turns that interrupted the bot, and idle_prompt extends it to turns while the bot was waiting for the user.

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

on_user_backchannel

Fired when the user says a short acknowledgment while the bot talks, such as “mhm”. It is reported from a UserBackchannelFrame, which is pushed in place of a transcription: the bot keeps talking, and the acknowledgment stays out of the LLM context and the turn events above. It doesn’t fire while the user is muted.

@user_aggregator.event_handler("on_user_backchannel")
async def on_user_backchannel(aggregator, message: UserBackchannelMessage):
    print(f"User backchannel: {message.content}")

Parameters:

Parameter	Type	Description
`aggregator`	`LLMUserAggregator`	The user aggregator instance
`message`	`UserBackchannelMessage`	Contains what the user said and its timestamp

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 the pipeline ends. 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_assistant_backchannel

Fired when the assistant starts saying text of type backchannel, such as a BotBackchannelFrame (“Mm-hmm.”). Backchannels stay out of the LLM context and the assistant turn events.

@assistant_aggregator.event_handler("on_assistant_backchannel")
async def on_assistant_backchannel(aggregator, message: AssistantBackchannelMessage):
    print(f"Assistant backchannel: {message.content}")

Parameters:

Parameter	Type	Description
`aggregator`	`LLMAssistantAggregator`	The assistant aggregator instance
`message`	`AssistantBackchannelMessage`	Contains what the assistant said and its 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

str | None

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

str

ISO 8601 timestamp indicating when the user turn started.

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

str

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

str

ISO 8601 timestamp indicating when the user turn started.

str | None

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

UserBackchannelMessage

Accompanies on_user_backchannel, carrying a short acknowledgment the user said while the bot talks.

from pipecat.processors.aggregators.llm_response_universal import UserBackchannelMessage

str

What the user said.

str

ISO 8601 timestamp indicating when the user said it.

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

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).

bool

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

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

str

The thought/reasoning text from the assistant.

str

ISO 8601 timestamp indicating when the thought started.

AssistantBackchannelMessage

Accompanies on_assistant_backchannel, carrying a short acknowledgment the assistant said while the user talks.

from pipecat.processors.aggregators.llm_response_universal import AssistantBackchannelMessage

str

What the assistant said.

str

ISO 8601 timestamp indicating when the assistant started saying it.

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

Get Started

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

Overview

Events Summary

User Turn Events

on_user_turn_started

on_user_turn_inference_triggered

on_user_turn_stopped

on_user_turn_message_added

on_user_turn_stop_timeout

on_user_turn_idle

on_user_mute_started

on_user_mute_stopped

on_user_backchannel

Assistant Turn Events

on_assistant_turn_started

on_assistant_turn_stopped

on_assistant_thought

on_assistant_backchannel

on_summary_applied

Message Types

UserTurnStoppedMessage

UserTurnMessageAddedMessage

UserBackchannelMessage

AssistantTurnStoppedMessage

AssistantThoughtMessage

AssistantBackchannelMessage

​Overview

​Events Summary

​User Turn Events

​on_user_turn_started

​on_user_turn_inference_triggered

​on_user_turn_stopped

​on_user_turn_message_added

​on_user_turn_stop_timeout

​on_user_turn_idle

​on_user_mute_started

​on_user_mute_stopped

​on_user_backchannel

​Assistant Turn Events

​on_assistant_turn_started

​on_assistant_turn_stopped

​on_assistant_thought

​on_assistant_backchannel

​on_summary_applied

​Message Types

​UserTurnStoppedMessage

​UserTurnMessageAddedMessage

​UserBackchannelMessage

​AssistantTurnStoppedMessage

​AssistantThoughtMessage

​AssistantBackchannelMessage

​Related

Overview

Events Summary

User Turn Events

on_user_turn_started

on_user_turn_inference_triggered

on_user_turn_stopped

on_user_turn_message_added

on_user_turn_stop_timeout

on_user_turn_idle

on_user_mute_started

on_user_mute_stopped

on_user_backchannel

Assistant Turn Events

on_assistant_turn_started

on_assistant_turn_stopped

on_assistant_thought

on_assistant_backchannel

on_summary_applied

Message Types

UserTurnStoppedMessage

UserTurnMessageAddedMessage

UserBackchannelMessage

AssistantTurnStoppedMessage

AssistantThoughtMessage

AssistantBackchannelMessage

Related