Phone numbers and routing

Start in Settings → Phone Numbers. A number’s verification, inbound assignment, and outbound route are separate parts of setup. Test each direction you intend to use. Use the search box in Managed Phone Numbers to filter by number, name, type (Hosted, BYOC or WhatsApp), or inbound destination. Results update as you type. Search ignores letter case and phone-number formatting such as spaces, parentheses, hyphens and the leading +. Clear the search to show all numbers again.

​

Choose a number setup

Use international format, for example +14155551234. A verified number confirms that you can use it; it does not by itself configure your carrier’s routing or permission to place calls to every destination.

​

Route incoming calls

1. Create an agent in Channels → Phone → Agents if AI should answer.
2. Open the agent’s Telephony & Routing settings and assign the inbound number. A number can have only one inbound destination: an AI phone agent or a Classical IVR. Unassign its existing destination before switching between those types.
3. Check Inbound Agent beside the number in Settings → Phone Numbers.
4. Call that number from a real phone and verify who answers.

For recorded keypad menus, enable Classical IVR in Settings → Voice & Telephony, then assign the number from Channels → Phone → Classical IVR → Workflows. Settings → Phone Numbers → Inbound destination shows the assigned IVR or agent. See Classical IVR setup. For supported inbound routes, an Unassigned number rings eligible teammates in the dashboard. Keep a teammate online and Available for calls when testing this path. See Human calling for eligibility and missed calls. When Classical IVR is enabled, calls to a number assigned to an IVR run that workflow first. For calls without an active IVR assignment, a valid X-OPENCX-AGENT-ID header for your workspace takes precedence. Otherwise, OpenCX looks up the agent assigned to the dialed number. If no agent is resolved for a recognized workspace, the call can enter the human-answering path. Do not rely on an unspecified workspace default AI agent; assign the number or send the header explicitly.

​

Configure outbound calls

AI calls: open the agent’s Telephony & Routing settings and select its outbound caller number or outbound SIP trunk. The agent’s inbound number assignment alone is not proof that outbound calling works. Human calls: choose a verified caller number in the dashboard dialer. OpenCX resolves an outbound route for that number, using a matching configured number route, an owning agent’s route, or the workspace’s hosted route where available. External numbers need a valid outbound route. See Human calling.

​

Limit outbound numbers by team

1. In Settings → Teams, edit a team and open Outbound numbers.
2. Select the verified numbers its members may use, then Save. The same number can be selected for several teams. Create a new team first, then edit it to configure its outbound numbers.
3. In Settings → Roles, disable Use all outbound numbers for the roles that should be restricted. Add agents to the appropriate teams under Settings → Teams.

Restricted agents can select only numbers allowed for at least one of their current teams. A number with no allowed teams is unavailable to them. This also applies when selecting a caller number for an external participant or phone transfer. OpenCX checks access again when starting the call, so removing a team membership also prevents calls from an already-open dialer. Workspace admins retain access to every number. Use all outbound numbers also grants unrestricted number selection to other roles, but does not itself grant permission to place calls. If an agent has several roles, a grant on any role applies. Existing calling roles retain Use all outbound numbers during rollout. Older role editors preserve this grant when saving; refresh the dashboard before intentionally removing it. Configure the number mappings before removing that permission. These settings control human-selected outbound caller numbers; they do not change inbound routing, chat access, or automated workflow caller numbers. Your carrier must accept the caller identity and destination on that route. Test the caller ID on the receiving phone; the same displayed caller number does not prove that an AI call and a human call used the same route.

​

Outbound number pools

Number pools group verified BYOC numbers from your own carrier. They choose a regional caller when available and let sequence phone steps retry from different numbers.

1. Add and verify your BYOC numbers in Settings → Phone Numbers.
2. Configure your outbound SIP trunk in Settings → SIP. Your carrier must authorize the selected numbers for outbound calls on that trunk.
3. In Settings → Phone Numbers → Number pools, choose Create pool, enter a Pool name, select the Outbound SIP trunk, and choose your numbers. Each number can belong to only one pool.
4. Read and accept the responsibility notice, then choose Save pool. You need Voice settings write access to create or change pools.

