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

# ThunderPhone

> Speech-to-speech service that runs a ThunderPhone voice agent (speech recognition, LLM, voice, turn-taking, 47 languages and tools) inside a Pipecat pipeline

export const CommunityMaintained = ({maintainer, maintainerUrl, repo}) => <Note>
    <strong>Community-maintained integration.</strong> This service is built and
    maintained by{" "}
    <a href={maintainerUrl} target="_blank" rel="noreferrer">
      {maintainer}
    </a>
    . Pipecat does not test or officially support it. Please report issues and
    request changes on the{" "}
    <a href={repo} target="_blank" rel="noreferrer">
      source repository
    </a>
    . Learn more about{" "}
    <a href="/api-reference/server/services/community-integrations">
      community integrations
    </a>
    .
  </Note>;

<CommunityMaintained maintainer="ThunderPhone" maintainerUrl="https://github.com/autophonix" repo="https://github.com/autophonix/pipecat-thunderphone" />

## Overview

`ThunderPhoneRealtimeLLMService` connects a Pipecat pipeline to
[ThunderPhone](https://thunderphone.com), a platform for AI phone agents. It
is a speech-to-speech service: Pipecat sends caller audio, ThunderPhone
returns the agent's voice, transcripts and function calls. Speech
recognition, the language model, the voice, turn-taking, 47 languages and
built-in tools all run on ThunderPhone; the pipeline supplies the transport
(Daily, LiveKit, Twilio, WebRTC, a local microphone).

Two ways to use it:

* **Saved agent** — pass `agent_id`. The agent's prompt, voice, engine,
  languages, tools, greeting and silence handling are configured on
  ThunderPhone.
* **Inline** — instructions and tools come from the Pipecat context, as with
  the OpenAI Realtime service. `product` picks the engine (`spark`, `bolt`
  or `storm`) and `voice` the ThunderPhone voice. Function calls run in your
  Pipecat handlers.

The integration supports server-side turn detection, interruption handling,
user transcriptions, function calling (inline sessions), and ThunderPhone's
`call.*` platform events (hang-up, transfer, keypad).

## Installation

Install the community-maintained package from PyPI:

```bash theme={null}
uv add pipecat-thunderphone
```

## Prerequisites

* A ThunderPhone account and a secret API key (`sk_live_...`) from the
  dashboard under **Developer → API keys**.
* Optionally a saved agent id, if you want the agent configured on
  ThunderPhone rather than in your pipeline.

Calls are billed at ThunderPhone's per-minute engine rate; there is no
subscription.

## Configuration

Set your ThunderPhone API key in the server environment:

```bash theme={null}
export THUNDERPHONE_API_KEY=sk_live_...
```

Create the service and add it to your pipeline in place of separate STT, LLM
and TTS services:

```python theme={null}
from pipecat_thunderphone import ThunderPhoneRealtimeLLMService

# Run a saved ThunderPhone agent
llm = ThunderPhoneRealtimeLLMService(agent_id=12)

# ...or configure the session inline
llm = ThunderPhoneRealtimeLLMService(product="bolt", voice="olivia", language="es")
```

### Common parameters

<ParamField path="api_key" type="str">
  ThunderPhone secret key (`sk_live_...`). Defaults to the
  `THUNDERPHONE_API_KEY` environment variable.
</ParamField>

<ParamField path="agent_id" type="int | str">
  Id of a saved ThunderPhone agent. Mutually exclusive with `product` and
  `voice`.
</ParamField>

<ParamField path="product" type="str">
  Engine for inline sessions: `"spark"`, `"bolt"` or `"storm"`.
</ParamField>

<ParamField path="voice" type="str">
  ThunderPhone voice name for inline sessions.
</ParamField>

<ParamField path="language" type="str">
  Primary language hint for inline sessions, for example `"es"`.
</ParamField>

<ParamField path="live_transcripts" type="bool" default="False">
  Stream caller transcript fragments while the caller is still speaking
  (billed extra). Off by default: one transcript per turn.
</ParamField>

<ParamField path="greet_on_connect" type="bool">
  Request a first response as soon as the session is ready. Defaults to
  `True` for inline sessions and `False` for saved agents, which greet on
  their own.
</ParamField>

<ParamField path="end_task_on_call_ended" type="bool" default="True">
  Push an `EndWorkerFrame` upstream when ThunderPhone ends the call, so the
  pipeline finishes cleanly.
</ParamField>

Function tools for inline sessions are declared on the `LLMContext` and
registered with `llm.register_function(...)`, exactly as for the OpenAI
Realtime service.

### Minimal pipeline

The following example assumes `transport` is an existing Pipecat audio
transport:

```python theme={null}
from pipecat.pipeline.pipeline import Pipeline
from pipecat.processors.aggregators.llm_context import LLMContext
from pipecat.processors.aggregators.llm_response_universal import (
    LLMContextAggregatorPair,
)

context = LLMContext(
    messages=[{"role": "system", "content": "You are Acme Dental's receptionist."}]
)
aggregators = LLMContextAggregatorPair(context)

pipeline = Pipeline(
    [
        transport.input(),
        aggregators.user(),
        llm,
        aggregators.assistant(),
        transport.output(),
    ]
)
```

### Events

ThunderPhone adds platform events on top of the realtime protocol. The
service delivers them to handlers, and `llm.call_id` identifies the call for
fetching the recording, transcript and grade afterwards:

```python theme={null}
@llm.event_handler("on_call_ended")
async def on_call_ended(service, event):
    print("call ended:", event["reason"], "call id:", service.call_id)
```

## Compatibility

The package requires `pipecat-ai>=1.8,<2` and is tested with Pipecat v1.8.1
on Python 3.11 to 3.13. Turn detection is server-side and always on;
Pipecat-driven turns (`turn_detection=False`) are not supported. Audio is
16-bit mono PCM at 24 kHz in both directions.

## Resources

<CardGroup cols={2}>
  <Card title="Integration guide" icon="github" href="https://github.com/autophonix/pipecat-thunderphone#readme">
    Setup instructions, the example bot, configuration options and limits
  </Card>

  <Card title="PyPI package" icon="cube" href="https://pypi.org/project/pipecat-thunderphone/">
    Package releases and installation metadata
  </Card>

  <Card title="ThunderPhone documentation" icon="book" href="https://thunderphone.com/docs/guides/use-with-pipecat">
    Using ThunderPhone from Pipecat, and the Realtime WebSocket API reference
  </Card>

  <Card title="ThunderPhone API keys" icon="key" href="https://thunderphone.com/docs/guides/api-keys">
    Create a secret API key
  </Card>
</CardGroup>