Overview
Let Voiceflow answer calls to an existing Zoom 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 Zoom Phone number your team answers.
- Connect the business line while keeping its number with Zoom 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 Zoom Phone phone-user routing. Zoom Contact Center configuration remains in Contact Centers. 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 Zoom Phone. The two systems keep separate routing and release settings.
Code
Use the current per-user Zoom Phone APIs to stage/read/change forwarding; complete its required acceptance-prompt GUI step locally before using Voiceflow calling APIs. 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 Zoom 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. Zoom 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 Zoom 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 Zoom 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 Zoom Phone user’s calls
Use a licensed Zoom Phone user with an assigned DID, permission to edit that user’s phone settings and a calling package that allows external forwarding. A numeric extension without a DID cannot use this route. Record the chosen hours, enabled destinations and acceptance-prompt setting before changing them.
Zoom’s call-handling controls govern external destinations, acceptance and ringing duration. Keep the original values available for restoration.
This is a user route. A Zoom Phone queue requires the press-1 setting and is not interchangeable with it. Configure business, closed, break or holiday hours deliberately; the example below changes business-hours destinations and leaves the schedule itself in place.
Studio
In the Zoom web portal, an administrator opens Admin Center → Product configuration → Phone system → Users & Rooms, selects the user, then User Settings. Under Business Hours → Call Handling, choose Edit. Use Add Phone Number for the tested Voiceflow answering number. Turn Require to press 1 before connecting the call off, enable the answering number and disable the other ringing destinations for the controlled test. Set a ringing duration long enough for the tested answering number to connect, save and reopen the setting. See Zoom’s call-handling controls.
Call the user’s public Zoom Phone number. In a user-managed account, the same settings are under Profile → Zoom Phone → Settings. If the external destination or acceptance control is locked, have the phone administrator resolve the account/site policy before testing. The resulting saved rule must reach the agent without a person pressing a key.
Code
Use a Business or Enterprise Zoom account with Zoom Phone, and an authorized OAuth app. The following admin granular scopes cover the complete read/add/update/remove lifecycle:
phone:read:user:adminphone:read:user_call_handling_setting:adminphone:write:user_call_handling_setting:adminphone:update:user_call_handling_setting:adminphone:delete:user_call_handling_setting:admin
Create/authorize the app through Zoom OAuth. Set ZOOM_TOKEN to its access token and ZOOM_USER_EMAIL to the intended licensed user’s email. Read the profile and retain its user ID:
Confirm the assigned public DID and the effective forwarding policy. For a policy record, external numeric destinations require the feature enabled and restriction type 4; types 1–3 restrict them. Resolve locked policies with the administrator. Do not use the deprecated forwarding_to_external_numbers boolean as the readiness check. ZOOM_USER_ID is distinct from extension_id and the dialling extension.
The current per-user destination schema does not expose the main ringing route’s global acceptance switch. A local portal step after staging the number below is required; do not add an old generic API wrapper or an invented field to the request.
Retain the business-hours destinations, then stage an inactive new entry. This recipe creates a new entry; stop and review the existing route if that destination is already present:
The 201 supplies the created ID. A timeout may still have created it: read the current list before retrying the POST.
Before enabling the staged entry, the administrator opens Zoom’s portal → Admin Center → Product configuration → Phone system → Users & Rooms → [user] → User Settings → Business Hours → Call Handling → Edit. Record the original Require to press 1 before connecting the call value, turn it off and save, keeping the new number disabled and other destinations unchanged. Check that the existing ringing duration allows the directly tested Voiceflow number to answer. This required GUI step supplies the acceptance setting absent from the per-user API.
Re-read the inactive entry, verify the ID/number and prepare an update that retains every observed ID while enabling only the selected route:
The PATCH returns empty 204. It updates the selected hour’s destination enable states, leaving the schedule/timezone and unrelated handling settings alone. These are the current per-user operations in Zoom’s Phone API, not the deprecated generic extension call-handling wrapper. Check a real forwarded call during business hours before customer use.
A Zoom Phone SBC deployment
Use a phone administrator for an existing BYOC-P or BYOP-P route.
Zoom’s BYOC-P/BYOP-P infrastructure and configuration require the applicable SBC and routing setup. An existing administrator-managed deployment can be assessed against Voiceflow SIP requirements; a Zoom SIP Group alone does not establish a working Voiceflow peer. This manual completes the public-number user-forwarding route. It does not describe Zoom Contact Center, Zoom Virtual Agent or an unverified direct cloud SIP connection.
Inbound calls
Verify the customer reaches the intended agent through the business phone route.
Call the business entry number
Call the Zoom 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 Zoom Phone forwarding. Test each schedule you enable. Check business-hours routing and a second active period separately. The forwarded caller ID may identify the forwarding line rather than the original caller.
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. Zoom users need an assigned DID for external forwarding. If a queue still asks the callee to press 1, return to the documented user route instead of treating queue settings as equivalent.
Outbound calls
Place a customer callback through the separately configured Voiceflow caller.
An inbound forwarding rule does not supply Zoom 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 Zoom 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 Zoom OAuth token.
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 Zoom 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; Zoom 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 Zoom Phone forwarding
Studio
Reopen the same user’s User Settings → Business Hours → Call Handling → Edit. Restore the previously enabled devices/numbers and the recorded press-1 setting. Remove only the new Voiceflow forwarding entry when it is no longer used, save and test the original route. Closed/holiday/break hours have their own settings; inspect the hours you actually changed.
Code
Restore the original enable states and disable the entry created by this recipe. Use the saved IDs, not a wholesale replay of GET’s read-only profile/handling data:
Delete returns empty 204. Restore the separately recorded press-1 value through the portal and verify the original call route. Delete only an entry created by this test. If another administrator has changed the destination list, reconcile that change before replaying the snapshot. When updating closed or break hours, Zoom requires business hours not to be 24×7; holiday/break requests also require the corresponding hour ID. Do not apply this business-hours payload to a different period without that setup.
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.