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 while keeping its number with Teams Phone.
- Receive support calls with the assigned Voice agent and verify the complete forwarded route.
- Make an outbound call through the independently configured Voiceflow caller.
- Transfer callers to a separate teammate line, then maintain or restore the route.
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, then configure the user’s forwarding in Teams Phone. The two systems keep separate routing and release settings.
Code
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.
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 supplies a number through Voiceflow; the Twilio, Vonage and 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.
Code
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:
Confirm the alias and version are the controlled test release. Correct them through the number-assignment operation 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 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 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.
Code
Use Microsoft Teams PowerShell with an authorized Teams administrator. Install the current supported module in an appropriate PowerShell environment if needed, then sign in:
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:
Read back True, Immediate, SingleTarget and the intended phone number. The saved XML is a local rollback snapshot, not a provider credential. 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 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. This manual supplies a complete public-number forwarding route; it does not certify an SBC deployment or replace Microsoft’s deployment procedure.
Inbound calls
Verify the customer reaches the intended agent through the business phone route.
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.
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.
Match the observed call
Inspect the matching Transcript 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.
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.
Code
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 or the CLI’s phone-number assign operation to change that route, then read it back. Use 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.
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.
Code
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:
The empty 201 accepts the request; it supplies no call ID and does not establish that someone answered. The phone calling contract 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 supplies the shared workflow and recovery checks. Inspect an uncertain attempt before retrying; forwarding does not add an idempotency mechanism or scheduler.
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.
Publish/assign the reviewed release before customer use. Transfer a phone call covers both Studio entry paths.
Code
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:
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 and developer transfer workflow 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.
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.
Code
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:
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 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.