> ## 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 your agents to phone calls via Twilio. Supports both inbound (receive calls) and outbound (make calls).

<Info>
  Vision Agents requires a [Stream](https://getstream.io/try-for-free/) account for real-time transport.
</Info>

## Prerequisites

1. [Twilio account](https://www.twilio.com/) with a phone number
2. [ngrok](https://ngrok.com/) for local development (exposes your server to Twilio)
3. Stream API credentials

## Installation

```sh theme={null}
uv add vision-agents[twilio]
```

## Environment Variables

```bash theme={null}
TWILIO_ACCOUNT_SID=your_account_sid
TWILIO_AUTH_TOKEN=your_auth_token
NGROK_URL=your-ngrok-subdomain.ngrok.io  # without https://
STREAM_API_KEY=your_stream_key
STREAM_API_SECRET=your_stream_secret
```

## Inbound Calls

Twilio sends a webhook when someone calls your number. Validate the request, create a call registry entry, and return TwiML to start the media stream.

```python theme={null}
@app.post("/twilio/voice")
async def voice_webhook(
    _: None = Depends(twilio.verify_twilio_signature),
    data: twilio.CallWebhookInput = Depends(twilio.CallWebhookInput.as_form),
):
    twilio_call = call_registry.create(call_id, data, prepare=prepare_call)
    url = f"wss://{NGROK_URL}/twilio/media/{call_id}/{twilio_call.token}"
    return twilio.create_media_stream_response(url)
```

Configure your Twilio phone number webhook to `https://your-ngrok-url/twilio/voice`.

## Outbound Calls

Use the Twilio REST API to initiate calls programmatically.

```python theme={null}
from twilio.rest import Client

twilio_client = Client(TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN)
twilio_client.calls.create(
    twiml=twilio.create_media_stream_twiml(url),
    to=to_number,
    from_=from_number,
)
```

## Key Components

| Component                      | Description                               |
| ------------------------------ | ----------------------------------------- |
| `TwilioCallRegistry`           | Manages pending calls and tokens          |
| `TwilioMediaStream`            | Handles WebSocket audio from Twilio       |
| `attach_phone_to_call`         | Connects phone audio to Stream call       |
| `verify_twilio_signature`      | FastAPI dependency for webhook security   |
| `create_media_stream_response` | Returns TwiML for bidirectional streaming |

## Next Steps

<CardGroup cols={2}>
  <Card title="Full Example" icon="github" href="https://github.com/GetStream/vision-agents/tree/main/examples/03_phone_and_rag_example">
    Complete phone + RAG implementation
  </Card>

  <Card title="RAG for Agents" icon="magnifying-glass" href="/guides/rag">
    Add knowledge base to phone agents
  </Card>
</CardGroup>