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

# Teams Phone integration

> Connect Microsoft Teams Phone user calls to a Voiceflow agent, configure immediate forwarding and verify callbacks and teammate transfers.

## Overview

Let Voiceflow answer calls to an existing Teams Phone user's business number. Forward that user's calls to a separate, callable Voiceflow-connected number, and send callers who need a person to a different Teams Phone number your team answers.

- [Connect the business line](#connecting-teams-phone) while keeping its number with Teams Phone.
- [Receive support calls](#inbound-calls) with the assigned Voice agent and verify the complete forwarded route.
- [Make an outbound call](#outbound-calls) through the independently configured Voiceflow caller.
- [Transfer callers](#transferring-callers) to a separate teammate line, then [maintain or restore the route](#managing-routing).

This manual covers Teams Phone phone-user routing. Microsoft Teams chat/bot connections and contact-center queues have separate owners. The worked setup uses a provider user with a public number, rather than a contact-center queue.

#### Studio

Prepare the answering agent and number in [Agent studio](https://creator.voiceflow.com), then configure the user's forwarding in Teams Phone. The two systems keep separate routing and release settings.

Independent Voiceflow phone numbers and their saved agent release assignments — Choose the callable Voiceflow destination that will answer the forwarded business call.

#### Developer

Use Microsoft Teams PowerShell for the user forwarding group and Voiceflow HTTP APIs for the answering agent, caller and transfer settings. Use a Voiceflow management bearer credential for number lookup and agent configuration, and the assigned project's runtime API key for outbound calling. Keep all credentials on your backend; provider authorization is separate from Voiceflow authorization.

<a id="connecting-teams-phone"></a>

## Connecting Teams Phone

Route an existing business number to a separately tested Voiceflow destination.

### Prepare the answering number

Start with a reviewed **Voice** agent, a test Environment and a callable number already connected to that agent. [Voiceflow telephony](/docs/guides/integrations/voiceflow-telephony/overview#getting-a-number) supplies a number through Voiceflow; the [Twilio](/docs/guides/integrations/twilio/overview#connecting-twilio), [Vonage](/docs/guides/integrations/vonage/overview#connecting-vonage) and [Telnyx](/docs/guides/integrations/telnyx/overview#connecting-telnyx) manuals cover existing carrier numbers. Complete the chosen number's setup first. Teams Phone stays responsible for its existing business number.

The Northstar example uses three different resources: the business entry number **+1 206 555 0111**, the Voiceflow answering number **+1 415 555 0120**, and a teammate's unforwarded number **+1 312 555 0145**. Replace them with your actual numbers. The business entry and answering numbers must differ; forwarding the number back to itself creates a loop. Calls use the provider's PSTN service and the Voiceflow connection's credits/capacity; check both plans before a customer cutover.

#### Studio

In Agent studio, open the Voice project's **Phone numbers**. Inspect the answering number, open **Environment**, select the test Environment and **Draft**, then **Save**. Call that number directly from a separate phone. Confirm the intended opening and two-way speech before changing Teams Phone routing.

Saved Main and Draft selection for the separate Voiceflow answering number — Test the answering number's saved release before forwarding another number to it.

#### Developer

Use Bash for the curl/jq examples, and PowerShell where a block is labelled PowerShell. Obtain `VF_TOKEN` with workspace number-list access, the authorized `WORKSPACE_ID`, the Voice `PROJECT_ID` and its test `ENVIRONMENT` alias. Set `VF_NUMBER` to the already connected answering number in E.164 format. In this dedicated trusted Bash session, stop on failed requests or checks before any later write:

```sh
set -euo pipefail
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/phone-number?workspaceID=$WORKSPACE_ID" \
  -H "Authorization: Bearer $VF_TOKEN" > workspace-numbers.json

jq -e --arg number "$VF_NUMBER" --arg project "$PROJECT_ID" \
  '[.phoneNumbers[] | select(.value==$number and .voice.projectID==$project)] |
   if length==1 then .[0] else error("Expected one assigned answering number") end' \
  workspace-numbers.json > answering-number.json
PHONE_NUMBER_ID=$(jq -er '.id' answering-number.json)
jq '.voice' answering-number.json
```

Confirm the alias and version are the controlled test release. Correct them through the [number-assignment operation](/docs/api-reference/phone-number/assign-phone-number) before proceeding. A business number held by Teams Phone is not this `PHONE_NUMBER_ID`. Have the builder call the answering number directly and verify its agent before the provider administrator enables forwarding.

### Forward the Teams Phone user's calls

Use a **Teams Only** user with a Teams Phone license, a public phone number and working PSTN connectivity through the organization's chosen calling service. A Teams chat account or internal calling alone does not prepare an external phone route. Have a Teams administrator confirm the user's assigned **Voice → Calling policies** permits **Call forwarding and simultaneous ringing to external phone numbers** and the intended destination. [Microsoft's user-call settings](https://learn.microsoft.com/en-us/microsoftteams/user-call-settings) describe the controls and policy dependency.

Record the user's existing forwarding mode, enabled state and destination. Use an individual test user for this recipe; enabling a global policy or changing a resource account can affect other people and phone applications.

#### Studio

Open the [Teams admin center](https://admin.teams.microsoft.com) with an authorized Teams administrator. Go to **Users → Manage users**, select the licensed user and open **Voice**. Under **Call answering rules**, choose **Be immediately forwarded**, select the external phone-number destination and enter the tested Voiceflow answering number in E.164 format. Save and reopen the user's settings to verify the selected destination.

Keep this distinct from simultaneous ringing or an unanswered-call rule: the controlled test should reach the agent immediately. The **Voice** tab requires the Teams Phone license. If forwarding is unavailable, resolve the user's license, Teams Only mode, PSTN service and effective calling policy before changing routing.

#### Developer

Use [Microsoft Teams PowerShell](https://learn.microsoft.com/en-us/microsoftteams/teams-powershell-install) with an authorized Teams administrator. Install the current supported module in an appropriate PowerShell environment if needed, then sign in:

```powershell
$ErrorActionPreference = 'Stop'
Install-Module MicrosoftTeams -Scope CurrentUser
Import-Module MicrosoftTeams
Connect-MicrosoftTeams
```

The administrator must verify the affected user's external-forwarding policy described above; do not modify the Global policy for this test. Set `$TeamsUser` to that user's real UPN and `$VoiceflowNumber` to the tested E.164 destination. The following values are illustrative:

```powershell
$TeamsUser = 'phone-test@your-company.example'
$VoiceflowNumber = '+14155550120'
$Before = Get-CsUserCallingSettings -Identity $TeamsUser
$Before | Export-Clixml -Path './teams-calling-before.xml'
$Before | Format-List IsForwardingEnabled,ForwardingType,ForwardingTargetType,ForwardingTarget

Set-CsUserCallingSettings -Identity $TeamsUser -IsForwardingEnabled $true `
  -ForwardingType Immediate -ForwardingTargetType SingleTarget `
  -ForwardingTarget $VoiceflowNumber

Get-CsUserCallingSettings -Identity $TeamsUser |
  Format-List IsForwardingEnabled,ForwardingType,ForwardingTargetType,ForwardingTarget
```

Read back `True`, `Immediate`, `SingleTarget` and the intended phone number. The saved XML is a local rollback snapshot, not a provider credential. [Set-CsUserCallingSettings](https://learn.microsoft.com/en-us/powershell/module/microsoftteams/set-csusercallingsettings) requires related forwarding fields to be supplied together; changing only a target is insufficient. Test a call to the user's public number after the saved configuration is applied.

### A Teams Direct Routing deployment

Keep Microsoft's certified SBC requirement in the phone-system architecture.

[Teams Direct Routing](https://learn.microsoft.com/en-us/microsoftteams/direct-routing-plan) requires a Microsoft-certified SBC and tenant/domain, certificate and voice-routing configuration. Voiceflow's SIP hostname is not a certified Microsoft SBC. For an existing Direct Routing deployment, have its administrator assess a separate SBC-to-Voiceflow peer against [Voiceflow SIP requirements](/docs/api-reference/agent-runtime/voice/sip/settings#network-and-media). This manual supplies a complete public-number forwarding route; it does not certify an SBC deployment or replace Microsoft's deployment procedure.

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

## Inbound calls

Verify the customer reaches the intended agent through the business phone route.

### 1. Call the business entry number

Call the **Teams Phone business entry number** from a separate phone. Confirm the expected forwarding rule runs and the Voiceflow agent answers without a human acceptance prompt.

### 2. Check the conversation

Verify speech in both directions. Ask a question covered by the agent's approved Knowledge, then one it cannot answer; check that its fallback follows the reviewed instructions.

### 3. Match the observed call

Inspect the matching [Transcript](/docs/documentation/measure/transcripts) and the provider's call history using time and dialled numbers.

Keep these checks separate from the direct answering-number test: a direct call proves the agent route, while a call to the business number additionally tests Teams Phone forwarding. Test each schedule you enable. The immediate forwarding rule should bypass the user devices. Test an external PSTN caller as well as any internal test; internal Teams calling alone does not verify the public phone route.

Forwarding can change the caller identity presented to the answering carrier. Record what actually arrives; a forwarded caller number or `user_id` is not proof of the original customer's identity. Use an appropriate verification step before exposing account-specific data. The phone connection does not import Knowledge or customer records; configure those through their [existing agent features](/docs/documentation/build/querying-the-knowledge-base).

#### Studio

In Agent studio, compare the saved number assignment with the project's Transcripts. Publish the reviewed Environment when ready for customer calls, then deliberately set the answering number to **Published** and repeat a fresh call through the business number.

#### Developer

Read the answering resource after a route change. Its `voice.projectID`, `voice.environmentAlias` and `voice.version` must match the intended release. Use the [assignment API](/docs/api-reference/phone-number/assign-phone-number) or the CLI's `phone-number assign` operation to change that route, then read it back. Use [call events](/docs/guides/developers/voice/call-events) when your application also needs call outcomes; the provider's forwarding save is not an answered-call event.

### The direct number works but the business line does not

Inspect the provider's effective destination, schedule and acceptance settings.

Check the exact user and public DID, external-forwarding permission, active hours and saved destination. Remove a human acceptance prompt from the selected route, and check whether another device, greeting or voicemail answers first. Keep the direct Voiceflow number test available to isolate the failing leg. Check Teams Phone/PSTN licensing, Teams Only mode and the effective external-forwarding policy. Microsoft provides a Teams Call Forwarding diagnostic in its [user settings guidance](https://learn.microsoft.com/en-us/microsoftteams/user-call-settings#diagnosing-issues-with-call-forwarding).

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

## Outbound calls

Place a customer callback through the separately configured Voiceflow caller.

An inbound forwarding rule does not supply Teams Phone's number as a Voiceflow outbound caller. In this recipe, a callback originates from the selected Voiceflow-connected number and its underlying carrier. Use that number's saved Voice agent/release, available credits and production call capacity. If using Teams Phone's caller ID is essential, have the phone administrator establish a separately verified outbound interconnect before promising it to customers.

#### Studio

For a connected Twilio, Vonage or Telnyx number, open **Phone numbers → Outbound call API → View** and test a separate E.164 phone you can answer. A number provisioned through Voiceflow has no Studio Test call panel: give its answering number, agent/release and controlled recipient to your backend implementer for the request below. Use **+1 206 555 0199** only as an illustrative recipient; never test against the forwarded business entry line.

#### Developer

Use `PHONE_NUMBER_ID` from the answering-number lookup, `VF_API_KEY` from its assigned Voice project and a separate E.164 `TEST_RECIPIENT`. The following request disables answering-machine detection for the controlled test:

```sh
jq -n --arg to "$TEST_RECIPIENT" '{to:$to,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 @-
```

The empty `201` accepts the request; it supplies no call ID and does not establish that someone answered. The [phone calling contract](/docs/api-reference/agent-runtime/voice/phone-calls) owns exact fields and provider-specific detection/override behavior. Keep the runtime key separate from `VF_TOKEN` and the Microsoft Teams administrator session.

Answer the recipient, check the agent's opening and intended task, and match the outcome to its Transcript/call events. [Make an outbound call](/docs/documentation/deploy/phone/outbound-calling) supplies the shared workflow and recovery checks. Inspect an uncertain attempt before retrying; forwarding does not add an idempotency mechanism or scheduler.

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

## Transferring callers

Send an active caller to a separate number the support team can answer.

Choose a teammate's **public Teams Phone number** that does not forward to the AI. A bare internal extension is not a PSTN destination in this recipe. Confirm your team can answer it directly before enabling the transfer, and keep it different from both the business entry and Voiceflow answering numbers.

#### Studio

In the Voice agent's **Agent** page, open the **Call forward** system tool and enable it. Choose **Phone number**, enter the teammate's E.164 destination and describe when the agent should transfer. Add the same condition to the agent's instructions. For a fixed branch, use the Workflow's **Call forward** step instead.

Call forward system tool with a separate support number — Transfer to the separate teammate line, rather than the business number that forwards to the AI.

Publish/assign the reviewed release before customer use. [Transfer a phone call](/docs/guides/studio/voice/transfer-calls) covers both Studio entry paths.

#### Developer

Set `SUPPORT_DESTINATION` to the separate, tested E.164 teammate number. `VF_TOKEN` also needs agent-read, agent-update and Environment-compile access for this project/release. Retain the tool configuration and explicitly requested instructions before changing them:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/agent?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT&includeInstructions=true" \
  -H "Authorization: Bearer $VF_TOKEN" > agent-before-transfer.json

jq -e --arg address "$SUPPORT_DESTINATION" '
  if (.agent.instructions | type)!="string" then error("Read the current instructions first") else . end |
  {instructions:(.agent.instructions + "\nTransfer to the support team when the caller asks for a person."),
   callForwardTool:{enabled:true,addressType:"phone",address:$address,
    description:"Transfer when the caller asks for the support team.",messages:null,toolSound:null}}' \
  agent-before-transfer.json |
curl --fail-with-body --silent --show-error -X PATCH \
  "https://realtime-api.voiceflow.com/v2/stable/agent?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-

curl --fail-with-body --silent --show-error -X PUT \
  "https://realtime-api.voiceflow.com/v1/stable/environment/$ENVIRONMENT/compile?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN"
```

Read the agent back with `includeInstructions=true` to verify `callForwardTool` and the appended transfer instruction. The PATCH replaces that tool configuration and updates the retained instruction text; keep both previous values for restoration. The [Agent API](/docs/api-reference/agent/get-agent) and [developer transfer workflow](/docs/guides/developers/voice/transfer-calls) own the complete configuration/compile contract.

Place a call to the business entry number with a teammate waiting at the destination. Ask for a person, confirm the teammate receives the caller and inspect the Transcript. A prototype run or accepted transfer does not establish a human answer. The forwarding leg remains part of the call route; Teams Phone's phone-to-phone transfer options do not establish a warm AI transfer or automatic context delivery.

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

## Managing routing

Change the answering release or restore the original phone route deliberately.

### Restore Teams Phone forwarding

#### Studio

In **Teams admin center → Users → Manage users → [user] → Voice**, restore the recorded call-answering rule and destination, then save. Recheck the user's original forwarding or device-ringing behavior with a fresh call. Leave policies, resource accounts and other users unchanged unless the administrator deliberately needs to modify them.

#### Developer

In the authorized PowerShell session, review the saved XML for the same test user. Restore the forwarding group, including its type and target when it was previously enabled:

```powershell
$Saved = Import-Clixml -Path './teams-calling-before.xml'
$Restore = @{
  Identity = $TeamsUser
  IsForwardingEnabled = [bool]$Saved.IsForwardingEnabled
}
if ($Saved.IsForwardingEnabled) {
  $Restore.ForwardingType = $Saved.ForwardingType
  $Restore.ForwardingTargetType = $Saved.ForwardingTargetType
  if ($Saved.ForwardingTargetType -eq 'SingleTarget') {
    $Restore.ForwardingTarget = $Saved.ForwardingTarget
  }
}
Set-CsUserCallingSettings @Restore
Get-CsUserCallingSettings -Identity $TeamsUser |
  Format-List IsForwardingEnabled,ForwardingType,ForwardingTargetType,ForwardingTarget
```

When forwarding was previously off, the command disables it; when it was on, compare the restored mode/target with the snapshot. Group/delegate membership was not changed by this recipe. Reconcile intervening administrator changes before restoring, then test the original route. Disconnect the management session with `Disconnect-MicrosoftTeams` when finished.

### Change the answering agent or release

Keep the provider destination stable while changing the answering number's assignment in Voiceflow. In Studio, select the intended agent/Environment/version and save; in Code, use the [number-assignment operation](/docs/api-reference/phone-number/assign-phone-number) and read the resource back. Publishing alone does not move a number pinned to Draft. Test a fresh call through the business number after the change.

Before deleting, unassigning or replacing the Voiceflow answering number, restore or replace the provider's forwarding destination and test it. Removing an agent route leaves the provider's saved forwarding rule in place. Keep credentials for provider call-handling APIs separate from Voiceflow management/runtime keys when rotating access.
