diff --git a/examples/deployment/pipecat-cloud-dialin-server/README.md b/examples/deployment/pipecat-cloud-dialin-server/README.md index 93181927f..ceb29cbd3 100644 --- a/examples/deployment/pipecat-cloud-dialin-server/README.md +++ b/examples/deployment/pipecat-cloud-dialin-server/README.md @@ -1,29 +1,31 @@ -# Handling PSTN/SIP Dial-in on Pipecat cloud +# Handling PSTN/SIP Dial-in on Pipecat Cloud -This repository contains two server implementations for handling -the pinless dialin workflow in pipecat cloud. This is the companion to the -Pipecat Cloud [pstn_sip starter image](https://github.com/daily-co/pipecat-cloud-images/tree/main/pipecat-starters/pstn_sip). -In addition you can use `/api/dial` to trigger dial-out, and +This repository contains two server implementations for handling +the pinless dial-in workflow in Pipecat Cloud. This is the companion to the +Pipecat Cloud [pstn_sip starter image](https://github.com/daily-co/pipecat-cloud-images/tree/main/pipecat-starters/pstn_sip). +In addition you can use `/api/dial` to trigger dial-out, and eventually, call-transfers. -1. [FastAPI Server](simple-python/README.md) - -A FastAPI implementation that handles PSTN (Public Switched Telephone -Network) and SIP (Session Initiation Protocol) calls using the Daily API. +1. [FastAPI Server](simple-python/README.md) - + A FastAPI implementation that handles PSTN (Public Switched Telephone + Network) and SIP (Session Initiation Protocol) calls using the Daily API. -2. [Vercel Serverless](vercel/README.md) - -A Next.js API implementation designed for deployment on Vercel's -serverless platform. +2. [Vercel Serverless](vercel/README.md) - + A Next.js API implementation designed for deployment on Vercel's + serverless platform. Both implementations provide: -- HMAC signature validation for pinless webhook + +- HMAC signature validation for pinless webhook - Structured logging -- Support for dialin and dialout settings +- Support for dial-in and dial-out settings - Voicemail detection and call transfer functionality (coming soon) - Test request handling ## Choosing an Implementation - Use the **Simple Python Server** if you: + - Need a standalone server - Prefer Python and FastAPI - Want to deploy to traditional hosting platforms @@ -39,22 +41,24 @@ Both implementations provide: ### Environment Variables Both implementations require similar environment variables: -- `PIPECAT_CLOUD_API_KEY`: Pipecat Cloud API Key, begins with pk_* + +- `PIPECAT_CLOUD_API_KEY`: Pipecat Cloud API Key, begins with pk\_\* - `AGENT_NAME`: Your Daily agent name - `PINLESS_HMAC_SECRET`: Your HMAC secret for request verification - `LOG_LEVEL`: (Optional) Logging level (defaults to 'info') -See the individual README files in each implementation directory for +See the individual README files in each implementation directory for specific setup instructions. ### Phone number setup You can buy a phone number through the Pipecat Cloud Dashboard: + 1. Go to `Settings` > `Telephony` 2. Follow the UI to purchase a phone number 3. Configure the webhook URL to receive incoming calls (e.g. `https://my-webhook-url.com/api/dial`) -Or purchase the number using Daily's +Or purchase the number using Daily's [PhoneNumbers API](https://docs.daily.co/reference/rest-api/phone-numbers). ```bash @@ -74,24 +78,24 @@ curl --request POST \ }' ``` -The API will return a static SIP URI (`sip_uri`) that can be called +The API will return a static SIP URI (`sip_uri`) that can be called from other SIP services. ### `room_creation_api` -To make and receive calls currently you have to host a server that -handles incoming calls. In the coming weeks, incoming calls will be -directly handled within Daily and we will expose an endpoint similar +To make and receive calls currently you have to host a server that +handles incoming calls. In the coming weeks, incoming calls will be +directly handled within Daily and we will expose an endpoint similar to `{service}/start` that will manage this for you. -In the meantime, the server described below serves as the webhook -handler for the `room_creation_api`. Configure your pinless phone -number or SIP interconnect to the `ngrok` tunnel or -the actual server URL, append `/api/dial` to the webhook URL. +In the meantime, the server described below serves as the webhook +handler for the `room_creation_api`. Configure your pinless phone +number or SIP interconnect to the `ngrok` tunnel or +the actual server URL, append `/api/dial` to the webhook URL. -## Examples curl commands +## Example curl commands -Note: Replace `http://localhost:3000` with your actual server URL and +Note: Replace `http://localhost:3000` with your actual server URL and phone numbers with valid values for your use case. ### Dialin Request @@ -114,7 +118,7 @@ curl -X POST http://localhost:3000/api/dial \ }' ``` -Dial a number with callerId, which is the UUID of a purchased number. +Dial a number with callerId, which is the UUID of a purchased number. ```bash curl -X POST http://localhost:3000/api/dial \ @@ -145,6 +149,7 @@ curl -X POST http://localhost:3000/api/dial \ ``` ### Advanced Request with Voicemail Detection + ```bash curl -X POST http://localhost:3000/api/dial \ -H "Content-Type: application/json" \ @@ -171,7 +176,3 @@ curl -X POST http://localhost:3000/api/dial \ } }' ``` - - - - diff --git a/examples/deployment/pipecat-cloud-dialin-server/simple-python/README.md b/examples/deployment/pipecat-cloud-dialin-server/simple-python/README.md index 53faa0ea8..a0cdbc8a7 100644 --- a/examples/deployment/pipecat-cloud-dialin-server/simple-python/README.md +++ b/examples/deployment/pipecat-cloud-dialin-server/simple-python/README.md @@ -5,34 +5,49 @@ A FastAPI server that handles PSTN (Public Switched Telephone Network) and SIP ( ## Setup 1. Clone the repository + 2. Install dependencies: + ```bash pip install -r requirements.txt ``` + 3. Copy `env.example` to `.env`: + ```bash - cp .env.example .env + cp env.example .env ``` + 4. Update `.env` with your credentials: + - `AGENT_NAME`: Your Daily agent name - `PIPECAT_CLOUD_API_KEY`: Your Daily API key - `PINLESS_HMAC_SECRET`: Your HMAC secret for request verification ## Running the Server -3. Copy `env.example` to `.env`: -Start the server with: + +Start the server: + ```bash python server.py ``` + The server will run on `http://localhost:3000` and you can expose it via ngrok for testing: + +```bash `ngrok http 3000` +``` + +> Tip: Use a subdomain for a consistent URL (e.g. `ngrok http -subdomain=mydomain http://localhost:3000`) ## API Endpoints ### GET / + Health check endpoint that returns a "Hello, World!" message. ### POST /api/dial + Initiates a PSTN/SIP call with the following request body format: ```json @@ -61,13 +76,15 @@ Initiates a PSTN/SIP call with the following request body format: ``` #### Response + Returns a JSON object containing: + - `status`: Success/failure status - `data`: Response from Daily API - `room_properties`: Properties of the created Daily room - ## Error Handling + - 401: Invalid signature - 400: Invalid authorization header (e.g. missing Daily API key in bot.py) - 405: Method not allowed (e.g. incorrect route on the webhook URL) diff --git a/examples/deployment/pipecat-cloud-dialin-server/vercel/README.md b/examples/deployment/pipecat-cloud-dialin-server/vercel/README.md index 8a00d2b17..946f6b096 100644 --- a/examples/deployment/pipecat-cloud-dialin-server/vercel/README.md +++ b/examples/deployment/pipecat-cloud-dialin-server/vercel/README.md @@ -7,39 +7,61 @@ Next.js API routes for handling Daily Pipecat requests. - API endpoint for handling Daily Pipecat requests - HMAC signature validation - Structured logging with Pino -- Support for dialin and dialout settings +- Support for dial-in and dial-out settings - Voicemail detection and call transfer functionality - Test request handling ## Setup 1. Clone the repository -2. Install dependencies: - ```bash - npm install - ``` -3. Create `.env.local` file with your credentials: - ``` - PIPECAT_CLOUD_API_KEY=pk_* - AGENT_NAME=my-first-agent - PINLESS_HMAC_SECRET=your_hmac_secret - LOG_LEVEL=info - ``` -4. Run the development server: - ```bash - npm run dev - ``` + +2. Navigate to the `vercel` directory: + +```bash +cd vercel +``` + +3. Install dependencies: + +```bash +npm install +``` + +4. Create `.env.local` file with your credentials: + +```bash +cp env.local.example .env.local +``` + +Add your secrets: + +```bash +PIPECAT_CLOUD_API_KEY=pk_* +AGENT_NAME=my-first-agent +PINLESS_HMAC_SECRET=your_hmac_secret +LOG_LEVEL=info +``` + +5. Run the development server: + +```bash +npm run dev +``` ## API Endpoints ### GET /api + Returns a simple "Hello, World!" message with a cute cat emoji to verify the server is running. ### POST /api/dial -Handles dialin and dialout requests for Daily Pipecat. + +Handles dial-in and dial-out requests for Pipecat Cloud. #### Test Requests + The endpoint handles test requests when a webhook is configured. Send a request with `"Test": "test"` to verify your setup: + ```json { "Test": "test" @@ -47,6 +69,7 @@ The endpoint handles test requests when a webhook is configured. Send a request ``` #### Production Request Format + ```json { // for dial-in from webhook @@ -56,9 +79,9 @@ The endpoint handles test requests when a webhook is configured. Send a request "callDomain": "string-contains-uuid", // for making a dial out to a phone or SIP "dialout_settings": [ - {"phoneNumber": "+14158483432", "callerId": "purchased_phone_uuid"}, - {"sipUri": "sip:username@sip.hostname.com"} - ], + { "phoneNumber": "+14158483432", "callerId": "purchased_phone_uuid" }, + { "sipUri": "sip:username@sip.hostname.com" } + ] } ``` @@ -79,4 +102,4 @@ The application is configured for Vercel deployment: - HMAC signature validation for request authentication - Environment variables for sensitive credentials -- Method validation (POST only for /dial) \ No newline at end of file +- Method validation (POST only for /dial)