Pipecat Cloud Telephony Quickstart

Spin up a minimal Pipecat Cloud agent that can answer or place calls over PSTN/SIP. This repository contains two deployable pieces:

• webhook/server.py → a FastAPI app packaged with Modal that receives telephony webhooks from Daily Pipecat Cloud.
• bot.py → the Pipecat AI pipeline the agent runs in the Daily room, using OpenAI, Deepgram, and Cartesia for the conversational loop.
• Daily telephony → supplies the phone number, triggers the webhook, and bridges audio into the Pipecat session.

How It Works

1. Pipecat Cloud receives an incoming or outgoing call event for your agent.
2. Pipecat Cloud invokes the Modal URL you deploy in this guide.
3. The Modal webhook creates a Daily room, configures dial-in/out, and calls the Pipecat Cloud start endpoint.
4. The Pipecat agent defined in bot.py joins the room, greets the caller, and handles conversation end-to-end.

Prerequisites

Have the following set up before running commands:

• Accounts: Pipecat Cloud (Daily), Daily Telephony number, Docker registry (Docker Hub or private), Modal.
• API keys: OpenAI, Deepgram, Cartesia, Daily REST key (for telephony), Pipecat Cloud API key.
• CLIs: uv, modal, and the Pipecat Cloud CLI (pcc) installed and authenticated.
• Runtime: Python 3.12 (matches .python-version).
• Billing awareness: purchasing a phone number and placing external calls incur charges with Daily and carriers.

Record organization identifiers you will substitute in later commands:

• <pipecat-cloud-organization> – found in the Pipecat Cloud dashboard URL.
• <modal-organization> – visible after logging into Modal.
• <docker-registry> – e.g., docker.io/<username> or internal registry path.

Deploy the Modal Webhook

Run these steps from the repository root unless noted otherwise.

1. cd webhook
2. cp .env.example .env
   • Fill in PIPECAT_CLOUD_API_KEY (from the Pipecat Cloud dashboard). Leave AGENT_NAME set to the agent you deploy later.
3. uv sync --active
   • Installs webhook dependencies into the .venv managed by uv for Python 3.12.
4. uv run --active modal deploy server.py
   • Builds the Modal image, uploads dependencies, and returns a URL similar to https://<modal-organization>--fastapi-webhook-server-dial.modal.run.
5. Note the returned URL; you will paste it into Pipecat Cloud when configuring the phone number webhook.

Configure the Pipecat Agent Deployment

Return to the repository root (cd ..). These commands provision the agent that Pipecat Cloud executes.

1. cp .env.example .env
   • Populate the voice, transcription, and LLM API keys (OpenAI, Deepgram, Cartesia, Daily).
2. uv sync
   • Installs the agent’s dependencies (Pipecat AI SDK and Pipecat Cloud Python utilities) into the root .venv.
3. cp pcc-deploy.toml.example pcc-deploy.toml
   • Update the copy with your Docker image reference, agent name, and secret set as needed.
4. uv run pcc secrets set pstn-sip-modal-secrets --file .env
   • Uploads the environment variables in .env to Pipecat Cloud under the secret set referenced by pcc-deploy.toml. Re-run this command whenever you rotate keys.
5. uv run pcc docker build-push
   • Builds the agent Docker image using pcc and pushes it to the registry configured in pcc-deploy.toml.
6. uv run pcc deploy -nc
   • Deploys the agent to Pipecat Cloud. The -nc flag is for public Docker images.

Attach the Webhook to Your Phone Number

1. Visit https://pipecat.daily.co/<pipecat-cloud-organization>/settings/telephony.
2. Purchase or select the phone number you want to use.
3. Set the webhook URL to the Modal endpoint you copied earlier and save the configuration.

Environment Reference

File	Key	Purpose
webhook/.env	AGENT_NAME	Matches the Pipecat agent slug in Pipecat Cloud.
	PIPECAT_CLOUD_API_KEY	Authenticates the Modal webhook when calling Pipecat Cloud.
	PINLESS_HMAC_SECRET	Base64 secret used to validate Pipecat Cloud signature headers.
.env	OPENAI_API_KEY	Generates responses via OpenAI’s chat models.
	DEEPGRAM_API_KEY	Provides transcription for caller audio.
	CARTESIA_API_KEY	Synthesizes voice responses.
	DAILY_API_KEY	Optional Daily REST operations invoked by the agent.
pcc-deploy.toml	agent_name	Defines the agent slug deployed to Pipecat Cloud.
	image	Docker image pushed in the deploy step; customize for your registry.
	secret_set	References the secrets uploaded with pcc secrets set.

Reference Material

• Pipecat Cloud Documentation
• Modal Documentation

Contribute

Help keep this the most minimal Pipecat Cloud + telephony example. Open an issue or pull request with improvements, alternative provider notes, or streamlined setup ideas.