Each pool uses its selected SIP trunk. If that trunk is unavailable or invalid, the call cannot start. To use a different trunk, create a new pool. Delete the pools using a trunk before editing or deleting it in Settings → SIP. Agents using pools can share a trunk. If another agent uses that trunk directly, set an explicit caller number for that agent first. Each caller number must be listed on only one outbound SIP trunk in your workspace. If a number already uses another trunk, select that trunk for the pool or remove the number from it first. Open your agent in Channels → Phone → Agents → Telephony & Routing. Under Outbound Caller, select the pool and set Maximum calls per step and Retry delay (minutes). In a sequence, select that agent under Settings; phone steps use its outbound setup automatically. A pool can contain numbers from several regions, while each step makes at most three calls per person. Calls first look for a matching US area code, then the same US state, then the destination country, and finally any other available number in the pool. If there is no regional match, the call still uses a pool number. International destinations are supported when your carrier allows them. The region associated with a phone number does not confirm the recipient’s current location. Sequence phone steps default to three calls, with two minutes between an unsuccessful call ending and the next attempt. Each retry uses a different number. No answer, busy, voicemail, machine answers, and failed calls can lead to another attempt. A human answer stops the remaining sequence steps for that person. If the attempt limit is reached or no unused numbers remain, the person advances to the next step. Sequence Step Failed workflows run only after the pool step finishes unsuccessfully. Existing calling windows and contact restrictions still apply. One-time dashboard, API, and workflow calls choose one number from the pool and make one attempt. A sequence step already in progress keeps the pool and retry settings it started with; new steps use the agent’s current settings. The sequence’s People view and phone-step details show Calling, Retry scheduled, Answered, or Attempts exhausted, with the attempt count. After the last unsuccessful attempt, they also show No answer, Busy / declined, or Failed. Scheduled retries show the next eligible time. Pausing the sequence shows Paused until it resumes. If required contact details are missing, the step shows what needs attention.

​

Automatic replacement

Automatically replace numbers is off by default. Connect your own primary Twilio account to buy replacement numbers and release old ones on a schedule. Other carriers can be used for BYOC pool calls; the Twilio connection is only needed for automatic replacement.

1. Enable Automatically replace numbers in the pool editor.
2. Set Replace numbers after (days) to 1–365 days. The default is three days.
3. Enter your Account SID, Trunk SID, and Auth Token. Use an active primary account that you own and manage. Subaccounts and OpenCX-managed accounts are not supported. The Twilio trunk must match the SIP trunk selected for the pool, and the numbers must belong to that account and trunk.
4. Choose Save pool. OpenCX verifies the connection before enabling replacement.

Your Auth Token is encrypted when saved and cannot be viewed in the dashboard. Use Update auth token to save a new token for the same account and trunk. To remove it, turn off automatic replacement, finish any replacements in progress, choose Remove saved token, and save. The pool keeps its account and trunk settings after token removal. Create a new pool to use a different account or trunk. Replacement purchases and configures a number in your connected account before releasing the old one. It preserves the country, known US state, and number type. Teams allowed to use the old outbound number automatically retain access through its replacement. Number availability and registration requirements can delay replacement. Numbers assigned to incoming calls are not automatically replaced. Replacement also waits until your workspace has no active calls. A number being replaced is temporarily unavailable for new calls. Turning replacement off keeps the current number after confirming that your account still owns it and completing setup for any replacement already purchased. If setup fails, the replacement stays reserved until you retry. A purchased replacement remains yours and appears in Phone Numbers after cancellation. You cannot delete a reserved replacement until replacement finishes or is canceled. If release of the old number has already started, let replacement finish before turning it off. Your provider charges your connected account for purchases and usage. Released numbers stop receiving calls and callbacks and may be reassigned. Adding a number to a pool does not change its incoming-call routing. No callback forwarding or retention period is added when a number is released. Deleting a pool keeps its numbers in your account and workspace. Choose another outbound caller for agents using the pool before deleting it. Replacement errors appear beside the affected number.

​

Access and verification

Changing phone configuration requires Voice settings write access. Assigning outbound numbers to teams requires Teams write access. API callers need phone:write to start an AI outbound call. Before opening the line to customers, verify:

• A real inbound call reaches the intended IVR, AI agent or teammate.
• An AI outbound call connects and displays the intended caller ID.
• A human outbound call works if your team will use the dialer.
• Each transfer destination answers, and the team knows what to do if it cannot.
• The session contains the expected call record and, when enabled, recording.

A browser Test Call checks the agent experience. It does not verify a phone number’s carrier route. For failed real calls, use Phone troubleshooting.