Events Overview

Overview

Pipecat provides an event system that lets you hook into lifecycle changes across the framework — pipeline state transitions, service connections, transport activity, conversation turns, errors, and more. Events are available on most Pipecat objects (anything that inherits from BaseObject). You register handlers using the @event_handler decorator, and Pipecat calls them automatically when things happen.

@worker.event_handler("on_pipeline_started")
async def on_pipeline_started(worker, frame):
    print("Pipeline is running!")

@tts.event_handler("on_connected")
async def on_tts_connected(service):
    print(f"TTS service connected: {service}")

Registering Event Handlers

Use the @event_handler decorator on the object that emits the event:

@object.event_handler("event_name")
async def handler(object, ...):
    # Handle the event
    ...

The first parameter is always the object that emitted the event. Additional parameters depend on the specific event. You can also register handlers without the decorator:

async def my_handler(object, ...):
    ...

object.add_event_handler("event_name", my_handler)

Handlers can be either async or synchronous functions — Pipecat detects which and calls them appropriately.

Multiple Handlers

You can register multiple handlers for the same event. They’re called in the order they were registered. For an asynchronous event each handler runs in its own task, so a handler that awaits doesn’t hold up the next one:

@worker.event_handler("on_pipeline_finished")
async def log_finished(worker, frame):
    print("Pipeline finished (handler 1)")

@worker.event_handler("on_pipeline_finished")
async def cleanup(worker, frame):
    print("Cleaning up (handler 2)")

Synchronous vs Asynchronous Events

Events are either synchronous or asynchronous, depending on how the component registered them internally:

Synchronous events (sync=True) run the handler inline — the caller waits for the handler to complete before continuing. These are used for events that must complete immediately, such as frame processing hooks and error handling. Synchronous event handlers should execute fast to avoid blocking the pipeline.
Asynchronous events (default) run the handler in a background asyncio.Task. The caller continues immediately. These are used for events where you might do I/O, logging, or other work that shouldn’t block the pipeline.

You don’t need to choose — the sync/async behavior is determined by the component, not by your handler. Your handler can be an async def or a regular def regardless.

Events Reference

The table below lists all events available in Pipecat, grouped by component. Click through to the linked documentation for full details including handler signatures and usage examples.

Pipeline

Events on PipelineWorker.

Event	Description
`on_pipeline_started`	Pipeline has started processing
`on_pipeline_finished`	Pipeline reached a terminal state (stopped, ended, or cancelled)
`on_pipeline_error`	An error frame reached the pipeline worker
`on_frame_reached_upstream`	A filtered frame type reached the pipeline source
`on_frame_reached_downstream`	A filtered frame type reached the pipeline sink
`on_idle_timeout`	No activity detected within the idle timeout period

Frame Processor

Events on every FrameProcessor. Since all services and processors, including a transport’s input() and output(), inherit from FrameProcessor, these events are available on any processor in your pipeline. The transport object itself is not a FrameProcessor and doesn’t emit them.

Event	Description
`on_error`	An error occurred in this processor
`on_usable_changed`	The processor’s ability to do its job changed
`on_before_process_frame`	A frame is about to be processed
`on_after_process_frame`	A frame has just been processed
`on_before_push_frame`	A frame is about to be pushed to the next processor
`on_after_push_frame`	A frame has just been pushed to the next processor

Turn Management

Events on context aggregators from LLMContextAggregatorPair.

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 for configured 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)

STT Services

Events on STT service instances. Available on WebSocket-based STT services, though DeepgramSTTService, SarvamSTTService, and SpeechmaticsSTTService don’t emit all three. See Service Events for details.

Event	Description
`on_connected`	WebSocket connection established
`on_disconnected`	WebSocket connection closed
`on_connection_error`	WebSocket connection error occurred

Some STT services have additional events: Deepgram Flux STT:

Event	Description
`on_start_of_turn`	Start of a new turn detected
`on_turn_resumed`	A previously paused turn has resumed
`on_end_of_turn`	End of turn detected
`on_eager_end_of_turn`	Early end-of-turn prediction
`on_update`	Transcript updated

Speechmatics STT:

Event	Description
`on_speakers_result`	Speaker identification result received

Sarvam STT (SarvamSTTService with vad_signals=True in its settings):

Event	Description
`on_speech_started`	Speech detected
`on_speech_stopped`	Speech stopped
`on_utterance_end`	End of utterance detected

TTS Services

Events on TTS service instances. Available on all WebSocket-based TTS services. See Service Events for details.

Event	Description
`on_connected`	WebSocket connection established
`on_disconnected`	WebSocket connection closed
`on_connection_error`	WebSocket connection error occurred
`on_tts_request`	A TTS synthesis request is being sent

LLM Services

Events on LLM service instances. See Service Events for details.

Event	Description
`on_function_calls_started`	LLM has started making function/tool calls
`on_function_calls_cancelled`	In-progress function calls were cancelled
`on_completion_timeout`	LLM response timed out

OpenAI Realtime / Grok Realtime:

Event	Description
`on_conversation_item_created`	A new conversation item was created
`on_conversation_item_updated`	A conversation item was updated

Daily Transport

Events on DailyTransport instances.

