Skip to content

Skills Routing

Skills Routing sends queued callers to agents whose skills match requirements set on the inbound call. Configure skills in the portal, enable Skills Routing on the queue, then use SmartPBX callflows to tag each caller before they enter the queue.

Individual Skills Routing vs Skills Group Routing

Both modes use the same Skills Routing toggle on the queue. The callflow decides which mode applies:

Individual Skills Routing Skills Group Routing
SmartPBX module CX Agent Skills CX Agent Skill Groups
Variables set One variable per skill: Agent_Skill_{name} One variable per priority group: Agent_Skill_Group_{N} (comma-separated skills)
What the caller needs A flat list of required skills Ranked groups — Group 1 is tried first, then Group 2, and so on
Agent must have All skills in the caller’s list All skills in the current group being tried
Dial behavior Match agents, then apply queue strategy (Single, Simultaneous, etc.) Dial every matching agent in the current group before advancing to the next group
Typical use “This caller needs Billing and English” — any qualified agent “Try BDA agents first; if none answer, try BSA; then BSS” — tiered fallback

Detection: If the call carries any Agent_Skill_Group_* variable, the queue uses Skills Group Routing. If only Agent_Skill_* variables are present, the queue uses Individual Skills Routing. Use one model per callflow branch.

Skills Routing works with any queue strategy (Single, Simultaneous, Weighted Random, and so on). It is disabled when an AI persona is assigned to the queue.

Setup overview

Complete these steps in order:

  1. Create skills on the Agent Skills page.
  2. Assign skills to users (agents) on each user profile.
  3. Enable Skills Routing on the queue and review per-agent skills on the queue Agents tab.
  4. Add skills in SmartPBX — use CX Agent Skills (individual) or CX Agent Skill Groups (priority groups) before the queue module.
flowchart LR
  A[Agent Skills page] --> B[User profile Skills]
  B --> C[Queue: Skills Routing ON]
  D[SmartPBX callflow] --> E[CX Agent Skills]
  D --> F[CX Agent Skill Groups]
  E --> G[Queue module]
  F --> G
  C --> G
  G --> H[Matching agents]

1. Create agent skills

In the admin portal:

Contact Center → Configuration → Agent Skills (/callcenter/config/agent_skills)

  1. Click Add (or open an existing skill).
  2. Set Name and Description.
  3. Choose Type:
  4. Regular — a single skill tag (for example Billing).
  5. Multilevel — a parent skill with child levels. Child names use dot notation (for example Language with children Language.English, Language.Portuguese).
  6. Save.

Skills defined here are available when assigning skills to users, queue agents, and SmartPBX callflow modules.

Naming

Use clear, stable names. SmartPBX CX Agent Skills publishes variables as Agent_Skill_{skill_name} (the skill name from this list).

2. Assign skills to users

Each agent needs the skills they can handle on their user record:

Users → Users (/users/list) → open the agent → Call Center section → Skills

  1. Select one or more skills from the multi-select list.
  2. Save the user.

These skills are stored on the user profile and used when the agent is a member of a queue with Skills Routing enabled. You can also refine skills per agent on the queue form (next section).

3. Enable Skills Routing on the Queue

Contact Center → Configuration → Queues (/callcenter/config/queues) → open the queue.

Turn on Skills Routing

Under Agent and routing toggles, enable Skills Routing.

When on, the queue dials only agents whose skills match the caller’s required skills (from the callflow). See CX Queues for other routing options.

Per-agent skills (Agents tab)

On the Agents tab, each queue member has an Agent Skills column:

Column Purpose
Agent Delay (s) Wait time before dialing this agent.
Agent Timeout (s) Ring time before trying the next agent.
Agent Skills Skills this agent offers for this queue when Skills Routing is on.

Assign the skills that agent should present while logged into this queue. If empty, routing falls back to skills from the user profile where applicable.

AI persona queues

Skills Routing, sticky agent routing, and manual agent selection are not used when an AI persona is set on the queue. See AI Agents.

4. Add skills in SmartPBX (callflow)

Inbound calls must carry required skills before they reach the queue. Configure that in SmartPBX (Monster UI callflows), typically on the DID or extension callflow that routes to the queue.

Open SmartPBX (/smartpbx) → Apps → Callflows → edit or create the inbound callflow.

In the Advanced category, add one of these modules before the Queue (or ring-group) step:

CX Agent Skills (Individual Skills Routing)

Use Individual Skills Routing when the caller needs a specific set of skills and any matching agent may answer.

  • Module: CX Agent Skills (SmartPBX Advanced category)
  • Select the skills the caller requires (multi-select).
  • At runtime the platform sets one custom application variable per skill: Agent_Skill_{skill_name}.

Example variables:

Agent_Skill_Billing = Billing
Agent_Skill_English = Language.English

Example callflow chain:

DID / Extension → Menu or logic → CX Agent Skills → Queue

A billing IVR branch might add CX Agent Skills with Billing and Language.English, then route to the support queue. Only agents who have both skills are eligible.

CX Agent Skill Groups (Skills Group Routing)

Use Skills Group Routing when callers should be matched in priority groups — the queue tries every matching agent in Group 1 before moving to Group 2, and so on.

  • Module: CX Agent Skill Groups (SmartPBX Advanced category)
  • Create one or more groups; each group lists multiple skills.
  • At runtime the platform sets Agent_Skill_Group_1, Agent_Skill_Group_2, … with comma-separated skill names per group.

