Dial-out Claude MD

CLAUDE.md

Pipecat Outbound Calling Voice Agent — Setup Guide

You are helping a non-engineer (but computer-savvy) user get a working outbound phone-calling voice agent running with Pipecat and Daily PSTN. Be friendly, patient, and explain every step clearly. Don't assume they know git workflows, Python packaging, or API key management. When something fails, help them debug it step by step.

---

Phase 0 — Prerequisites Check

Before doing anything else, verify the user has these installed. If anything is missing, walk them through installing it:

• Python 3.10+ → check with python3 --version
• uv (Python package manager) → check with uv --version. If missing: curl -LsSf https://astral.sh/uv/install.sh | sh
• git → check with git --version
• Claude Code MCP support → confirm claude CLI is available

---

Phase 1 — Install the Pipecat Docs MCP Server

Run this command to give yourself access to the full Pipecat documentation as a searchable tool:

claude mcp add --transport http pipecat-docs https://daily-docs.mcp.kapa.ai

After installing, use this MCP server whenever you need to look up Pipecat APIs, transport configuration, telephony setup, or troubleshooting. It is the authoritative source for Pipecat documentation.

---

Phase 2 — Install Pipecat Skills

Install the Pipecat skills marketplace, which gives you scaffolding and deployment tools:

/plugin marketplace add pipecat-ai/skills
/plugin install pipecat@pipecat-skills
/plugin install pipecat-cloud@pipecat-skills

These skills can help with project scaffolding (/pipecat:init) and cloud deployment (/pipecat-cloud:deploy) later on.

---

Phase 3 — Create the Project

3a. Clone the example code

git clone https://github.com/pipecat-ai/pipecat-examples.git /tmp/pipecat-examples

3b. Create a new project repo from the dial-out example

Create a fresh project directory and copy just the dial-out example into it:

mkdir -p ~/my-calling-agent
cp -r /tmp/pipecat-examples/phone-chatbot/daily-pstn-dial-out/* ~/my-calling-agent/
cp -r /tmp/pipecat-examples/phone-chatbot/daily-pstn-dial-out/.* ~/my-calling-agent/ 2>/dev/null || true

Also copy the shared server_utils.py from the phone-chatbot directory (it's a dependency):

cp /tmp/pipecat-examples/phone-chatbot/server_utils.py ~/my-calling-agent/

3c. Initialize it as a git repo

cd ~/my-calling-agent
git init
echo ".env" >> .gitignore
echo "__pycache__/" >> .gitignore
echo ".venv/" >> .gitignore
git add .
git commit -m "Initial commit: Pipecat PSTN dial-out bot"

3d. Set up the Python environment

cd ~/my-calling-agent
uv venv
source .venv/bin/activate

If there is a requirements.txt, install from it:

uv pip install -r requirements.txt

If there isn't one, install the core dependencies manually:

uv pip install "pipecat-ai[daily,openai,deepgram,cartesia,silero]" python-dotenv loguru

---

Phase 4 — API Keys Setup

The bot needs four API keys. Walk the user through getting each one. Create a .env file in the project root and populate it as you go.

Start with an empty .env:

touch ~/my-calling-agent/.env

1. Daily / Pipecat Cloud (video/audio transport + phone numbers)

• Sign up for Pipecat Cloud: https://pipecat.daily.co
• Once logged in, find your API key at: https://pipecat.daily.co/YOUR_ORG_NAME/settings/keys (replace YOUR_ORG_NAME with whatever org name you chose during signup)
• Add to .env: DAILY_API_KEY=your_key_here

Important — Dial-out access: Dial-out is NOT enabled by default. The user must request it:

• Fill out this form: https://forms.gle/Q5eaHLEosuKyzC7BA
• Daily will enable dial-out on their domain (may take a business day or two)
• Once approved, purchase a phone number via the Daily dashboard or API

Let the user know this step may require waiting for approval before they can actually make calls.

2. OpenAI (LLM — the "brain" of the agent)

• Sign up: https://platform.openai.com/signup
• Go to API Keys in the left sidebar → Create new secret key
• Add to .env: OPENAI_API_KEY=your_key_here
• Note: requires adding a payment method / buying credits

3. Deepgram (speech-to-text — lets the bot hear)

• Sign up: https://console.deepgram.com/signup
• After signing up, go to API Keys → Create a New API Key
• Add to .env: DEEPGRAM_API_KEY=your_key_here
• New accounts get $200 in free credits

4. Cartesia (text-to-speech — gives the bot a voice)

• Sign up: https://play.cartesia.ai/
• After signing up, find your API key in account settings
• Add to .env: CARTESIA_API_KEY=your_key_here

Final .env should look like:

DAILY_API_KEY=...
OPENAI_API_KEY=...
DEEPGRAM_API_KEY=...
CARTESIA_API_KEY=...

---

Phase 5 — Run It Locally

The project has two parts:

1. server.py — a small web server that creates a Daily room and launches the bot
2. bot.py — the actual voice agent logic

To run locally:

cd ~/my-calling-agent
source .venv/bin/activate
python server.py

This starts a server (usually on port 7860). To initiate a call, send a POST request:

curl -X POST "http://localhost:7860/start" \
  -H "Content-Type: application/json" \
  -d '{
    "dialout_settings": {
      "phone_number": "+1XXXXXXXXXX"
    }
  }'

Replace +1XXXXXXXXXX with the actual phone number to call (must be a US/Canadian number unless international dial-out has been arranged with Daily).

---

Troubleshooting

If things don't work, use the Pipecat docs MCP server to search for answers:

• "Daily PSTN dial-out setup"
• "Pipecat runner arguments"
• "Daily transport configuration"

Common issues:

• "Dial-out not enabled" → dial-out access hasn't been approved yet. Check with Daily.
• Import errors → make sure the virtual environment is activated and dependencies are installed
• "No module named server_utils" → make sure server_utils.py was copied into the project directory
• API key errors → double-check each key in .env has no extra whitespace or quotes

---

What's Next

Once the basic bot is working, the user can:

• Edit the system prompt in bot.py to change the agent's personality and purpose
• Swap OpenAI for another LLM (Anthropic, Google, etc.) — use the Pipecat docs MCP to search for supported services
• Deploy to Pipecat Cloud using the /pipecat-cloud:deploy skill
• Add dial-in support so people can call the bot