> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vobiz.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pipecat integration

> Pipecat connects to Vobiz SIP trunking to power AI voice pipelines on real phone calls - WebSocket streaming and SIP trunk setup across 130+ countries.

This integration combines Vobiz telephony with the [Pipecat](https://pipecat.ai) voice agent framework to build intelligent AI-powered phone calls.

<iframe width="100%" height="420" src="https://www.youtube.com/embed/4ae-Lgg2gbU" title="Pipecat + Vobiz Integration Tutorial" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen style={{ borderRadius: "12px", marginTop: "1rem", marginBottom: "1rem" }} />

## Overview

**What you'll build:** An outbound calling system with real-time AI conversations powered by OpenAI (STT → LLM → TTS), automatic call recording, and bidirectional audio streaming.

<div className="border border-slate-200 bg-slate-50 rounded-xl p-6 my-8">
  <div className="font-bold text-slate-800 mb-4">Call flow:</div>

  <div className="flex-1 bg-white border border-slate-200 rounded-lg p-4 flex flex-wrap items-center gap-3">
    <div className="bg-orange-50 border border-orange-200 text-orange-800 px-3 py-1 rounded text-sm font-medium">curl POST</div>
    <div className="text-slate-400">→</div>
    <div className="bg-orange-50 border border-orange-200 text-orange-800 px-3 py-1 rounded text-sm font-medium">Vobiz API</div>
    <div className="text-slate-400">→</div>
    <div className="bg-orange-50 border border-orange-200 text-orange-800 px-3 py-1 rounded text-sm font-medium">Call initiated</div>
    <div className="text-slate-400">→</div>
    <div className="bg-orange-50 border border-orange-200 text-orange-800 px-3 py-1 rounded text-sm font-medium">Call answered</div>
    <div className="text-slate-400">→</div>
    <div className="bg-orange-50 border border-orange-200 text-orange-800 px-3 py-1 rounded text-sm font-medium">Vobiz requests XML</div>
    <div className="text-slate-400">→</div>
    <div className="bg-orange-50 border border-orange-200 text-orange-800 px-3 py-1 rounded text-sm font-medium">Server returns WebSocket URL</div>
    <div className="text-slate-400">→</div>
    <div className="bg-orange-50 border border-orange-200 text-orange-800 px-3 py-1 rounded text-sm font-medium">Audio streams</div>
    <div className="text-slate-400">→</div>
    <div className="bg-orange-50 border border-orange-200 text-orange-800 px-3 py-1 rounded text-sm font-medium">Pipecat bot (STT → LLM → TTS)</div>
    <div className="text-slate-400">→</div>
    <div className="bg-orange-50 border border-orange-200 text-orange-800 px-3 py-1 rounded text-sm font-medium">AI conversation + Recording</div>
  </div>
</div>

## Features

<CardGroup cols={2}>
  <Card title="AI Voice Conversations" icon="robot">
    Natural conversations powered by OpenAI GPT + TTS/STT
  </Card>

  <Card title="Outbound Calling" icon="phone-arrow-up-right">
    Trigger calls via REST API from anywhere
  </Card>

  <Card title="Automatic Recording" icon="microphone">
    All conversations automatically recorded and saved
  </Card>

  <Card title="Real-time Streaming" icon="wave-square">
    Bidirectional audio via WebSockets
  </Card>
</CardGroup>

## Prerequisites

<div className="border border-gray-200 dark:border-gray-800 rounded-xl p-6 mt-4 mb-8">
  <div className="flex flex-col gap-5">
    <div className="flex items-center gap-3">
      <div className="w-5 h-5 rounded bg-[#4ade80] flex items-center justify-center text-white shrink-0">
        <svg className="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth="4" d="M5 13l4 4L19 7" />
        </svg>
      </div>

      <div className="text-gray-800 dark:text-gray-200 text-[15px]">**Vobiz Account** with Auth ID and Auth Token → <a href="https://console.vobiz.ai/auth/signup" className="text-primary hover:underline">Sign up</a></div>
    </div>

    <div className="flex items-center gap-3">
      <div className="w-5 h-5 rounded bg-[#4ade80] flex items-center justify-center text-white shrink-0">
        <svg className="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth="4" d="M5 13l4 4L19 7" />
        </svg>
      </div>

      <div className="text-gray-800 dark:text-gray-200 text-[15px]">**OpenAI API Key** for LLM, STT, and TTS → <a href="https://platform.openai.com/api-keys" className="text-primary hover:underline">Get API key</a></div>
    </div>

    <div className="flex items-center gap-3">
      <div className="w-5 h-5 rounded bg-[#4ade80] flex items-center justify-center text-white shrink-0">
        <svg className="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth="4" d="M5 13l4 4L19 7" />
        </svg>
      </div>

      <div className="text-gray-800 dark:text-gray-200 text-[15px]">**Python 3.10+** installed on your system</div>
    </div>

    <div className="flex items-center gap-3">
      <div className="w-5 h-5 rounded bg-[#4ade80] flex items-center justify-center text-white shrink-0">
        <svg className="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth="4" d="M5 13l4 4L19 7" />
        </svg>
      </div>

      <div className="text-gray-800 dark:text-gray-200 text-[15px]">**ngrok** for local development → <a href="https://ngrok.com/download" className="text-primary hover:underline">Download ngrok</a></div>
    </div>
  </div>
</div>

## Installation

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/vobiz-ai/Vobiz-X-Pipecat
    cd Vobiz-X-Pipecat
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    pip install -r requirements.txt
    ```

    <Note>This installs FastAPI, Pipecat, OpenAI SDK, and other required packages.</Note>
  </Step>

  <Step title="Configure environment">
    The repo ships an `env.example` file. Copy it and fill in your values:

    ```bash theme={null}
    cp env.example .env
    ```

    ```bash .env theme={null}
    # Required
    OPENAI_API_KEY=sk-...
    VOBIZ_AUTH_ID=MA_XXXXXXXX
    VOBIZ_AUTH_TOKEN=your-token-here
    PUBLIC_URL=https://your-ngrok-url.ngrok-free.app

    # Optional
    VOBIZ_PHONE_NUMBER=+918065480214        # default `from` for the /start endpoint
    DEEPGRAM_API_KEY=...                    # use Deepgram for STT instead of OpenAI
    ```

    **Where to find these values:**

    * `OPENAI_API_KEY` - OpenAI Platform → API Keys
    * `VOBIZ_AUTH_ID` - Vobiz Console → Account Settings
    * `VOBIZ_AUTH_TOKEN` - Vobiz Console → Account Settings
    * `PUBLIC_URL` - Your ngrok URL (set in Step 2 of Usage)
    * `VOBIZ_PHONE_NUMBER` *(optional)* - Vobiz number used as the caller-ID for `/start`
    * `DEEPGRAM_API_KEY` *(optional)* - drop-in alternative to OpenAI Whisper for STT
  </Step>
</Steps>

## Usage

<Steps>
  <Step title="Start the server">
    ```bash theme={null}
    python server.py
    ```

    The server runs on `http://0.0.0.0:7860`.
  </Step>

  <Step title="Start ngrok">
    In a new terminal, expose your local server:

    ```bash theme={null}
    ngrok http 7860
    ```

    Copy the ngrok URL from the output (for example, `https://abc123.ngrok-free.app`).

    <Warning>
      **Important:** Update `PUBLIC_URL` in your `.env` file with this ngrok URL, then restart the server.
    </Warning>
  </Step>

  <Step title="Make a call">
    There are two ways to trigger an outbound call - pick whichever fits your stack.

    <Tabs>
      <Tab title="Server's /start helper (easiest)">
        The repo exposes `POST /start` on the local server. It wraps the Vobiz Call API and auto-fills `answer_url` from your `PUBLIC_URL`, plus uses `VOBIZ_PHONE_NUMBER` as `from` when set.

        ```bash theme={null}
        curl -X POST http://localhost:7860/start \
          -H "Content-Type: application/json" \
          -d '{ "to": "+919148223344" }'
        ```
      </Tab>

      <Tab title="Direct Vobiz API">
        ```bash theme={null}
        curl -X POST https://api.vobiz.ai/api/v1/Account/YOUR_AUTH_ID/Call/ \
          -H "X-Auth-ID: YOUR_AUTH_ID" \
          -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{
            "from": "+918011223344",
            "to": "+919148223344",
            "answer_url": "https://your-ngrok-url.ngrok-free.app/answer",
            "answer_method": "POST"
          }'
        ```
      </Tab>
    </Tabs>

    **What happens next:**

    * Phone rings at the "to" number
    * When answered, Vobiz requests XML from your server's `/answer` endpoint
    * Server returns a WebSocket URL pointing at `/ws`
    * Audio streams bidirectionally to the Pipecat bot
    * AI assistant speaks and listens (STT → LLM → TTS)
    * Conversation is automatically recorded; MP3 fetched via `/recording-ready`
  </Step>
</Steps>

## Receiving inbound calls

Configure your Vobiz number to handle incoming calls with your Pipecat agent.

<Steps>
  <Step title="Open Applications">
    Log in to the Vobiz Console and navigate to the **Applications** section in the sidebar.

    <img className="block w-full rounded-xl border border-gray-200 my-4 shadow-sm" src="https://mintcdn.com/vobizai/OZ7y9Kg025aXyvCH/images/pipecat/image1.png?fit=max&auto=format&n=OZ7y9Kg025aXyvCH&q=85&s=bebde1c06f39cbd1c4897de25e604f84" alt="Open Applications" width="413" height="236" data-path="images/pipecat/image1.png" />
  </Step>

  <Step title="Create an application">
    Click **Create New Application** and give it a name (for example, "Pipecat Agent").

    <img className="block w-full rounded-xl border border-gray-200 my-4 shadow-sm" src="https://mintcdn.com/vobizai/OZ7y9Kg025aXyvCH/images/pipecat/image2.png?fit=max&auto=format&n=OZ7y9Kg025aXyvCH&q=85&s=09e88aae040f0fda432ac1d5acb60c67" alt="Create an application" width="884" height="716" data-path="images/pipecat/image2.png" />
  </Step>

  <Step title="Configure URLs">
    Set the **Answer URL** to your ngrok URL (for example, `https://.../answer`) and select `POST` method. You can use the same URL for Hangup or leave it blank.

    <img className="block w-full rounded-xl border border-gray-200 my-4 shadow-sm" src="https://mintcdn.com/vobizai/OZ7y9Kg025aXyvCH/images/pipecat/image3.png?fit=max&auto=format&n=OZ7y9Kg025aXyvCH&q=85&s=b9079fffd97a49493326df0835d25ac5" alt="Configure the Answer URL" width="192" height="81" data-path="images/pipecat/image3.png" />
  </Step>

  <Step title="Assign phone number">
    Go to **Phone Numbers**, select your number, and assign it to the application you just created.

    <img className="block w-full rounded-xl border border-gray-200 my-4 shadow-sm" src="https://mintcdn.com/vobizai/OZ7y9Kg025aXyvCH/images/pipecat/image4.png?fit=max&auto=format&n=OZ7y9Kg025aXyvCH&q=85&s=0a9dcd9879635f8752398ee00bc5da1f" alt="Attach your phone number" width="1684" height="203" data-path="images/pipecat/image4.png" />
  </Step>
</Steps>

<Check>
  **Success:** Calls to your Vobiz number will now be handled by your local Pipecat server!
</Check>

## Quick reference

### Server endpoints

| Endpoint              | Method    | Description                                                                                     |
| --------------------- | --------- | ----------------------------------------------------------------------------------------------- |
| `/start`              | POST      | Trigger an outbound call. Body: `{ "to": "+91..." }`. Wraps the Vobiz Call API.                 |
| `/answer`             | POST      | Called by Vobiz when the call is answered. Returns XML pointing at `/ws`.                       |
| `/ws`                 | WebSocket | Bidirectional audio between Vobiz and the Pipecat bot.                                          |
| `/recording-finished` | POST      | Vobiz callback when recording stops. Logs metadata.                                             |
| `/recording-ready`    | POST      | Vobiz callback when the recording is ready. Auto-downloads the MP3 via `download_recording.py`. |

### Project files

| File                    | Purpose                                                                    |
| ----------------------- | -------------------------------------------------------------------------- |
| `server.py`             | FastAPI app - owns `/start`, `/answer`, `/ws`, and the recording callbacks |
| `bot.py`                | Pipecat pipeline - STT → LLM → TTS, runs per call                          |
| `download_recording.py` | Helper used by `/recording-ready` to pull the MP3 from Vobiz               |
| `requirements.txt`      | Python dependencies (FastAPI, Pipecat, OpenAI SDK, etc.)                   |
| `env.example`           | Template for your `.env` file - copy and fill in                           |

## Customizing the bot

Edit `bot.py` to customize your AI assistant:

```python Change Bot Personality theme={null}
messages = [
    {
        "role": "system",
        "content": "You are a friendly customer service agent..."
    },
]
```

```python Change TTS Voice theme={null}
tts = OpenAITTSService(
    api_key=os.getenv("OPENAI_API_KEY"),
    voice="nova",  # Options: alloy, echo, fable, onyx, nova, shimmer
)
```

<Check>
  **Integration complete!**

  You can now make AI-powered phone calls with Vobiz and Pipecat.
</Check>

## Next steps

* Customize your AI assistant's personality in `bot.py`
* Deploy to production (AWS/GCP/Heroku) instead of ngrok
* Add custom business logic and integrations

## Resources

**Vobiz Documentation**

* [API Documentation](/account)
* [Make a Call](/call/make-call)
* [Vobiz Console](https://console.vobiz.ai)

**External Resources**

* [GitHub Repository](https://github.com/vobiz-ai/Vobiz-X-Pipecat)
* [Pipecat Documentation](https://docs.pipecat.ai)

## Build it with an AI agent

<Prompt description="Clone, configure, and run the Vobiz-X-Pipecat repo - your first AI voice agent in ~5 minutes." icon="robot" actions={["copy", "cursor"]}>
  Using the Vobiz MCP at `https://docs.vobiz.ai/mcp`:

  1. Read the `vobiz-ai-voice-agents` skill from `mintlify://skills/ai-voice-agents` and the `vobiz-audio-streams` skill from `mintlify://skills/audio-streams`.
  2. Clone `https://github.com/vobiz-ai/Vobiz-X-Pipecat` into the current directory.
  3. Run `pip install -r requirements.txt` (warn me first if I'm not in a virtualenv).
  4. Copy `env.example` to `.env` and ask me for: `OPENAI_API_KEY`, `VOBIZ_AUTH_ID`, `VOBIZ_AUTH_TOKEN`, my Vobiz number for `VOBIZ_PHONE_NUMBER`. Leave `PUBLIC_URL` and `DEEPGRAM_API_KEY` blank for now.
  5. Explain how to start the FastAPI server (`python server.py`) and how to expose it with `ngrok http 7860`. Tell me to paste the ngrok HTTPS URL into `PUBLIC_URL` and restart.
  6. Show me the curl to fire my first AI-powered call via the local `/start` endpoint: `POST http://localhost:7860/start` with body `{"to": "+91..."}`.
  7. Explain the call flow: Vobiz → `/answer` → returns XML pointing at `/ws` → bidirectional audio → Pipecat pipeline (STT → LLM → TTS) → MP3 recording delivered to `/recording-ready`.
</Prompt>