Service Events

Handle connection lifecycle and service-specific events for STT, TTS, and LLM services

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

All WebSocket-based STT and TTS services share a common set of connection events. These are emitted by the base STTService and TTSService classes, so they work the same way regardless of which provider you use.

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) when connection errors occur. The on_connection_error event fires for each failed attempt.

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_completion_timeout

Fired when an LLM completion request times out. This can happen with slow models or large context windows. The timeout is also pushed as an error frame.

@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

Related

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