Telephony configuration

Telephony configuration is where an administrator decides who answers each of your organization's phone numbers: you label the trunks and numbers xMatix provisions for you, build queues of agents, register AI and human agents, and point every number at one of them with an inbound route. It comes after xMatix has provisioned voice for your organization and before your agents take calls on the softphone.

Overview

Telephony administration splits in two. The infrastructure — voice trunks and phone numbers — is provisioned for your organization by xMatix. Everything organizational — queues, agents, routes and the on/off switch — is yours to author. Five screens sit under Setup → Feature Hub → Service → Telephony:

The Telephony group appears in Setup only when your organization holds the Telephony & Messaging product.

When to use it

• Telephony has just been provisioned and you are setting it up for the first time.
• A new team, line or AI assistant needs its own number, queue or agent.
• Calls ring the wrong people, ring everyone, or are not answered at all.
• Someone joins or leaves the call team.
• A route shows Error on the Routing screen.

How xMatix handles it

A call follows the route of the number that was dialled. Each number can carry one route. When a call arrives, xMatix first matches the caller to a contact and account, then reads the route of the called number:

• Queue — the call is offered to one available member of the queue's agent pool, chosen by the queue's routing model. Only that agent's softphone rings.
• Human agent — only that person's softphone rings.
• AI agent — the AI agent joins the call and answers it; no person is rung.

When the number has no active route, when a human-agent target is inactive, when nobody in the queue's pool can take the call, or when the queue no longer exists, the call rings every signed-in agent in your organization instead. Inbound routing explains this fallback in detail.

Routes are pushed to the voice platform. A route only works once it also exists as configuration on the voice platform that answers your numbers. xMatix pushes it there every time you create, edit, resync or delete a route, and every time you save or create an AI agent. The Status column shows the outcome — Synced, Syncing… or Error — and the screen checks again every 10 seconds while a route is syncing.

Who gets the call dock. The Calls drawer and the call bar at the bottom of the workspace appear only for users who are in the agent pool of at least one active queue, and only while Enable Telephony (CTI) is on. They are not shown on mobile devices. This applies to human agents you route to directly as well: a person who is not in an active queue's pool has no softphone, so a direct route to them never reaches them.

Infrastructure is managed for you. You cannot create or delete trunks or numbers, and no provider settings or credentials appear anywhere in Setup.

Prerequisites

• Your organization holds the Telephony & Messaging product, and xMatix has provisioned at least one trunk and one number. Until then the screens open but list nothing.
• Your security profile grants Manage telephony (CTI). To use the Settings screen you also need Manage module settings.
• Each person who will take calls has a resource record linked to their user, and belongs to a resource group. Queue pools are resource groups — see Queues and omni-channel routing.
• Any AI agent identity you plan to use has been deployed for your organization by xMatix.

Procedure

Step 1 — Check that telephony is switched on

1. Open Setup → Feature Hub → Service → Telephony → Settings.
2. Make sure Enable Telephony (CTI) is on. It is on by default.
3. If you changed it, select Save.

When the switch is off, telephony is unavailable to every user and nobody gets the call dock. Setup stays reachable, so you can switch it back on.

Step 2 — Review and label trunks and numbers

1. Open Setup → Feature Hub → Service → Telephony → Trunks & numbers. The page has two tabs, Trunks and Phone numbers.
2. On Trunks, select Edit on a row. In Edit trunk, set:
   • Name — a friendly name. Left blank, the trunk shows the provider name.
   • Description — optional notes.
   • Enabled — whether xMatix uses this trunk.
   • Default for outbound calls — turn it on for the trunk xMatix should use first.
3. Select Save. Making one trunk the default clears the default flag on every other trunk.
4. On Phone numbers, select Edit on a number and set its Label (for example Main support line), its Outbound caller ID and Active. Select Save.

An empty Trunks tab means telephony has not been provisioned yet; contact xMatix to enable it. An empty Phone numbers tab means no numbers have been allocated yet.

Step 3 — Create a queue

