ThunderPhone 2.0 is live.Self-serve, from 2¢/min.Read the announcement
Get started

Facts verified against published sources on .

Pipecat

Pipecat is an open-source framework for building voice agents out of composable services. ThunderPhone plugs into it as a speech-to-speech service through the first-party pipecat-thunderphone package, which is listed on Pipecat's supported-services page. Pipecat's transport carries the audio (Daily, LiveKit, a telephony trunk, WebRTC or a local microphone); ThunderPhone runs speech recognition, the language model, the voice, turn-taking, 47 languages and tools.

This is an integration for teams that already build on Pipecat and want a phone agent they do not have to assemble from separate recognition, model and voice services. It is not a replacement for Pipecat's pipeline model: your pipeline still owns the transport, any extra processors, and when the session starts and ends.

What the package does

pip install pipecat-thunderphone adds ThunderPhoneRealtimeLLMService, a subclass of Pipecat's OpenAI Realtime service. ThunderPhone's realtime WebSocket speaks the same protocol, so the service reuses Pipecat's audio, transcript and function-call plumbing and adds the ThunderPhone-specific parts: the endpoint and its query parameters, sk_live_ API keys, saved agents, and the platform's call events.

Two ways to run it:

  • Saved agent. Pass agent_id. The agent's prompt, voice, engine, languages, tools, greeting and silence handling are configured on ThunderPhone. The pipeline only moves audio, and the agent opens the call on its own schedule.
  • Inline session. Omit agent_id. Instructions and tools come from the Pipecat context, the way they do for any hosted realtime model; product picks the engine and voice picks the ThunderPhone voice. Functions registered on the service run inside your pipeline.

Every session is one ThunderPhone call. It appears in call history with a recording, transcript and grade, and it is billed at the product's per-minute rate. There is no subscription and no ThunderPhone phone number involved unless you want one.

Typical call flows

Phone line fronted by Pipecat

A Pipecat pipeline attached to a telephony or LiveKit SIP transport answers the call and streams audio to a saved ThunderPhone agent. The agent handles the conversation as an AI receptionist would on ThunderPhone's own numbers, and the pipeline hangs up when ThunderPhone reports call.ended. Pass from_number and to_number so the call record shows the real parties.

Web or in-app voice with your own tools

An inline session runs the receptionist prompt from your code and registers functions such as availability lookups. When the agent decides to call one, Pipecat runs it in your process and returns the result; ThunderPhone continues the turn with the answer. This is standard function calling, with the reasoning on ThunderPhone's side.

Mixed pipelines

Because the service is a normal Pipecat processor, it can sit alongside recording, analytics or moderation processors in the same pipeline. Audio in and out is 16-bit mono PCM at 24 kHz in both directions.

Setup outline

  1. Create a secret API key in the ThunderPhone dashboard and set THUNDERPHONE_API_KEY.
  2. pip install pipecat-thunderphone (needs Pipecat 1.8 or newer).
  3. Add ThunderPhoneRealtimeLLMService(agent_id=...) between the user and assistant context aggregators of your pipeline, or configure an inline session with product, voice and your instructions.
  4. Handle on_call_ended if the pipeline needs to know why the call finished; service.call_id links the session to the call record for the recording and transcript.
  5. Test barge-in, a tool round trip and an agent hang-up before going to production.

The full walkthrough with code is in the docs: Use ThunderPhone from Pipecat.

Limits worth knowing

  • Turn detection is server-side and always on. Pipecat-driven turns are not supported.
  • A saved agent runs its own tools on ThunderPhone; functions registered on the service apply to inline sessions only.
  • Instructions, tools and voice are fixed once the call starts. Change them by starting a new session.
  • Video frames are ignored.

Related workflows and terms