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

# Phone Calling

Connect Vision Agents to PSTN phone calls. A telephony provider handles the phone network; your FastAPI server receives webhooks, streams audio over WebSocket, and bridges it into a Stream call where your agent runs.

<Info>
  Vision Agents uses [Stream Video](https://getstream.io/video/) for real-time WebRTC transport by default. [External WebRTC transports](/integrations/introduction-to-integrations#edge-transport) are supported as well. Most AI providers offer free tiers to get started.
</Info>

## Choose a provider

<CardGroup cols={2}>
  <Card title="Twilio" icon="phone" href="/integrations/telephony/twilio">
    Media Streams, TwiML, built-in webhook helpers — default in our examples
  </Card>

  <Card title="Telnyx" icon="phone" href="/integrations/telephony/telnyx">
    Call Control API, bidirectional media streaming
  </Card>
</CardGroup>

## How phone agents work

Every phone integration follows the same pattern, regardless of provider:

1. **Webhook** — the provider notifies your server of an incoming call (or you initiate an outbound call via REST API)
2. **Register** — create a call entry in a provider registry with a secret token
3. **Stream URL** — tell the provider to open a WebSocket media stream to your server
4. **Bridge** — `attach_phone_to_call` connects phone audio ↔ a Stream call where your agent listens and responds

```mermaid theme={null}
flowchart LR
    subgraph twilio [Twilio]
        T1[Voice webhook] --> T2[TwiML Connect Stream]
        T2 --> T3[Media Streams WS]
    end
    subgraph telnyx [Telnyx]
        X1[Call Control webhook] --> X2[Answer or Dial API]
        X2 --> X3[Media Streaming WS]
    end
    T3 --> Bridge[attach_phone_to_call]
    X3 --> Bridge
    Bridge --> Stream[Stream call plus Agent]
```

## Shared building blocks

Both telephony plugins expose the same core primitives:

| Building block         | Role                                                                               |
| ---------------------- | ---------------------------------------------------------------------------------- |
| Call registry          | Tracks active calls, assigns tokens, optional async `prepare` to warm up the agent |
| Media stream           | WebSocket handler that receives/sends phone audio                                  |
| `attach_phone_to_call` | Bridges provider audio ↔ Stream WebRTC participant                                 |
| Tokenized media URL    | Provider connects to `wss://<host>/<provider>/media/{call_id}/{token}`             |

Provider-specific differences:

|                  | Twilio                               | Telnyx                                         |
| ---------------- | ------------------------------------ | ---------------------------------------------- |
| Answer mechanism | Return TwiML with `<Stream>`         | Call Control Answer/Dial API with `stream_url` |
| Webhook auth     | `verify_twilio_signature` (built-in) | Ed25519 verification (see plugin examples)     |
| Audio encoding   | mulaw 8 kHz                          | PCMU/PCMA 8 kHz or L16 16 kHz                  |

## Prerequisites

Before starting any phone example:

* [Stream](https://getstream.io/try-for-free/) API key and secret
* A telephony provider account with at least one phone number
* [ngrok](https://ngrok.com/) (or another HTTPS tunnel) for local development
* A public webhook URL pointing at your FastAPI server

<Tip>
  **Prefer managed hosting?** [Stream Voice AI](https://getstream.io/video/voice-ai/) runs production voice agents on Stream's global edge, phone numbers, web and mobile clients, co-located STT/LLM/TTS, and built-in observability. [Join the waitlist](https://getstream.io/video/voice-ai/) for early access.
</Tip>

## Learning path

Follow this order:

1. **[Twilio Phone Agent](/examples/twilio-phone-agent)** — get your first inbound and outbound call working
2. **[Phone Support Agent (RAG)](/examples/phone-and-rag)** — add knowledge retrieval on top
3. **[Twilio](/integrations/telephony/twilio)** or **[Telnyx](/integrations/telephony/telnyx)** integration pages — API reference when building your own server

<CardGroup cols={2}>
  <Card title="Twilio Phone Agent" icon="phone" href="/examples/twilio-phone-agent">
    Step-by-step phone tutorial
  </Card>

  <Card title="Phone Support Agent (RAG)" icon="book" href="/examples/phone-and-rag">
    Add knowledge retrieval to calls
  </Card>
</CardGroup>

## Quick orientation

<Steps>
  <Step title="Expose your local server" icon="globe">
    Run `ngrok http 8000` and note the HTTPS hostname for `NGROK_URL`.
  </Step>

  <Step title="Point webhooks at your server" icon="link">
    Configure your provider to send call events to your FastAPI endpoints (e.g. `https://<NGROK_URL>/twilio/voice` for Twilio).
  </Step>

  <Step title="Run an example and call your number" icon="microphone">
    Follow the [Twilio Phone Agent](/examples/twilio-phone-agent) tutorial for full commands. Dial your Twilio number to verify end-to-end audio.
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Twilio Integration" icon="plug" href="/integrations/telephony/twilio">
    Plugin API reference
  </Card>

  <Card title="Telnyx Integration" icon="plug" href="/integrations/telephony/telnyx">
    Alternative provider
  </Card>

  <Card title="RAG for Agents" icon="magnifying-glass" href="/guides/rag">
    Knowledge retrieval backends
  </Card>

  <Card title="Stream Video RTC" icon="signal-stream" href="/integrations/edge-transport/getstream">
    Default edge transport
  </Card>

  <Card title="Build a Voice Agent" icon="microphone" href="/introduction/voice-agents">
    Voice agent fundamentals
  </Card>
</CardGroup>