Use ThunderPhone with Pipecat

1. Install the documented adapter. Use pip install pipecat-thunderphone in a clean environment. Confirm the resolved pipecat-ai version is 1.8 or newer; do not mix incompatible transport examples from older releases.
2. Select agent mode. Prefer a saved deployed ThunderPhone agent for shared prompt, voice, tools, knowledge, and testing. Use inline session config only when the application must own those fields.
3. Store the credential as THUNDERPHONE_API_KEY. Never embed it in client JavaScript, recordings, or pipeline logs.
4. Create the service. Import ThunderPhoneRealtimeLLMService from the installed adapter and pass the API key plus the documented saved agent_id or inline session options. Wire the service between the application's chosen input/output transports as shown in the Pipecat guide.
5. Use the OpenAI Realtime protocol at wss://api.thunderphone.com/v1/realtime. Let the adapter manage event and audio framing; do not combine REST call fields with realtime session fields.
6. Inspect server-side sessions during backend diagnosis with POST /v1/realtime/sessions only when the integration requires explicit session creation.

{
  "agent_id": 12
}

curl --fail-with-body -X POST https://api.thunderphone.com/v1/realtime/sessions \
  -H "Authorization: Bearer $THUNDERPHONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-ThunderPhone-Client: skills/use-with-pipecat@1.0" \
  --data-binary @realtime-session.json

import json, os, requests
with open("realtime-session.json", encoding="utf-8") as f: payload = json.load(f)
r = requests.post("https://api.thunderphone.com/v1/realtime/sessions", json=payload,
    headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}",
             "X-ThunderPhone-Client": "skills/use-with-pipecat@1.0"}, timeout=30)
r.raise_for_status(); print(r.json())

import { readFile } from "node:fs/promises";
const r = await fetch("https://api.thunderphone.com/v1/realtime/sessions", { method: "POST",
  headers: { Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}`,
    "Content-Type": "application/json", "X-ThunderPhone-Client": "skills/use-with-pipecat@1.0" },
  body: await readFile("realtime-session.json", "utf8") });
if (!r.ok) throw new Error(await r.text()); console.log(await r.json());

7. Verify end to end. Test connection, two-way audio, interruptions, tool calls, language switching, teardown, and error recovery. Correlate client events with ThunderPhone call/session records.

Errors

Source and safety rules

• Follow use with Pipecat and the Realtime API.
• Keep the API key server-side and redact event payloads before logging.
• Do not claim latency or audio quality without a real audio run.
• Pin compatible packages for production and retest before upgrades.

See references/pipecat-checklist.md.