1. Open Setup → Feature Hub → Service → Telephony → Queues and select New queue.
2. Enter a Name (required) and choose a Routing model: Direct, Round robin, Load balance or Skill-based. The dialog suggests Round robin.
3. Optionally add a Description.
4. In Channels, keep Voice for a queue that takes calls. You can add other channels, such as Email, Chat, SMS and Web.
5. In Agent pool, choose the resource group whose members take work from this queue.
6. Leave Active on, and select Create.

The queue appears in the list with its routing model, channels, agent pool and status. Members of its pool who are signed in on a desktop browser get the call dock the next time their session loads. The full queue reference — eligibility, presence, capacity and how each routing model picks an agent — is on Queues and omni-channel routing.

Step 4 — Add human agents

1. Open Setup → Feature Hub → Service → Telephony → Agents and select the Human agents tab.
2. Select New human agent.
3. Choose the User and enter an Extension — the agent's telephony identity, such as 1001. Both are required.
4. Optionally pick an Outbound caller ID from your active numbers.
5. Leave Active on, and select Create.

The user appears with their extension and status. You need a human agent entry only to route a number straight to that person; queue members take queue calls without one. To change an entry later, select Edit — the user cannot be changed, only the extension, caller ID and Active.

Step 5 — Add an AI agent

1. On the Agents screen, select the AI agents tab, then New AI agent.
2. Enter the Agent identity (required). It must match the identity of a voice agent deployed for your organization by xMatix; calls routed to an unknown identity are not answered.
3. Give it a Name and an optional Description.
4. Shape how it talks to callers with Greeting, Instructions, Caller language, Voice, Pause before replying and Let the caller interrupt.
5. In Transfer to, enter the number the agent connects a caller to when they ask for a person, with its country code.
6. For a fixed conversation with no AI, enter Script lines, one reply per line, and an optional Goodbye line.
7. Leave Other settings empty unless xMatix support gives you a value.
8. Leave Active on, and select Create.

xMatix checks the settings when you save and shows any problem, for example Transfer to must be a phone number with its country code, like +919876543210. Saving also pushes the agent's settings to every route that targets it. Active AI agents are also offered in the softphone's Call as list, so an agent can place an outbound call that the AI agent conducts.

Step 6 — Route each number

1. Open Setup → Feature Hub → Service → Telephony → Routing and select New route.
2. Enter a Name. If you leave it blank, xMatix names the route route- followed by the number.
3. Choose the Number (required). Only active numbers are offered.
4. Under Route to, choose Queue, AI agent or Human agent, then choose the target in the field beside it. Only active targets are offered. A queue without the Voice channel is shown with (no Voice channel) after its name.
5. Leave Active on, and select Create.

The route appears with Status Syncing…, which changes to Synced once the voice platform has it. Point at Synced to see when it last synced. If it shows Error, point at the status to read the reason, fix it, and select Resync on the row. See Common problems.

Step 7 — Test the setup

1. Ask an agent in the queue's pool to sign in on a desktop browser, open the Calls drawer and choose Available.
2. Call the routed number from another phone.
3. Check that the right softphone rings — or, for an AI agent, that the agent answers with its greeting.
4. Open the call register and check that the call was recorded with the caller match you expect.

Step 8 — Change, retarget or retire

• Change a route's target: select Edit on the route, choose the new target and select Save. The route syncs again.
• Remove a route: select Delete and confirm. The confirmation warns that inbound calls to the number will stop being routed, and the route is removed from the voice platform.
• Retire a queue: retarget the routes that use it first. Deleting a queue is not blocked by routes; calls to their numbers then ring every signed-in agent. Switching a queue off does not stop a route from sending calls to it.
• Remove an AI agent or human agent: retarget or delete the routes that target it first. Otherwise deleting it fails with This AI agent is the target of an inbound route. Delete or retarget the route first. (or This agent is the target… for a human agent).
• Stop a number taking routed calls: switch the number off on Phone numbers, then select Resync on its route. The route then shows the error The route's number is missing or inactive.

Fields

Trunk (Edit trunk)

The Trunks list also shows Provider (always the xMatix telephony service), Default and Status (Enabled or Disabled).

Phone number

Queue

Human agent

AI agent

Route

The list also shows Target (the target type and name), Status and Updated.

Business rules

