> ## 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.

# Voiceflow telephony integration

> Voiceflow telephony connects a Voice agent to a number provisioned through Voiceflow or to your existing phone system over hosted SIP.

## Overview

Voiceflow telephony connects a Voice agent to a number provisioned through Voiceflow or to your existing phone system over hosted SIP. Use it to answer support calls, make an agreed callback and transfer a caller to a separate support destination.

- [Get a phone number](#getting-a-number) through Voiceflow and assign its agent/release.
- [Connect a SIP system](#connecting-sip) while retaining your existing numbers and phone-system routing.
- [Receive customer calls](#inbound-calls), [place an outbound call](#outbound-calls) or [transfer the caller](#transferring-calls).
- [Maintain the connection](#managing-connections) as names, credentials and customer routes change.

| Connection | Choose it when |
| --- | --- |
| Voiceflow number | You need a new public US or Canadian phone number through Voiceflow. |
| Voiceflow SIP | You already have a phone system and need inbound authentication plus one optional outbound trunk. |
| Bring your own SIP | You need independent call directions, optional outbound digest authentication or multiple outbound gateways. |

#### Studio

Start from a Voice project's **Phone numbers**. Number provisioning uses the workspace allowance; SIP requires the phone-system administrator's addresses/routing and enabled SIP availability. Prepare the agent's speech, instructions and approved Knowledge before testing the live route.

Voiceflow phone numbers and a hosted SIP connection with saved release assignments — Choose the number or SIP connection that routes calls to your agent.

#### Developer

Use the management API/CLI to provision and assign a Voiceflow number. Create SIP connections in Studio before using their calling API. A management bearer credential authorizes number resources; a runtime API key authorizes the assigned project's calls. SIP digest credentials authenticate a phone-system peer and do not replace either HTTP credential. Keep them server-side.

<a id="getting-a-number"></a>

## Getting a phone number

Provision and route a number through Voiceflow before testing its calls.

Studio shows **Voiceflow number** only in workspaces where number provisioning is available. You need workspace phone-management access and an available Voiceflow-number allowance for acquisition. Assigning it also requires edit access to the Voice project and an administrator able to resolve the project API key when assignment needs it. The create form shows how many numbers remain on the workspace's plan. Area-code availability can change; a selected area code does not reserve a particular sequence of digits. An existing connected number is selected through assignment rather than acquired again.

#### Studio

### 1. Open number creation

Open the Voice project's **Phone numbers**, choose **Create number**, then **Voiceflow number**. If you are managing an unassigned workspace number, start from the workspace's **Phone numbers** page instead.

### 2. Choose the area code and name

Open **Area code**, search for an available US or Canadian three-digit area code and select it. The selected entry determines the country. Enter an optional **Name** for your team; callers do not see this label.

Voiceflow number creation form with US area code 415 and a support-line name — Choose an available area code; Voiceflow selects the final number.

### 3. Create and inspect the number

Choose **Create**. Record the returned number and confirm it appears in the workspace. When creating from an agent, inspect its resulting assignment. A number created at workspace level still needs an agent before it can answer.

#### Developer

Use a Voiceflow management bearer credential with workspace phone-number creation and project assignment access. Set `VF_TOKEN`, `WORKSPACE_ID`, `PROJECT_ID` and `ENVIRONMENT` to the authorized credential, workspace, Voice project and test Environment alias. These are separate from the project's runtime API key used for outbound calls.

Prepare an illustrative request for a US 415 number. This operation acquires a number and consumes workspace allowance; only run it when you intend to provision one.

```sh
jq -n --arg workspace "$WORKSPACE_ID" \
  '{workspaceID:$workspace,name:"Northstar support line",provider:"voiceflow-telnyx",country:"US",areaCode:415}' \
  > voiceflow-number-create.json
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  'https://realtime-api.voiceflow.com/v1/stable/phone-number' \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @voiceflow-number-create.json > voiceflow-number-result.json
```

#### CLI

Export `VF_TOKEN` for the [Voiceflow CLI](/docs/cli/overview), then submit the same body:

```sh
vf phone-number create --output-format json \
  < voiceflow-number-create.json > voiceflow-number-result.json
```

Retain the Voiceflow resource ID, which is different from the public phone number:

```sh
PHONE_NUMBER_ID=$(jq -er '.phoneNumber.id' voiceflow-number-result.json)
```

Creation returns an unassigned number. Complete [Routing calls](#routing-calls) before testing it. The [create-number contract](/docs/api-reference/phone-number/create-phone-number) owns the complete schema and errors. Number creation is refused for MCP clients; use Studio, REST or CLI.

<a id="routing-calls" />

### Assign the answering release

The number and agent must belong to the same workspace. A fixed Environment/version answers from that release. **All environments** follows the project's traffic split on its Published versions; it does not select the Draft currently open in Studio.

#### Studio

Open the target Voice project's **Phone numbers**. Use **Assign existing number** for a workspace number not yet attached to this agent, and confirm any reassignment from another agent. Open its **Environment**, select the test Environment and **Draft**, then **Save**.

Update environment dialog with Main and Draft selected for a Voiceflow number — Pin a Draft route before testing a newly assigned number.

Check the saved Environment/version in the table. Selecting a different agent changes who answers; selecting another Environment changes the configured release of that agent.

#### Developer

Use the `PHONE_NUMBER_ID` from creation, or find it with `vf phone-number list --workspace-id "$WORKSPACE_ID" --output-format json`. Assign the Voice project and pin the test alias explicitly:

```sh
vf phone-number assign --phone-number-id "$PHONE_NUMBER_ID" --workspace-id "$WORKSPACE_ID" \
  --target voice --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --version-param draft --output-format json
vf phone-number get --phone-number-id "$PHONE_NUMBER_ID" --workspace-id "$WORKSPACE_ID" --output-format json
```

Confirm the returned `phoneNumber.voice` contains the intended project, alias and `draft`. Omitting the Environment alias clears a prior pin and follows traffic splitting. The [assignment API](/docs/api-reference/phone-number/assign-phone-number) provides the equivalent REST operation.

### The requested number cannot be created

Check the workspace allowance and available area code before trying again.

If **Voiceflow number** is absent from Create number, confirm provisioning availability with your workspace administrator or Voiceflow support. You can also [connect an existing provider number or phone system](/docs/guides/integrations/phone-messaging#choose-your-connection). If Studio shows **No free Voiceflow numbers left**, inspect the included allowance and existing numbers. The form's **Add more** action is available only to users allowed to upgrade. If an area code is unavailable or provisioning reports no available numbers, choose another supported area code. After a timeout, inspect the workspace list before submitting another acquisition request.

### Routing best practices

Make test and customer release changes independently observable.

- Keep a dedicated test number pinned to Draft so customer traffic does not move when you edit the agent.
- Read the saved assignment after a change. Publishing an Environment does not move a number already pinned to Draft.
- Name numbers for their purpose and team so an administrator can distinguish test and customer routes before reassigning them.

<a id="connecting-sip"></a>

## Connecting a SIP system

Create and authenticate a hosted route for your existing phone system.

Create SIP connections in **Phone numbers** in [Agent studio](https://creator.voiceflow.com), including when your backend will place calls. The stable phone-number API does not create SIP connections. You need workspace phone-management permission, SIP enabled for the workspace, an available SIP connection allowance and an administrator who controls the phone system.

Your phone system keeps its public numbers. Voiceflow creates a unique hosted SIP hostname and assigns one agent/release to that connection. Different dialled numbers on the same connection do not select different agents. Review the canonical [network and media requirements](/docs/api-reference/agent-runtime/voice/sip/settings#network-and-media) with the administrator before routing traffic.

### Choose and create the SIP connection

#### Voiceflow SIP

### 1. Choose Voiceflow SIP

Open **Phone numbers → Create number → SIP → Voiceflow SIP** and enter a recognizable **Name**.

### 2. Authenticate the sending phone system

Choose **IPs**, **Credentials** or **Both**. Enter the sender's public IPv4 addresses/CIDR ranges for IP authentication, or the username and password the sender will supply for digest authentication. Both requires both identities to match. Use the provider's public egress address, including NAT, rather than a private LAN address.

Voiceflow SIP inbound IP and digest authentication — Authenticate the system sending calls to the hosted SIP address.

### 3. Enable outbound routing when needed

For callbacks or transfers through the phone system, enable **Outbound calls and transfers**. Enter one **Address**, **Username**, **Password** and E.164 **Caller ID**. When outbound is enabled, all four are required. Select **Protocol** and an optional **Port**. Use the outbound settings below to check the transport before calling.

Whether you enabled outbound or only need inbound calls, choose **Create** after completing the enabled settings.

#### Bring your own SIP

### 1. Choose the directions

Open **Phone numbers → Create number → SIP → Bring your own SIP**. Enter a **Name** and enable **Inbound calls**, **Outbound calls and transfers**, or both. At least one direction must stay enabled. An outbound-only connection needs no inbound IP rows.

### 2. Configure each enabled direction

For inbound, choose **IPs**, **Credentials** or **Both**, and supply the sending system's public IPv4 sources and/or digest credentials. For outbound, add the destination **Address**, **Port** and **Protocol** rows in failover order, and an E.164 **Caller ID**. Enter outbound **Username** and **Password** together only when the peer requires digest authentication; otherwise configure the peer's source-IP allowlist. The connection allows ten addresses total across inbound and outbound rows.

Bring your own SIP directional authentication settings — Configure the directions your phone system will use.

### 3. Create the connection

Choose **Create**. Retain the resulting SIP hostname and inspect the saved directions. Use the [Bring your own SIP setup](/docs/api-reference/agent-runtime/voice/sip/bring-your-own) for gateway failover and direction-specific maintenance.

### Check transport, encryption and assignment

An outbound Address is a public IPv4 address or hostname without `sip:`, a path or an embedded port. Empty **Port** uses `5060` for UDP/TCP or `5061` for TLS. Outbound credentials authenticate Voiceflow to your peer; inbound credentials authenticate the peer to Voiceflow.

**Encrypted audio (SRTP)** requires matching peer support. Enabling it locks outbound routing to TLS; inbound calls must use TLS on `5061` with SRTP. TLS alone does not prove media encryption. TLS destinations need a publicly trusted certificate chain. Keep exact [network/encryption settings](/docs/api-reference/agent-runtime/voice/sip/settings#encrypted-audio) with their Developer owner.

SIP outbound trunk identity, transport and encryption settings — Set the peer route Voiceflow uses for outbound calls and transfers.

Creation from an agent's Phone numbers page assigns that agent. At workspace level, assign the Voice agent after creation. In the connection's **Environment** control, select your test Environment and **Draft**, then **Save**. Retain the complete **SIP address** for inbound routing and, for an outbound-enabled SIP connection, its connection ID from **Outbound call API → View** for API calling; these are different identifiers. **All environments** follows Published traffic-split routing.

For inbound calls, have the administrator route a controlled test number to `sip:<dialled-number>@<connection-sip-address>`, using peer SIP without `REGISTER`. A destination IP literal does not replace the hostname. Save the old route for rollback, then verify a real call using [Inbound calls](#inbound-calls).

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

## Inbound calls

Confirm that callers reach the intended agent with speech in both directions.

<a id="receiving-calls" />

Configure the agent's opening, speech and approved [Knowledge](/docs/documentation/build/querying-the-knowledge-base) before testing. Provisioning a number does not create support content or prove that the agent can answer the customer's question.

#### Studio

Prepare the Voice agent in **Agent**, use **Run** to check its conversation, then make the phone test below. Use [Build a phone support agent](/docs/guides/call-centre-automation) for the complete support-content workflow.

#### Developer

Prepare and compile the assigned Draft using [Voice configuration](/docs/guides/developers/voice/configure-voice). Keep its runtime API key on your backend. Incoming calls follow the assigned number or phone-system/SIP route; the HTTP key is for backend API calls.

### 1. Call from a separate phone

Dial the provisioned number or the controlled phone-system number routed to this SIP connection. Confirm the intended greeting, a relevant answer and speech in both directions. Browser Run checks the agent conversation separately from telephone routing.

### 2. Inspect the matching conversation

Find the call in [Transcripts](/docs/documentation/measure/transcripts). Check the time, caller and agent response against the test. A Transcript does not by itself establish that an audio recording exists; configure [call recording](/docs/documentation/build/voice) separately when needed.

### 3. Select and retest the released route

[Publish the reviewed Environment](/docs/documentation/deploy/environments/publishing). For a phone number, select **Published** in its Environment setting; in Code, repeat the number assignment with `--version-param published` (CLI) or `version:"published"` (API). For SIP, select **Published** in the connection's Studio Environment controls, including for API-driven calls. Read the saved route back and make a new call to confirm the released instructions answer.

For SIP, the phone-system route must use the complete connection hostname and the configured inbound authentication. Test through the real carrier/PBX route, not only browser Run. Check its source identity, the agent/release and two-way audio. Use [SIP troubleshooting](/docs/api-reference/agent-runtime/voice/sip/troubleshooting) to distinguish authentication, destination and media failures.

### A call reaches the wrong agent or release

Reconcile the connection, phone-system route and saved release with a fresh call.

Inspect the actual dialled number and its saved voice assignment. Check whether the number moved to another agent, remains pinned to Draft or intentionally follows a traffic split. Correct the assignment and start a new call. Editing or publishing the agent alone does not repair an incorrect route.

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

## Outbound calls

Place a callback through the assigned connection and verify the answered result.

Start an agreed callback, reminder or other customer call through the assigned Voice agent. Prepare the agent's opening and approved context, choose a separate test phone you can answer, and verify the saved Environment/version before dialing. Calling requires workspace credits and production call capacity.

| Connection | Place the call | Required caller route |
| --- | --- | --- |
| Voiceflow number | Calling API; no Studio **View** or **Test call** panel | Assigned Voiceflow number and the assigned project's runtime API key. |
| Voiceflow SIP | Studio test or SIP calling API | Assigned connection with outbound address, credentials and Caller ID configured. |
| Bring your own SIP | Studio test or SIP calling API | Assigned connection with outbound gateways and Caller ID; digest credentials when the peer requires them. |

### Place and verify one call

#### Studio

For a SIP connection, open **Phone numbers → Outbound call API → View**. In **Test call**, enter a separate E.164 phone you control, including its country code, then choose **Call**. Studio resolves the assigned project's key and compiles before sending the request; an administrator may be needed for that key access. The native **Outbound call sent** message confirms request acceptance.

Native SIP Test call panel with a separate US recipient — Test the configured SIP route against a separate phone you can answer.

Voiceflow numbers do not expose this panel. Give your backend implementer the intended number, agent, Environment and a controlled recipient, then use the API path in **Code** or [Make an outbound call](/docs/documentation/deploy/phone/outbound-calling). This is a required execution step, not an additional Studio button.

#### Developer

Set `VF_API_KEY` to a runtime API key with read/version-read authorization for the assigned project. Set `TEST_RECIPIENT` to the separate E.164 test phone. Use the connection's saved assignment; neither request selects a different project or Environment.

For a Voiceflow number, retain its `phoneNumber.id` as `PHONE_NUMBER_ID` from creation or workspace number lookup. Send a number request:

```sh
jq -n --arg to "$TEST_RECIPIENT" \
  '{to:$to,variables:{customer_name:"Alex"},amd:false}' |
curl --fail-with-body --silent --show-error \
  "https://runtime-api.voiceflow.com/v1/phone-number/$PHONE_NUMBER_ID/outbound" \
  -H "Authorization: $VF_API_KEY" -H 'Content-Type: application/json' --data-binary @-
```

`variables` values are strings. Prepare matching agent instructions/variables for the context you send. This minimal test sets `amd:false` to disable answering-machine detection; it does not assert that every provider implements detection in the same way.

For SIP, retain `SIP_CONNECTION_ID` from the connection-specific URL in Studio's **View** dialog. Send only `to`:

```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 @-
```

Voiceflow SIP requires E.164. Bring your own SIP also accepts a one-to-fifteen-digit PBX extension through this API when the peer routes it. Studio's SIP Test call input still requires an E.164 phone. The SIP endpoint accepts no `variables`, `amd`, arbitrary SIP URI or Environment override. Use the [phone calling](/docs/api-reference/agent-runtime/voice/phone-calls) and [SIP outbound](/docs/api-reference/agent-runtime/voice/sip/outbound) contracts for exact fields, detection behavior and errors.

Answer the phone, confirm the agent's identity and intended conversation, and inspect the matching [Transcript](/docs/documentation/measure/transcripts) and [call events](/docs/guides/developers/voice/call-events). The number endpoint returns empty `201`; SIP returns empty `200`. Neither returns a call ID or proves that someone answered.

For an application or CRM trigger, use the [backend calling workflow](/docs/guides/developers/voice/outbound-calls). Keep scheduling, recipient selection and calling preferences in that owning system; the calling endpoint does not create a campaign scheduler.

### A call is rejected or its result is uncertain

Check the saved route and call outcome before sending another request.

On `402`, resolve credits. On `429`, wait for available production capacity. Inspect provider errors for an invalid destination or unavailable outbound route. If a timeout leaves the result unknown, inspect the provider/call events before retrying; the first request may already have dialled. Do not assume an idempotency key or call ID was returned.

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

## Transferring calls

Connect an active caller to a separate support phone or SIP destination.

<a id="transferring-callers" />

Use the agent's **Call forward** system tool or a Workflow's **Call forward** step. Configure a support phone or SIP destination distinct from the number receiving the call, and define when the agent should transfer.

#### Studio

Open **Agent → Call forward**, enable it, choose **Phone number** or **SIP address**, and enter the support destination. Add a usage description and the transfer condition to the agent's instructions. For a fixed branch, configure the Workflow step instead.

Call forward system tool with a separate US support destination — Give the transfer a separate reachable destination and a clear trigger.

#### Developer

Configure the assigned agent's `callForwardTool` with the [Agent API](/docs/api-reference/agent/get-agent), then compile the selected Environment. The [developer transfer guide](/docs/guides/developers/voice/transfer-calls) supplies the complete read, update, compile and verification procedure. Use `addressType: "phone"` with the separate E.164 destination, or `"sip"` with the intended SIP URI; keep the current configuration before replacing it.

Place a real inbound or outbound test call through the assigned number or phone-system route with a teammate ready at the destination. Request a person, confirm the teammate receives the caller and inspect the Transcript. Prototype call forwarding is disabled, so a prototype test cannot verify the production transfer. Use [Transfer a phone call](/docs/guides/studio/voice/transfer-calls) for the complete Studio workflow.

For SIP connections, enable and configure the outbound direction before the transfer. The peer must accept SIP REFER for a SIP target and route the destination. Verify the receiving team gets the caller; acceptance alone does not prove a teammate answered. The [SIP transfer contract](/docs/api-reference/agent-runtime/voice/sip/transfers) owns URI handling and supported context headers.

<a id="managing-connections"></a>

## Managing connections

Maintain the workspace resources and coordinate changes to live call routes.

### Phone numbers

Unassigning a number removes its agent route and retains the number in the workspace. Deleting a Voiceflow number removes it from the workspace and returns it to Voiceflow's number pool; you cannot rely on recovering the same digits. Arrange replacement customer routing before retirement.

#### Studio

### 1. Rename or unassign the agent route

In the Voice project's **Phone numbers**, open the number's **…** menu. Choose **Rename** to update its internal name, or **Unassign** and confirm to remove it from the agent. Verify that the old agent no longer lists the number. Use **Assign existing number** when routing it to another Voice project.

### 2. Delete a number from the workspace

Open the workspace's **Phone numbers** page, find the exact public number and review its agent assignment. Open **… → Delete**, then confirm the deletion. Check that the number is absent from the workspace. Deleting differs from the project's Unassign action.

#### Developer

Inspect the resource before changing it:

```sh
vf phone-number list --workspace-id "$WORKSPACE_ID" --output-format json
vf phone-number get --phone-number-id "$PHONE_NUMBER_ID" --workspace-id "$WORKSPACE_ID" --output-format json
```

Use only the operation matching your intended change:

To change the internal name:

```sh
vf phone-number update --phone-number-id "$PHONE_NUMBER_ID" --workspace-id "$WORKSPACE_ID" \
  --name "Northstar customer support" --output-format json
```

To remove the voice assignment while retaining the workspace number:

```sh
vf phone-number unassign --phone-number-id "$PHONE_NUMBER_ID" --workspace-id "$WORKSPACE_ID" \
  --target voice --output-format json
```

To retire the number from the workspace when it is no longer needed:

```sh
vf phone-number delete --phone-number-id "$PHONE_NUMBER_ID" --workspace-id "$WORKSPACE_ID" --output-format json
```

After renaming or unassigning, read the resource again; after deletion, confirm its absence from the workspace list. The [number-management APIs](/docs/api-reference/phone-number/get-phone-number) provide the equivalent REST operations. Only the name is editable through the update operation; the provider and number are fixed.

### SIP connections

<a id="change-or-remove-the-connection" />
<a id="editing-or-deleting-a-sip-connection" />

Maintain SIP connections in Studio, including those your backend calls through the API. The stable number-management endpoints operate on phone numbers, not these SIP records.

### 1. Update names, credentials or outbound routing

Open the connection in **Phone numbers**, then open the relevant setting. Changes save automatically. A blank existing-password field keeps the stored password; enter a replacement to rotate it and coordinate the matching peer change with the phone-system administrator. Turning outbound off clears its saved destination and credentials, so retain the configuration before changing the direction.

### 2. Change or remove its agent assignment

Use the connection's assignment and Environment controls to select the intended agent/release. Use **Unassign** in the agent's connection menu to remove its answering route while retaining the workspace connection. Retest any route that should continue serving customers.

### 3. Retire the workspace connection

Have the phone-system administrator remove or replace routes pointing to its SIP hostname. In the workspace's **Phone numbers**, select the connection's **Delete** action and confirm only after reviewing its name, address and assignment. This removes the connection, not the phone numbers held by your carrier. Confirm it is absent and that customer calls follow the replacement route.

Use the canonical [connection maintenance reference](/docs/api-reference/agent-runtime/voice/sip/settings#editing-and-removing-connections) for removal behavior and [SIP troubleshooting](/docs/api-reference/agent-runtime/voice/sip/troubleshooting) when a saved change fails its call test. Provider-specific contact-centre queues, authentication and mappings remain in the relevant [Contact Center manual](/docs/guides/integrations/contact-centers).