Event	Description
`on_joined`	Bot joined the room
`on_left`	Bot left the room
`on_error`	Transport error occurred
`on_call_state_updated`	Call state changed
`on_client_connected`	A participant connected
`on_client_disconnected`	A participant disconnected
`on_first_participant_joined`	First participant joined the room
`on_participant_joined`	A participant joined
`on_participant_left`	A participant left
`on_participant_updated`	A participant’s state was updated
`on_active_speaker_changed`	Active speaker changed
`on_app_message`	App message received
`on_transcription_message`	Transcription message received
`on_transcription_stopped`	Transcription stopped
`on_transcription_error`	Transcription error occurred
`on_recording_started`	Recording started
`on_recording_stopped`	Recording stopped
`on_recording_error`	Recording error occurred
`on_dialin_connected`	Dial-in call connected
`on_dialin_ready`	Dial-in SIP endpoint ready
`on_dialin_stopped`	Dial-in call stopped
`on_dialin_error`	Dial-in error occurred
`on_dialin_warning`	Dial-in warning
`on_dialout_answered`	Dial-out call answered
`on_dialout_connected`	Dial-out call connected
`on_dialout_stopped`	Dial-out call stopped
`on_dialout_error`	Dial-out error occurred
`on_dialout_warning`	Dial-out warning
`on_before_leave`	About to leave the room (sync)

LiveKit Transport

Events on LiveKitTransport instances.

Event	Description
`on_connected`	Connected to the room
`on_disconnected`	Disconnected from the room
`on_participant_connected`	A participant connected
`on_participant_disconnected`	A participant disconnected
`on_first_participant_joined`	First participant joined
`on_audio_track_subscribed`	Audio track subscribed
`on_audio_track_unsubscribed`	Audio track unsubscribed
`on_video_track_subscribed`	Video track subscribed
`on_video_track_unsubscribed`	Video track unsubscribed
`on_data_received`	Data message received
`on_before_disconnect`	About to disconnect (sync)

WebSocket Transports

Events on WebSocket transport instances. WebSocketServerTransport:

Event	Description
`on_client_connected`	Client connected
`on_client_disconnected`	Client disconnected
`on_session_timeout`	Session timed out
`on_websocket_ready`	WebSocket server is ready

FastAPIWebsocketTransport:

Event	Description
`on_client_connected`	Client connected
`on_client_disconnected`	Client disconnected
`on_session_timeout`	Session timed out

WebSocketClientTransport:

Event	Description
`on_connected`	Connected to server
`on_disconnected`	Disconnected from server

Other Transports

SmallWebRTCTransport:

Event	Description
`on_client_connected`	Client connected
`on_client_disconnected`	Client disconnected
`on_app_message`	App message received

HeyGenTransport / TavusTransport:

Event	Description
`on_client_connected`	Client connected
`on_client_disconnected`	Client disconnected

Utilities

ContextSummarizer:

Event	Description
`on_summary_applied`	A summary has been successfully applied to the context.

ServiceSwitcherStrategy (switcher.strategy on a ServiceSwitcher):

Event	Description
`on_service_switched`	Active service was switched

AudioBufferProcessor:

Event	Description
`on_audio_data`	Audio data available
`on_track_audio_data`	Per-track audio data available
`on_user_turn_audio_data`	User turn audio data available
`on_bot_turn_audio_data`	Bot turn audio data available
`on_recording_started`	Recording started (state transitioned to active)
`on_recording_stopped`	Recording stopped (after final buffered audio is emitted)

RTVIProcessor:

Event	Description
`on_bot_started`	Bot started
`on_client_ready`	Client is ready
`on_client_message`	Client message received

Observers

TurnTrackingObserver:

Event	Description
`on_turn_started`	A conversation turn started
`on_turn_ended`	A conversation turn ended

UserBotLatencyObserver:

Event	Description
`on_latency_measured`	Latency measurement available

Extensions

VoicemailDetector:

Event	Description
`on_conversation_detected`	Live conversation detected (not voicemail)
`on_voicemail_detected`	Voicemail detected and the greeting ended

IVRNavigator:

Event	Description
`on_conversation_detected`	Live conversation detected
`on_ivr_status_changed`	IVR navigation status changed

Get Started

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

Events Overview

Overview

Registering Event Handlers

Multiple Handlers

Synchronous vs Asynchronous Events

Events Reference

Pipeline

Frame Processor

Turn Management

STT Services

TTS Services

LLM Services

Daily Transport

LiveKit Transport

WebSocket Transports

Other Transports

Utilities

Observers

Extensions

​Overview

​Registering Event Handlers

​Multiple Handlers

​Synchronous vs Asynchronous Events

​Events Reference

​Pipeline

​Frame Processor

​Turn Management

​STT Services

​TTS Services

​LLM Services

​Daily Transport

​LiveKit Transport

​WebSocket Transports

​Other Transports

​Utilities

​Observers

​Extensions

Overview

Registering Event Handlers

Multiple Handlers

Synchronous vs Asynchronous Events

Events Reference

Pipeline

Frame Processor

Turn Management

STT Services

TTS Services

LLM Services

Daily Transport

LiveKit Transport

WebSocket Transports

Other Transports

Utilities

Observers

Extensions