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

# Connect External Phone Numbers to Plivo

> Route calls from phone numbers you can't port to Plivo applications using DID forwarding or direct SIP

If you have a phone number with another provider that you can't port to Plivo, you can still use it with Plivo applications (XML apps, Audio Streaming, AI voice agents). This guide covers two ways to do it.

***

## How It Works

<Steps>
  <Step title="Caller dials your external number">
    The call lands at your existing provider (the carrier where your number lives).
  </Step>

  <Step title="Provider routes the call to Plivo">
    Either as a forwarded call to a Plivo phone number (Option 1), or as a direct SIP INVITE to your Plivo application's SIP URI (Option 2).
  </Step>

  <Step title="Plivo authenticates (Option 2 only)">
    For direct SIP, Plivo verifies the incoming call against your IP ACL or SIP credentials before accepting it.
  </Step>

  <Step title="Plivo executes your Application">
    The call hits your XML application's Answer URL. Your server returns XML instructions (e.g., `<Stream>` to connect to a WebSocket-based AI agent).
  </Step>

  <Step title="Conversation continues">
    Audio flows in real-time between the caller and your application via Plivo's voice infrastructure.
  </Step>
</Steps>

***

## Two Options

| Option                       | What It Does                                                       | Best For                                        |
| ---------------------------- | ------------------------------------------------------------------ | ----------------------------------------------- |
| **DID forwarding**           | Your provider forwards calls from your number to a Plivo number    | Quick setup, no SIP knowledge required          |
| **Direct SIP** (recommended) | Your provider sends SIP traffic directly to your Plivo application | Lower cost, lower latency, fewer failure points |

***

## When to Use This

* You have phone numbers with carriers that don't support porting
* You have geographic numbers (e.g., specific countries) where Plivo doesn't offer numbers
* You have toll-free or vanity numbers you've owned for years and can't move
* You want to connect existing PBX or contact center extensions to Plivo AI agents
* You're testing AI voice agents on existing numbers without committing to porting

***

## Option 1: DID Forwarding

The simplest approach. Configure your existing provider to forward all incoming calls to a Plivo phone number.

```text theme={null}
Caller dials your external number
   |
   v
Your Provider (Provider X)
   |
   v  [forward leg, outbound from Provider X]
Your Plivo Number (inbound)
   |
   v
Plivo XML App -> Answer URL -> WebSocket / AI Agent
```

### Setup

