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

# Zoom Phone integration

> Connect Zoom Phone user calls to a Voiceflow agent, configure external forwarding and verify callbacks and teammate transfers.

## 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](#connecting-zoom-phone) while keeping its number with Zoom 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 Zoom Phone phone-user routing. Zoom Contact Center configuration remains in [Contact Centers](/docs/guides/integrations/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](https://creator.voiceflow.com), then configure the user's forwarding in Zoom 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 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.

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

## 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](/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. 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.

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 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](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0069180) 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](https://zoom.us), 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](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0069180).

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.

#### Developer

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:admin`
- `phone:read:user_call_handling_setting:admin`
- `phone:write:user_call_handling_setting:admin`
- `phone:update:user_call_handling_setting:admin`
- `phone:delete:user_call_handling_setting:admin`

Create/authorize the app through [Zoom OAuth](https://developers.zoom.us/docs/integrations/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**:

```sh
curl --fail-with-body --silent --show-error \
  "https://api.zoom.us/v2/phone/users/$ZOOM_USER_EMAIL" \
  -H "Authorization: Bearer $ZOOM_TOKEN" > zoom-phone-user.json
ZOOM_USER_ID=$(jq -er '.id' zoom-phone-user.json)
jq '{id,phone_numbers,policy:.policy.call_handling_forwarding_to_other_users}' zoom-phone-user.json
```

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:

```sh
ZOOM_HANDLING="https://api.zoom.us/v2/phone/users/$ZOOM_USER_ID/call_handling/settings"
ZOOM_FORWARD="https://api.zoom.us/v2/phone/users/$ZOOM_USER_ID/call_forward_settings/business_hours"
curl --fail-with-body --silent --show-error \
  "$ZOOM_HANDLING?hour_type=business_hours" \
  -H "Authorization: Bearer $ZOOM_TOKEN" > zoom-handling-before.json

jq -e --arg number "$VF_NUMBER" \
  '[.call_forward_settings[] | select(.phone_number==$number)] | length==0' \
  zoom-handling-before.json

jq -n --arg number "$VF_NUMBER" \
  '{call_forward_settings:[{enable:false,phone_number:$number,phone_number_description:"Voiceflow support"}]}' \
  > zoom-add-forward.json
curl --fail-with-body --silent --show-error -X POST "$ZOOM_FORWARD" \
  -H "Authorization: Bearer $ZOOM_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @zoom-add-forward.json > zoom-created-forward.json
VF_FORWARD_ID=$(jq -er '.call_forward_settings | if length==1 then .[0].call_forward_id else error("Expected one created route") end' zoom-created-forward.json)
```

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](https://zoom.us) → **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:

```sh
curl --fail-with-body --silent --show-error \
  "$ZOOM_HANDLING?hour_type=business_hours" \
  -H "Authorization: Bearer $ZOOM_TOKEN" > zoom-handling-staged.json

jq -e --arg id "$VF_FORWARD_ID" --arg number "$VF_NUMBER" '
  .call_forward_settings |
  if any(.[]; .call_forward_id==$id and .phone_number==$number and .enable==false) then .
  else error("Staged destination not found") end |
  {call_forward_settings:map({call_forward_id,enable:(.call_forward_id==$id)})}' \
  zoom-handling-staged.json > zoom-enable-forward.json

curl --fail-with-body --silent --show-error -X PATCH \
  "$ZOOM_HANDLING/business_hours" \
  -H "Authorization: Bearer $ZOOM_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @zoom-enable-forward.json

curl --fail-with-body --silent --show-error \
  "$ZOOM_HANDLING?hour_type=business_hours" \
  -H "Authorization: Bearer $ZOOM_TOKEN" > zoom-handling-after.json
jq -e --arg id "$VF_FORWARD_ID" \
  '[.call_forward_settings[] | select(.enable)] | length==1 and .[0].call_forward_id==$id' \
  zoom-handling-after.json
```

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](https://developers.zoom.us/docs/api/phone/), 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](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0079203) and [configuration](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0083637) require the applicable SBC and routing setup. An existing administrator-managed deployment can be assessed against [Voiceflow SIP requirements](/docs/api-reference/agent-runtime/voice/sip/settings#network-and-media); 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.

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

### 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 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](/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. 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.

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

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

#### 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 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](/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 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.

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; Zoom 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 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.

#### Developer

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:

```sh
jq --arg id "$VF_FORWARD_ID" \
  '{call_forward_settings:([.call_forward_settings[] | {call_forward_id,enable}] +
    [{call_forward_id:$id,enable:false}])}' \
  zoom-handling-before.json > zoom-restore-forward.json

curl --fail-with-body --silent --show-error -X PATCH \
  "$ZOOM_HANDLING/business_hours" \
  -H "Authorization: Bearer $ZOOM_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @zoom-restore-forward.json

curl --fail-with-body --silent --show-error -X DELETE \
  "$ZOOM_FORWARD?call_forward_id=$VF_FORWARD_ID" \
  -H "Authorization: Bearer $ZOOM_TOKEN"

curl --fail-with-body --silent --show-error \
  "$ZOOM_HANDLING?hour_type=business_hours" \
  -H "Authorization: Bearer $ZOOM_TOKEN" > zoom-handling-restored.json
```

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](/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.
