> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

```python theme={null}
@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 |

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

### on\_disconnected

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

```python theme={null}
@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.

```python theme={null}
@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    |

<Note>
  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.
</Note>

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

```python theme={null}
@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.

```python theme={null}
@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.

```python theme={null}
@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](/api-reference/server/events/overview) - Overview of all events in Pipecat
* [FrameProcessor Events](/api-reference/server/events/frame-processor-events) - Error handling and frame monitoring events
* [Turn Events](/api-reference/server/utilities/turn-management/turn-events) - User and assistant turn lifecycle events