<Steps>
  <Step title="Buy a Plivo number">
    [Purchase a voice-enabled Plivo number](https://cx.plivo.com/phone-numbers) and assign it to your XML application.
  </Step>

  <Step title="Configure forwarding in your provider">
    In your existing provider's dashboard, set up call forwarding to route inbound calls to your Plivo number. The exact steps depend on your provider — look for "call forwarding", "auto-forward", or "external destination" settings.
  </Step>

  <Step title="Test">
    Call your external number. It should ring through to your Plivo number, hit your XML app's Answer URL, and trigger your voice agent.
  </Step>
</Steps>

### Trade-offs

* **Pros:** Quick to set up, works with any provider that supports forwarding, no SIP knowledge needed
* **Cons:** Three call legs (caller → provider, provider → Plivo number outbound, Plivo number inbound). Higher cost and latency.

***

## Option 2: Direct SIP (Recommended)

Configure your existing provider to send SIP traffic directly to your Plivo XML application's SIP URI. Use [SIP Authentication](/voice/concepts/sip-authentication/) to secure the inbound stream.

<Warning>
  **Request-URI requirement:** For inbound SIP authentication to apply, the Request-URI of the INVITE must be `sip:{app_id}@app.plivo.com`. Plivo resolves the application from the Request-URI user part, not from the To header. If your SIP provider places a phone number in the Request-URI, configure the provider to send INVITEs to the application's SIP URI instead. Without this, calls bypass authentication silently.
</Warning>

```text theme={null}
Caller dials your external number
   |
   v
Your Provider (Provider X)
   |
   v  [SIP INVITE to sip:{app_id}@app.plivo.com]
Plivo SIP Auth check (IP ACL or credentials)
   |
   v
Plivo XML App -> Answer URL -> WebSocket / AI Agent
```

### Why Direct SIP Is Recommended

* **Lower cost** — single Plivo SIP termination charge instead of provider forwarding + Plivo inbound
* **Lower latency** — eliminates the extra forwarding hop
* **Better quality** — fewer transcoding steps means cleaner audio
* **Fewer failure points** — fewer legs means fewer things that can go wrong

### Setup

<Steps>
  <Step title="Find your Plivo application's SIP URI">
    Every Plivo application has a SIP URI in the format:

    ```
    sip:{app_id}@app.plivo.com
    ```

    Find your `app_id` in the [Plivo Console](https://cx.plivo.com/home) under **Voice > Applications**, or via the [Application API](/account/api/application/).
  </Step>

  <Step title="Create SIP authentication">
    Choose one auth method:

    **Option A: IP ACL** (recommended if your provider has stable outbound IPs)

    ```bash theme={null}
    # Create the IP ACL
    curl -X POST "https://api.plivo.com/v1/Account/<auth_id>/SipAuth/IpAccessControlList/" \
      -u "<auth_id>:<auth_token>" \
      -H "Content-Type: application/json" \
      -d '{"name": "External Provider"}'
    # Response: {"ip_acl_uuid": "acl-abc123"}

    # Add your provider's outbound SIP IP
    curl -X POST "https://api.plivo.com/v1/Account/<auth_id>/SipAuth/IpAccessControlList/acl-abc123/Entry/" \
      -u "<auth_id>:<auth_token>" \
      -H "Content-Type: application/json" \
      -d '{"ip": "203.0.113.10", "cidr_prefix": 32, "description": "Provider X SIP outbound"}'
    ```

    **Option B: SIP digest credentials** (use if your provider's IPs change)

    ```bash theme={null}
    curl -X POST "https://api.plivo.com/v1/Account/<auth_id>/SipAuth/Credential/" \
      -u "<auth_id>:<auth_token>" \
      -H "Content-Type: application/json" \
      -d '{"username": "external-provider", "password": "<your_password>"}'
    # Response: {"credential_uuid": "cred-def456"}
    ```
  </Step>

  <Step title="Assign auth to your Plivo application">
    Update your application to require SIP authentication:

    ```bash theme={null}
    # For IP ACL
    curl -X POST "https://api.plivo.com/v1/Account/<auth_id>/Application/<app_id>/" \
      -u "<auth_id>:<auth_token>" \
      -H "Content-Type: application/json" \
      -d '{
        "sip_auth_type": "ip_acl",
        "ip_acl_uuid": "acl-abc123"
      }'
    ```
  </Step>

  <Step title="Configure your external provider">
    In your existing provider's dashboard, configure inbound calls to your number to forward via SIP to:

    ```
    sip:{app_id}@app.plivo.com
    ```

    Look for "SIP termination", "SIP forwarding", or "external SIP destination" settings.

    If you're using credentials, configure your provider with the username and password you created in Step 2.
  </Step>

  <Step title="Test">
    Call your external number. The call should hit your provider, route as a SIP INVITE to `sip:{app_id}@app.plivo.com`, pass Plivo's auth check, and trigger your XML application.

    Check the Plivo Console under **Voice > Logs > Calls** to verify routing.
  </Step>
</Steps>

### Connecting to AI Voice Agents

Once your external number routes to a Plivo Application via SIP, your Answer URL can return the `<Stream>` XML element to connect to a WebSocket-based AI voice agent (Pipecat, LiveKit Agents, or your own framework).

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Speak>Connecting you to our AI assistant.</Speak>
    <Stream bidirectional="true" keepCallAlive="true"
        contentType="audio/x-mulaw;rate=8000">
        wss://your-server.com/stream
    </Stream>
</Response>
```

For full AI voice agent setup, see [Build with Audio Streaming](/voice-agents/audio-streaming/overview/).

***

## Cost & Latency Comparison

For a typical 5-minute inbound call:

| Approach           | Legs                                                                          | Cost Components                                       |
| ------------------ | ----------------------------------------------------------------------------- | ----------------------------------------------------- |
| **DID forwarding** | 3 (caller → provider, provider → Plivo number outbound, Plivo number inbound) | Provider's outbound forward rate + Plivo inbound rate |
| **Direct SIP**     | 1 (caller → Plivo via SIP)                                                    | Plivo's SIP termination rate only                     |

Direct SIP typically eliminates 50-70% of the per-minute cost and shaves 100-300ms of latency.

***

## Verify It's Working

After setup, make a test call and check your `answer_url` callback for these parameters:

| Parameter     | What It Confirms                                                          |
| ------------- | ------------------------------------------------------------------------- |
| `SIPAuthType` | Auth method that ran (`ip_acl`, `credential`, or `ip_acl_and_credential`) |
| `SIPAuthUser` | The authenticated username (credential auth only)                         |
| `SIPSourceIP` | The caller's source IP                                                    |

If `SIPAuthType` is missing from the callback, auth is not running — the most common cause is the provider placing a phone number in the Request-URI instead of your app\_id.

***

## Security (Direct SIP)

* **Always use SIP Authentication** — leaving an XML app's SIP URI open invites toll fraud and abuse
* **Prefer IP ACL when possible** — if your provider has stable outbound IPs, IP ACL is faster (no challenge/response handshake) and harder to abuse
* **Use credentials when IPs are dynamic** — if your provider rotates IPs, use SIP digest credentials with a strong password
* **Beware of shared IPs** — if your provider is on carrier-grade NAT or a shared-IP platform, IP ACL alone is not sufficient. Use `ip_acl_and_credential` for defense in depth.
* **Combine both for maximum security** — set `sip_auth_type` to `ip_acl_and_credential` to require both checks
* **Rate limiting is automatic** — 10 failed auth attempts from the same IP triggers a lockout. Updating the IP ACL to include the locked-out IP does NOT clear an active lockout. See [SIP Authentication](/voice/concepts/sip-authentication/) for details.

***

## Troubleshooting

| Issue                                          | Solution                                                                                                                                                    |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| All calls get 403 Forbidden                    | Verify your provider's outbound SIP IP matches an entry in your IP ACL, or that the credentials match exactly                                               |
| Calls succeed but no `SIPAuthType` in callback | Your provider is placing a phone number in the Request-URI instead of your app\_id. Configure the provider to send INVITEs to `sip:{app_id}@app.plivo.com`. |
| Call rejected with 407 (then drops)            | Your provider isn't responding to the digest challenge. Configure the SIP credentials in your provider's setup.                                             |
| Auth passes but no XML executes                | Check that the Application has a valid `answer_url` configured, and that your server returns valid XML                                                      |
| Calls work intermittently                      | Your provider may be rotating outbound IPs. Switch to credential auth, or expand your IP ACL CIDR range                                                     |

***

## Full API Reference

* [SIP Authentication API](/account/api/sip-authentication/) — Create and manage SIP credentials and IP Access Control Lists
* [Application API](/account/api/application/) — Configure `sip_auth_type`, `credential_uuid`, `ip_acl_uuid` on your Plivo application
* [Voice Call API](/voice/api/calls/) — Make outbound calls and retrieve call logs

## Related

* [Transfer to Human Agent](/voice/use-cases/transfer-to-human-agent/) — Route AI-handled calls to a human agent
* [SIP Authentication](/voice/concepts/sip-authentication/) — Full concept guide for IP ACL and credential auth
* [Build with Audio Streaming](/voice-agents/audio-streaming/overview/) — Connect external numbers to AI voice agents