Service Events

Overview

Pipecat services emit events for connection lifecycle management and service-specific activity. These events let you monitor WebSocket connections, handle errors, and react to service behavior.

Connection Events

WebSocket-based STT and TTS services share a common set of connection events. Not every STT service emits all three: DeepgramSTTService emits only on_connection_error, SpeechmaticsSTTService doesn’t emit on_connected, and SarvamSTTService emits none.

Events Summary

Event	Available On	Description
`on_connected`	STT, TTS	WebSocket connection established
`on_disconnected`	STT, TTS	WebSocket connection closed
`on_connection_error`	STT, TTS	WebSocket connection error occurred

on_connected

Fired when the service’s WebSocket connection is established. This is useful for logging, monitoring connection health, or triggering actions that depend on the service being ready.

@stt.event_handler("on_connected")
async def on_stt_connected(service):
    print(f"STT connected: {service.name}")

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

Parameters:

Parameter	Type	Description
`service`	`STTService` / `TTSService`	The service instance

Not all STT and TTS services use WebSocket connections. HTTP-based services (e.g., Azure TTS, Google TTS) do not emit connection events.

on_disconnected

Fired when the service’s WebSocket connection is closed, whether due to normal shutdown or an error.

@stt.event_handler("on_disconnected")
async def on_stt_disconnected(service):
    print(f"STT disconnected: {service.name}")

Parameters:

Parameter	Type	Description
`service`	`STTService` / `TTSService`	The service instance

on_connection_error

Fired when a WebSocket connection error occurs. The error is also pushed as an ErrorFrame through the pipeline.

@tts.event_handler("on_connection_error")
async def on_tts_connection_error(service, error):
    print(f"TTS connection error: {error}")

Parameters:

Parameter	Type	Description
`service`	`STTService` / `TTSService`	The service instance
`error`	`str`	The error message

WebSocket-based services automatically reconnect with exponential backoff (3 retries, 4-10s waits by default) when connection errors occur. The on_connection_error event fires for each failed attempt. Configure the wait times via reconnect_backoff_min_wait and reconnect_backoff_max_wait constructor parameters.Reconnection stops once the service can no longer do its job — credentials the provider has already rejected aren’t worth retrying, and exhausting the retries leaves the service unusable too. See Error Handling.

TTS Events

on_tts_request

Fired just before a TTS synthesis request is sent to the service. This is useful for logging, monitoring, or modifying behavior based on what text is being synthesized.

@tts.event_handler("on_tts_request")
async def on_tts_request(service, context_id, text):
    print(f"TTS synthesizing ({context_id}): {text}")

Parameters:

Parameter	Type	Description
`service`	`TTSService`	The TTS service instance
`context_id`	`str`	The context ID for this TTS request
`text`	`str`	The prepared text about to be synthesized

LLM Events

on_function_calls_started

Fired when the LLM starts making function (tool) calls. This event is emitted before the function calls are executed.

@llm.event_handler("on_function_calls_started")
async def on_function_calls_started(service, function_calls):
    for call in function_calls:
        print(f"LLM calling function: {call.function_name}")

Parameters:

Parameter	Type	Description
`service`	`LLMService`	The LLM service instance
`function_calls`	`list`	List of function call objects from the LLM

on_function_calls_cancelled

Fired after one or more in-progress function calls are cancelled: by an interruption (for calls registered with cancel_on_interruption=True), a function call timeout, the model cancelling a cancellable_by_llm=True call, or cancel_function_calls().

@llm.event_handler("on_function_calls_cancelled")
async def on_function_calls_cancelled(service, function_calls):
    for call in function_calls:
        print(f"Cancelled function: {call.function_name}")

Parameters:

Parameter	Type	Description
`service`	`LLMService`	The LLM service instance
`function_calls`	`list`	The function calls that were cancelled

on_completion_timeout

Fired when an LLM completion request times out. This can happen with slow models or large context windows. The OpenAI-based and Google services also push the timeout as an error frame; AnthropicLLMService and AWSBedrockLLMService report it only through this event.

@llm.event_handler("on_completion_timeout")
async def on_completion_timeout(service):
    print("LLM completion timed out — consider increasing timeout or reducing context")

Parameters:

Parameter	Type	Description
`service`	`LLMService`	The LLM service instance

Events Overview - Overview of all events in Pipecat
FrameProcessor Events - Error handling and frame monitoring events
Turn Events - User and assistant turn lifecycle events

Get Started

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

Overview

Connection Events

Events Summary

on_connected

on_disconnected

on_connection_error

TTS Events

on_tts_request

LLM Events

on_function_calls_started

on_function_calls_cancelled

on_completion_timeout

​Overview

​Connection Events

​Events Summary

​on_connected

​on_disconnected

​on_connection_error

​TTS Events

​on_tts_request

​LLM Events

​on_function_calls_started

​on_function_calls_cancelled

​on_completion_timeout

​Related

Overview

Connection Events

Events Summary

on_connected

on_disconnected

on_connection_error

TTS Events

on_tts_request

LLM Events

on_function_calls_started

on_function_calls_cancelled

on_completion_timeout

Related