• One route per number. A second route on the same number is refused with This number already has a route; edit the existing route instead.
• One target per route, matching the Route to choice.
• Unique identities. Two AI agents cannot share an Agent identity (An AI agent with this agent name already exists for the tenant.). A user can have only one human-agent entry per trunk (This user already has a binding on the selected telephony connection.).
• Human agents need a trunk. Adding one picks your enabled trunk, the default first. With no enabled trunk, it fails with Telephony is not provisioned for this tenant yet.
• Delete guards. An AI agent or human agent that a route targets cannot be deleted. Queues have no such guard.
• Default trunk. Setting a trunk as default clears the flag on every other trunk. xMatix uses the enabled default trunk first, then any other enabled trunk.
• Sync on change. Creating, editing, resyncing or deleting a route, and creating or saving an AI agent, pushes every route in your organization to the voice platform. Opening the Routing screen retries any route still syncing.
• Shadowed numbers. A route can be in place on the voice platform but still never get its calls, because another rule there takes the number's calls first. xMatix detects this and marks the route Error instead of Synced.
• Caller IDs. The Outbound caller ID values on numbers and human agents are recorded but not used when the softphone places a call.

Example

A two-wheeler dealership has two numbers: a service line and an after-hours line.

1. In Settings, the administrator confirms Enable Telephony (CTI) is on.
2. In Trunks & numbers, they label the first number Service desk and the second After hours.
3. In Queues, they create Service advisors, with routing model Round robin, channel Voice and the agent pool Service advisors team.
4. In Agents → AI agents, they create After-hours assistant, with the agent identity xMatix deployed for them, the greeting Thank you for calling. Our workshop is closed now — how can I help?, caller language Multilingual (Hindi + English) and Transfer to set to the duty manager's mobile number.
5. In Routing, they create Service desk (Number: the service line, Route to: Queue, Service advisors) and After hours (Number: the after-hours line, Route to: AI agent, After-hours assistant). Both reach Synced within seconds.
6. An advisor signs in, chooses Available in the Calls drawer and receives the next call to the service line. A test call to the after-hours line is answered by the assistant with its greeting.

Training

Practice exercise

In a sandbox where telephony is provisioned with at least two numbers:

1. Create a queue Practice queue with channel Voice and an agent pool that contains your own user.
2. Create a route from the first number to Practice queue. Wait for Synced.
3. Sign in on a desktop browser, open the Calls drawer, choose Available and call the number. Your softphone should ring.
4. Switch the queue off, reload, and confirm the Calls drawer is gone.
5. Try to create a second route on the same number.

Expected result: step 3 rings only you; step 4 removes your call dock because you are no longer in an active queue's pool; step 5 is refused with This number already has a route; edit the existing route instead. Switch the queue back on when you finish.

Quick reference

• All five screens: Setup → Feature Hub → Service → Telephony.
• Trunks and numbers come from xMatix — you label them, you cannot create them.
• One number, one route, one target.
• No call dock unless the user is in an active queue's pool and Enable Telephony (CTI) is on.
• Unroutable calls ring every signed-in agent; they are not lost.
• Error on a route: point at it, fix the cause, select Resync.
• Retarget routes before deleting a queue, AI agent or human agent.
• Manage telephony (CTI) configures; Supervise telephony (CTI) watches live calls.

Permissions

Both telephony capabilities belong to the Metadata Administration feature and are granted on a security profile's Entitlements tab. See Security profiles.

The built-in SystemAdmin profile holds all three. Keep the manage and supervise capabilities apart on purpose: team leads usually need supervision without configuration rights, and supervisors see every live call in the organization.

Agents themselves need no telephony capability to take calls — they need a place in an active queue's pool.

Configuration

Deployment shapes

Telephony reaches an organization in one of three shapes, chosen with your xMatix account team:

1. Platform-managed voice — xMatix runs the voice infrastructure and allocates your numbers. There is nothing to host and no provider credentials to hold.
2. Your own carrier trunk — your organization keeps its carrier and numbers, and the trunk is connected to the platform's voice infrastructure. Agents use the same softphone.
3. Third-party dialer — calls are handled in an external dialer and logged into the call register through the integration. There is no in-app softphone in this shape.

Common problems

Adding a human agent fails with "Telephony is not provisioned for this tenant yet."