Example variables:

Agent_Skill_Group_1 = Language.English,Department.BDA
Agent_Skill_Group_2 = Language.English,Department.BSA
Agent_Skill_Group_3 = Language.English,Department.BSS

Example callflow chain:

DID / Extension → Menu or logic → CX Agent Skill Groups → Queue

Individual Skills Routing

When the callflow sets only Agent_Skill_* variables (no Agent_Skill_Group_*), the queue uses Individual Skills Routing.

Matching rules

  • Customer skills are read from each Agent_Skill_{name} variable on the call.
  • An agent matches only when they have every required skill (on the user profile and/or queue Agents tab).
  • The queue strategy (Single, Simultaneous, Weighted Random, etc.) selects among all matching agents.

Per-call flow

flowchart TD
  A[Caller enters queue with Agent_Skill vars] --> B[Read required skill list]
  B --> C[Filter agents with all required skills]
  C --> D{Any agents match?}
  D -->|No| E[Caller waits in queue]
  E --> C
  D -->|Yes| F[Apply queue strategy]
  F --> G[Dial matched agent(s)]
  G --> H{Agent answers?}
  H -->|Yes| I[Call connected]
  H -->|No| J[Try next agent per strategy]
  J --> G
  1. Skill collection — The queue reads Agent_Skill_* from the call’s custom channel variables (excluding Agent_Skill_Group_* keys).
  2. Agent filtering — Only agents whose skill list includes all customer skills are candidates.
  3. Strategy — Single dials one agent at a time; Simultaneous may ring multiple matched agents; Weighted Random and other strategies apply among the matched set.
  4. No match — If no agent has the full skill set, the caller remains in queue until someone becomes available or timeout / next actions run.

Example

SmartPBX sets:

Agent_Skill_Billing = Billing
Agent_Skill_English = Language.English

Agents:

Agent Skills Matches?
Alice Billing, Language.English Yes
Bob Billing only No — missing Language.English
Carol Billing, Language.English, Language.Spanish Yes

Single caller, Single strategy:

  1. Filter to Alice and Carol
  2. Dial first matched agent (per strategy / order) → if no answer, try the other

Unlike Skills Group Routing, there is no Group 1 / Group 2 fallback — the caller’s skill list is fixed for the entire queue stay.

Skills Group Routing

When Skills Routing is enabled and the callflow sets Agent_Skill_Group_* variables, the queue service applies Skills Group Routing automatically.

Matching rules

  • An agent matches a group only when they have all skills listed in that group (on the user profile and/or queue Agents tab).
  • Group numbers are integers (1, 2, 3, …). Lower numbers are higher priority in the callflow definition, but runtime selection also balances load across groups (see below).

Per-call flow

flowchart TD
  A[Caller enters queue with Agent_Skill_Group vars] --> B[Assign target group]
  B --> C[Filter agents with all skills in that group]
  C --> D[Dial agents sequentially]
  D --> E{Agent answers?}
  E -->|Yes| F[Call connected]
  E -->|No| G{More agents in group?}
  G -->|Yes| D
  G -->|No| H{Other groups free?}
  H -->|Yes| I[Advance to next group]
  I --> C
  H -->|No| J[Stay on group and retry when agents free]
  1. Group assignment — The queue reads Agent_Skill_Group_* from the call’s custom channel variables and picks a target group for this caller.
  2. Agent filtering — Only idle agents who have every skill in the target group are candidates.
  3. Sequential dial — In typical Single strategy, the queue dials one agent at a time within the group. Failed or unanswered attempts move to the next matching agent in the same group.
  4. Group exhaustion — After every matching agent in the group has been tried (or is unavailable), the queue advances to the next group and repeats.
  5. Concurrent calls — When multiple callers are waiting, the queue tracks which groups are already in use so new calls can be steered to other groups where possible.

Example

Callflow defines:

Group Skills required
Group 1 Billing, English
Group 2 Billing, Spanish

Agents:

Agent Skills
Alice Billing, English
Bob Billing, English
Carol Billing, Spanish

Single caller:

  1. Target Group 1 → dial Alice → no answer
  2. Dial Bob → no answer
  3. Group 1 exhausted → switch to Group 2 → dial Carol

Stay vs switch when a group is exhausted

  • If another group has free agents, the caller moves to the next group.
  • If all other groups are busy with other callers, the queue may stay on the current group and retry matching agents when they become available (instead of skipping to an empty group).

CDR and reporting

The queue records skill-group progress on the call:

  • entered_skill_groups — groups the caller entered during routing
  • skill_group — the active group at connect time (group number and skills)

View these in Contact Center → Reports → Queues Calls (call detail / agent history) when skill routing was used.

Verification

  • Contact Center → Reports → Queues Calls — skill column and entered skill groups / skill group on call detail where enabled.
  • Confirm test calls use a callflow that sets skills before the queue module.
  • Confirm queue members have matching skills on the user profile and/or queue Agents tab.
  • For Individual Skills Routing, confirm the callflow uses CX Agent Skills and agents have all listed skills.
  • For Skills Group Routing, confirm the callflow uses CX Agent Skill Groups and that at least one agent has all skills in Group 1 before expecting a connect.