Skip to main content

​
Overview

ThunderPhoneRealtimeLLMService connects a Pipecat pipeline to ThunderPhone, 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:

​
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:
Create the service and add it to your pipeline in place of separate STT, LLM and TTS services:

​
Common parameters

​
str
ThunderPhone secret key (sk_live_...). Defaults to the THUNDERPHONE_API_KEY environment variable.
​
int | str
Id of a saved ThunderPhone agent. Mutually exclusive with product and voice.
​
str
Engine for inline sessions: "spark", "bolt" or "storm".
​
str
ThunderPhone voice name for inline sessions.
​
str
Primary language hint for inline sessions, for example "es".
​
bool
default:"False"
Stream caller transcript fragments while the caller is still speaking (billed extra). Off by default: one transcript per turn.
​
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.
​
bool
default:"True"
Push an EndWorkerFrame upstream when ThunderPhone ends the call, so the pipeline finishes cleanly.
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:

​
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:

​
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

Integration guide

Setup instructions, the example bot, configuration options and limits

PyPI package

Package releases and installation metadata

ThunderPhone documentation

Using ThunderPhone from Pipecat, and the Realtime WebSocket API reference

ThunderPhone API keys

Create a secret API key