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

# Deploy a voice agent with Bandwidth SIP trunking

> Route a Universal Platform number to Voiceflow.

## Overview

Route an existing **Bandwidth Universal Platform** number to a Voiceflow Voice agent over SIP. This manual uses a Voice Configuration Package to send incoming calls to Voiceflow's hosted SIP hostname. For callbacks, it configures a separate Bandwidth SIP realm and digest credential. Voiceflow hosts the agent conversation and audio processing; you configure the carrier routes without building a media bridge.

**Note:** 

**Starting with Bandwidth Build?** Its [number-level SIP setup](https://dev.bandwidth.com/docs/voice/sip-trunking/sip-getting-started/) exposes routes and endpoints under **My Numbers → Voice configuration**. This walkthrough teaches Universal Platform VCP routing. Switching a Build number to SIP also disables Voice API traffic for that number. [Bandwidth SMS](/docs/guides/channels/sms/bandwidth) has a separate installation.

<a id="prepare-bandwidth"></a>

## Before you begin

Collect the trunk's actual signalling sources and the intended test release.

| Owner | Required input |
| --- | --- |
| Voiceflow builder | An editable [Voice agent](/docs/guides/studio/voice/first-phone-call), configured speech, approved answers and a recognizable test greeting. |
| Voiceflow administrator | Phone-management/project edit access, available SIP allowance and access to the project runtime key when assignment requires it. |
| Bandwidth administrator | Universal Platform SIP service, an existing voice-active number and permission to create/assign VCPs. Record its current package and inbound service settings. |
| Network administrator | Every public **standard SIP (Orig/Term)** signalling IP for this account's trunk groups, obtained from **Account → Trunk Group Configurations** or Bandwidth Support. Include both redundant sources. |
| Tester | A separate controlled phone and an unforwarded teammate number if transfers are required. |

The administrator must hand over the deployed signalling IPs and the exact number being routed before Voiceflow setup. Confirm these values against the account's trunk configuration; neither a guessed global range nor the addresses from a DNS lookup establish the incoming call source. See [Bandwidth's inbound trunk contract](https://www.bandwidth.com/support/en/articles/12822925-inbound-calling-integration-guide).

For callbacks, the account must also support SIP credentials. Ask Bandwidth to enable that service if realm creation is unavailable. Carrier SIP credentials and a Voiceflow runtime API key serve different systems.

<a id="route-inbound-calls"></a>

## Route inbound calls

Make the number's Voice Configuration Package target the assigned Voiceflow endpoint.

### 1. Create an IP-authenticated Voiceflow connection

In [Agent studio](https://creator.voiceflow.com), open the Voice project's **Phone numbers → Create number → SIP → Voiceflow SIP**. Enter a name, choose **IPs**, and add every Bandwidth signalling source supplied above as IPv4 addresses/CIDRs. Do not select **Both** unless the carrier also supplies matching digest credentials on incoming calls. Choose **Create** and copy the full **SIP address**.

Confirm the assigned agent. Open **Environment**, choose the controlled Environment and **Draft**, then **Save**. A connection created from workspace Phone numbers must be assigned separately.

### 2. Create the carrier route before moving the number

In the [Bandwidth App](https://app.bandwidth.com), open **Service Management → Voice Configuration → Create New**. Name a new package, choose **Route to Domain Name**, and enter the complete copied Voiceflow hostname. Use standard SIP over UDP on `5060` for this walkthrough. Do not replace the hostname with an IP or select a Programmable Voice application.

Use one primary endpoint with all traffic directed to it during the test. Review the saved package's origination route before changing number assignment. The [VCP guide](https://dev.bandwidth.com/docs/universal-platform/create-a-vcp/) explains package creation and number association.

### 3. Assign the test number and inspect its service

Assign only the controlled number to that VCP and confirm inbound voice is activated. Read back its effective package and destination. A package can serve several numbers, so editing an existing shared package could change other customer routes; a separate test package avoids that dependency.

The SIP request's dialled number and caller identity are distinct from the hostname selecting the Voiceflow connection. Every number routed to this connection shares its agent/release. Voiceflow manages the ongoing audio session; telephone Caller ID alone is not authenticated customer identity. Shared [SIP network and media settings](/docs/api-reference/agent-runtime/voice/sip/settings#network-and-media) own the wire contract.

<a id="outbound-and-transfers"></a>

## Configure callbacks and transfers

Authenticate outbound calls independently from inbound IP matching.

### 1. Create the outbound realm and credential

In Bandwidth **Account → SIP Credentials**, use **Manage Realms** to create a dedicated realm. Wait until it is active and retain its generated hostname. Add a username/password credential to that realm. Keep the password in your secret store and hand over the hostname, bare username and password to the Voiceflow administrator. See [Bandwidth SIP authentication](https://www.bandwidth.com/support/en/articles/12823069-sip-authentication-network-bridge-setup-and-configuration).

This is digest authentication for INVITEs, rather than SIP device registration. If Bandwidth requires source-IP approval for the account, obtain the [Voiceflow signalling egress allowlist](/docs/api-reference/agent-runtime/voice/sip/settings#network-and-media) and have the carrier administrator confirm it is accepted.

### 2. Save the outbound settings in Voiceflow

Open the SIP connection, enable **Outbound calls and transfers**, and configure:

| Voiceflow field | Value |
| --- | --- |
| Address | Bandwidth's generated realm hostname, without scheme, path or embedded port. |
| Protocol / Port | UDP / `5060` for this standard-SIP walkthrough. |
| Username / Password | The dedicated realm credential; use the bare username. |
| Caller ID | An E.164 number owned by the same Bandwidth account as the realm. |

Save and reopen the connection to check its address, caller identity and transport. Inbound signalling sources do not supply these outbound values. Do not infer TLS/SRTP capability from a different Bandwidth trunk product; coordinate any change with the carrier and the [Voiceflow encryption contract](/docs/api-reference/agent-runtime/voice/sip/settings#encrypted-audio).

### 3. Prepare one backend callback

Get `SIP_CONNECTION_ID` from this connection's **Outbound call API → View**. Obtain `VF_API_KEY`, a runtime key authorized for the assigned project's read/version-read permissions, and set `TEST_RECIPIENT` to a separate E.164 phone you can answer. Run from the backend when ready for a real call:

```sh
jq -n --arg to "$TEST_RECIPIENT" '{to:$to}' |
curl --fail-with-body --silent --show-error \
  "https://runtime-api.voiceflow.com/v1/sip-connection/$SIP_CONNECTION_ID/outbound" \
  -H "Authorization: $VF_API_KEY" -H 'Content-Type: application/json' --data-binary @-
```

HTTP `200` returns no call ID and does not prove pickup. It uses this connection's saved release. After an uncertain response, inspect carrier records before another attempt. See [SIP outbound calls](/docs/api-reference/agent-runtime/voice/sip/outbound).

### 4. Choose the support transfer path

Configure **Agent → Call forward** or a Workflow **Call forward** step with a separate support phone and a clear trigger. A phone transfer and SIP REFER use different runtime operations. Use a phone target for the first transfer test. If your deployment requires a SIP target, have the Bandwidth administrator establish REFER handling for the actual trunk product before enabling it; outbound calling alone does not establish REFER interoperability. Follow [Transfer a phone caller](/docs/guides/studio/voice/transfer-calls) and [SIP transfer behavior](/docs/api-reference/agent-runtime/voice/sip/transfers).

<a id="test-calls"></a>

## Test the caller journey

Prove that the selected carrier route carries a complete conversation.

### 1. Call through Bandwidth

Call the controlled Bandwidth number from a separate phone. Expect the assigned test release's greeting, then ask a known support question. Confirm a complete audible answer and that the agent hears you.

### 2. Continue, hang up and call again

Ask a follow-up referring to that answer. Confirm it stays in context. Hang up, check that the carrier call ended and find the matching Voiceflow [Transcript](/docs/documentation/measure/transcripts) by time and caller. Make a fresh call to verify repeat routing. Check anonymous-caller behavior separately if your service accepts withheld numbers.

### 3. Check the additional enabled directions

Place one configured callback and verify its Caller ID, intended agent and speech both ways. For transfer, request a person during a separate inbound test and confirm the teammate actually receives and can speak to the caller. End both legs and inspect their carrier records.

### Calls fail or arrive intermittently

Compare the active VCP and every deployed signalling source.

Confirm the number's inbound service and assigned VCP, then the package's full destination hostname. Check the actual SIP source against Voiceflow's allowlist, including both redundant Bandwidth SBCs. A trunk migration can change source IPs while the number remains the same. Avoid fixing an authentication failure by broadly allowing all sources.

### Audio, callbacks or transfers fail

Separate media reachability from realm and destination authorization.

Use [SIP troubleshooting](/docs/api-reference/agent-runtime/voice/sip/troubleshooting) for SDP/media and codec checks. For outbound authentication errors, compare the active realm hostname, credential and same-account Caller ID. For transfers, confirm a distinct reachable destination and inspect the carrier's failure reason. A rejected transfer may end the agent call; arrange a recoverable support route before cutover.

<a id="release-and-maintain"></a>

## Release and maintain the route

Coordinate package assignment, the released agent and future SBC changes.

### 1. Release and retest

[Publish the reviewed Environment](/docs/documentation/deploy/environments/publishing), set this connection to **Published**, and save. **All environments** uses Published traffic splits. Repeat the caller test with a fresh call before assigning approved customer numbers to the package.

### 2. Retain configuration and monitor failures

Record the number/VCP association, package destinations and priorities, all signalling sources, realm, Voiceflow hostname/ID and agent release. Keep passwords in the secret store. Review carrier call records and Transcripts after credential rotation or Bandwidth trunk maintenance, and update the inbound allowlist when confirmed sources change.

### 3. Restore or remove the route

Restore the number's recorded VCP to roll back and verify the previous service answers. Check all associated numbers before editing or deleting a shared package. Remove the carrier route before unassigning or deleting the Voiceflow connection; deleting it does not restore Bandwidth routing.