Human-agent entries attach to an enabled trunk. Open Trunks & numbers → Trunks. If the list is empty, telephony has not been provisioned — arrange it with your xMatix account team. If a trunk is listed as Disabled, enable it and try again.

An agent has no Calls drawer

The agent is not in the agent pool of an active queue, the queue's pool has no resource linked to their user, Enable Telephony (CTI) is off, or they are on a mobile device. Add them to the pool's resource group (or switch the queue on), then ask them to reload the page.

A route shows Error: "The route's number is missing or inactive."

The number was switched off or removed. Switch it back on in Trunks & numbers → Phone numbers, or edit the route to use another number, then select Resync.

A route shows Error: "The route's AI agent is missing or inactive."

Switch the AI agent back on in Agents → AI agents, or retarget the route, then select Resync.

A route shows Error: "The voice platform could not be reached. Retry or contact support."

The push to the voice platform failed. Select Resync after a few minutes. If it keeps failing, contact xMatix support. Creating the route on the voice platform failed. and Updating the route on the voice platform failed. are handled the same way.

A route shows Error: "Calls to … are answered by another dispatch rule on the voice platform …"

Another rule on the voice platform takes this number's calls before your route, so callers never reach your target. You cannot remove that rule yourself. Ask xMatix support to remove it, then select Resync. If the message says the platform could not be checked for another rule, simply select Resync.

A route shows Error: "Telephony is not provisioned for this tenant yet."

There is no usable trunk behind your routes. Check Trunks & numbers → Trunks and contact your xMatix account team if it is empty.

Calls to a number ring everybody

The number has no active route, the target human agent is inactive, the target queue was deleted, or nobody in the queue's pool is available with spare capacity. Check the route on Routing, then the target. See Queues and omni-channel routing for the agent checks.

Calls to a human agent never reach them

The person has no call dock because they are not in an active queue's pool. Add them to the pool of an active queue, even if you route to them directly.

Saving an AI agent fails with a settings message

The message names the field: for example Pause before replying must be a number of seconds from 0.3 to 3., A script can have at most 50 lines. or Other settings must be valid JSON, like {"key": "value"}. Correct that field and save again.

Deleting an AI agent or human agent fails

A route still targets it. Edit or delete that route on Routing first.

Common questions

Who do I ask for a new phone number?

xMatix. Numbers are allocated by the platform, not created in Setup. Once a number is allocated, it appears on the Phone numbers tab, where you can label it, switch it on and give it a route. The same applies to trunks: you can rename, describe, enable and choose the default trunk, but you cannot add or remove one. If you need your own carrier numbers rather than numbers from the managed pool, raise it with your account team.

Can one number ring a queue during the day and an AI agent after hours?

Not automatically. A route has no schedule — it is one number and one target. Use two numbers, or edit the route's target when your hours change; the route syncs again within seconds. See Inbound routing.

Does every agent need a human-agent entry?

No. Queue members take queue calls without one. You need a human-agent entry only when a number should ring one specific person directly. Even then, that person must be in an active queue's pool to have a softphone.

Which caller ID do the people we call see?

Outbound calls from the softphone use the caller ID set on your trunk by xMatix. With platform-managed voice, that is the first number allocated to your organization, and it stays the same when more numbers are added. The Outbound caller ID fields on numbers and human agents are recorded for reference and are not used to choose it. If calls show the wrong number, contact xMatix support.

What does an AI agent do when a caller asks for a person?

The agent transfers when the caller asks for a person, or asks something it cannot answer. It tells the caller it is connecting them, then dials the number in Transfer to into the same call. If you leave the field empty, it uses a default number that xMatix may have set for your deployment. When there is no number to dial, or the number is the one the caller rang, the agent apologises and offers to take a message. Fill in a staffed number with its country code, and make it a different number from the one routed to the agent.

Can I hide the telephony screens from most administrators?

Yes. The four configuration screens follow Manage telephony (CTI), so only profiles that hold it see them. The Settings switch follows Manage module settings. Keep Supervise telephony (CTI) similarly narrow, because its holders see every live call.

Related topics

• Inbound routing
• Queues and omni-channel routing
• Using the softphone
• The supervisor console
• Calls, dispositions and recordings
• Security profiles
• Troubleshooting telephony