CloudCX Administrator & Training Manual

Contents

Table of Contents

This manual is organised into the chapters listed below. Use the chapter and section numbers (for example § 7.4) as the stable cross-reference throughout — printed page numbers depend on your browser’s print engine and zoom.

CloudCX Administrator & Training Manual

Ch. 01 · Welcome

Welcome and how to use this manual

This is the official handbook and training course for CloudCX, the multi-tenant omnichannel contact-centre-as-a-service (CCaaS) platform. It teaches you to operate the platform control plane — the dark admin console at admin.cloudcx.app — from the very first sign-in through the day-two routines that keep resellers, tenants, channels and the voice fabric healthy. This first chapter explains who the book is for, the platform → reseller → tenant → user hierarchy that every later chapter assumes, and the conventions — callouts, screen mockups, numbered steps and Try-it exercises — the rest of the manual uses. Read it once; refer back to it whenever a later chapter’s notation is unclear.

1.1 Who this manual is for

CloudCX is operated by a small number of trusted people with broad authority. The book is written for two overlapping readers, and most chapters serve both:

You do not need to be a developer to use this manual. You should, however, be comfortable with the vocabulary of a contact centre — queues, agents, DIDs, IVR, SLAs — and willing to work carefully, because actions taken in the admin console affect every customer on the platform. A short glossary of the terms used throughout appears in the appendix; the first time each term is used in a chapter it is briefly defined in place.

CloudCX Administrator & Training Manual

Ch. 02 · Platform overview

CloudCX platform overview & architecture

Before you provision a single reseller or route a single call, it pays to understand what CloudCX is and how its pieces fit together. This chapter is the mental model the rest of the manual builds on: the multi-tenant hierarchy you administer, the omnichannel queue every customer conversation flows through, and the planes — voice, application, data, channels and AI — that make it all run.

Read this as an administrator, not an engineer: you do not need to operate CloudCX SBC or CloudCX Switch by hand to run CloudCX well. But knowing which moving part does what will make every later chapter — trunks, ACD, channels, billing, security — click into place, and it will make you far faster when something needs diagnosing.

2.1 What CloudCX is

CloudCX is a multi-tenant, omnichannel Contact-Center-as-a-Service (CCaaS) platform. In plain terms: it is one cloud that lets many separate businesses each run a complete contact centre — phones, web chat, WhatsApp, SMS, email and social — without owning any telephony hardware, while you, the platform operator, run and monetise the whole thing from a single console at admin.cloudcx.app.

Two ideas distinguish CloudCX from a hosted PBX or a chat widget:

• It owns the call path. Carriers connect over SIP trunks that the platform controls — there is no third-party CPaaS sitting in the middle of every call. Routing logic, recording and margin stay on your infrastructure.
• It is a full contact centre, not a feature. Skills-based ACD and a visual IVR / call-flow designer; preview, progressive and predictive dialers; live supervision (monitor / whisper / barge); QA scorecards; recording, transcription and sentiment on every interaction; and a custom report builder.

On top of that sits the commercial engine that makes CloudCX a platform rather than a single deployment: a white-label reseller tier, a per-feature, per-count licensing/entitlement engine, and built-in billing. Those three are what you spend most of your administrator time configuring, and they are the subject of Parts II and VIII.

CloudCX Administrator & Training Manual

Chapter 03 · Signing in & the console

Signing in and a tour of the admin console

This chapter takes you from a cold browser to a confident command of the CloudCX control plane. You will sign in for the first time, harden your own account with two-factor authentication (an authenticator app or emailed sign-in codes), learn how to recover a forgotten password, and then take a guided, fully annotated tour of every region of the console — the dark navigation rail, the light working area, and the controls you will reach for dozens of times a day.

3.1 Before you sign in

Account creation is not self-service at the platform tier. Your platform-administrator credentials are issued to you by CloudCX (or by an existing super-admin during onboarding, covered in Chapter 2). You will be given a username (or you may sign in with your email address) and an initial password. Have the following ready before you start:

• Your username or email and the password you were issued.
• A modern browser (Chrome, Edge, Firefox or Safari, kept up to date). The console is a single-page app and stores your session token in the browser’s local storage.
• If your organisation enforces an IP allow-list (see Chapter on Security), make sure you are on an approved network or VPN — otherwise the sign-in request will be refused before it ever reaches the login form.
• An authenticator app on your phone (Google Authenticator, 1Password, Authy or any RFC 6238 TOTP app) if you intend to turn on two-factor authentication in § 3.4 — which we strongly recommend.

3.2 The sign-in screen

When you open the console without an active session, the entire window is dimmed behind a centred sign-in card. Nothing else in the application is reachable until you authenticate — this is the login gate.

3.2.1 Signing in step by step

1. Open the console. Navigate to admin.cloudcx.app. If you do not already have a live session, the sign-in card appears automatically.
2. Enter your username or email. Type the identifier you were issued into the first field. It is not case-sensitive for email.
3. Enter your password in the second field.
4. Select Enter or click Sign in. The button shows Signing in… while it works.
5. Land on the Dashboard. On success the gate disappears and the Platform overview (Dashboard) loads. Your session token is stored in the browser so you stay signed in across page reloads until you sign out or the token expires.

3.3 Worked example — your first sign-in

Suppose you are Sofia Aranha, a newly onboarded platform super-admin. CloudCX has issued you the email [email protected] and a temporary password.

1. Go to admin.cloudcx.app. The sign-in card appears.
2. Type [email protected] into Username or email.
3. Type the temporary password into Password.
4. Click Sign in. The Dashboard loads, and the top-right corner now shows your identity chip — the avatar SA, the name S. Aranha, and the role SUPER-ADMIN — read live from your account.
5. Immediately do two things: change your temporary password (use the Security view or your account profile), and enrol a second factor as described next in § 3.4. A platform super-admin account is the highest-value credential in the system; treat it accordingly.

CloudCX Administrator & Training Manual

Ch. 4 · Roles & Access

Roles and the access model

Everything an account can see, change, or be billed for in CloudCX flows from a single decision: what type of login is this, and which slice of the platform does it own? This chapter is the canonical reference for the six login types, the three-tier tenancy hierarchy that contains them, and the row-level isolation model that keeps one customer’s data invisible to every other customer. Get this right and the rest of the manual — billing, channels, supervision, security — falls into place.

4.1 The six login types at a glance

Every person (and every machine token) that signs in to CloudCX is a single User record carrying one user type. There are exactly six, and they never change at runtime — a login is created as a type and stays that type for its life. The type, together with two optional ownership pointers (tenant_id and reseller_id), is the only thing the platform consults when it decides what you may touch.

4.2 The tenancy hierarchy

CloudCX is multi-tenant by construction. The platform is divided into three nested tiers of ownership. Each tier can only ever reach down into the tier it contains — never sideways to a sibling, and never up to its parent.

Two ownership pointers wire this together on every User row:

A Tenant itself also carries a reseller_id: when set, the tenant belongs to that reseller (white-label); when NULL, it is a direct platform customer that you, the admin, manage yourself. This single column is what lets a reseller see “their” tenants and nobody else’s.

CloudCX Administrator & Training Manual

Ch. 5 · Resellers

Resellers — create, brand, entitle, white-label

A reseller is the white-label partner tier that sits between you (the platform) and the enterprise customers who actually use CloudCX. A reseller resells the platform under its own brand, sells to its own customers (tenants), prices them with its own plans, and — where you permit it — connects its own carriers and channel providers. This chapter shows you how to create a reseller, brand it, set its entitlement caps, switch on its “bring-your-own” connectivity, and what the partner then sees inside their own white-label console.

5.1The reseller in the tenancy hierarchy

CloudCX is a strict three-level tenancy: Platform Admin → Reseller → Tenant. You operate the platform; a reseller operates a book of business on top of it; each tenant is one enterprise customer with its own agents, numbers and channels. Every object a reseller can touch is scoped to its own reseller_id, so one partner can never see or modify another partner’s brand, customers or billing.

A reseller record carries four kinds of data. Keep them straight — the rest of the chapter is organised around them:

CloudCX Administrator & Training Manual

Ch. 06 · Tenants

Tenants — create, configure, license

A tenant is a single business customer running its own contact centre on CloudCX — its own agents, numbers, queues, channels and data, fully isolated from every other tenant. This chapter shows you how to create a tenant from the platform console, configure its core identity, understand how seat and feature limits are licensed and enforced, and read the live entitlement counters. It closes with a fully worked provisioning example and a hands-on Try-it exercise.

6.1 The Tenants workspace

Open the console at admin.cloudcx.app, sign in with your platform-administrator account, and select Tenants in the dark sidebar under the Tenancy group. This is the platform-wide book of every enterprise customer — those belonging to resellers and those you sell to directly. The list is loaded live from GET /api/v1/tenants and ordered newest-first.

Use the breadcrumb chip below as your map for the procedures in this chapter:

Tenancy›Tenants›Add tenant

6.2 Creating a tenant

Click Add tenant to open the create form. A tenant needs only four things to come to life: a display name, a unique login username, a contact email, and the password for its first login. An optional dial prefix can be set now or later. When you save, CloudCX does two things in one transaction: it creates the tenant record, and it bootstraps the tenant’s primary login (a user of type tenant) using the username, email and password you supplied.

6.2.1 Field reference

The create form maps directly onto the POST /api/v1/tenants request body. Each field, its constraints and how CloudCX uses it:

6.2.2 Step by step: create a tenant

1. Open the form. From Tenancy›Tenants click Add tenant (top-right).
2. Enter the company name. Type the customer’s display name, e.g. Northwind Logistics.
3. Choose a unique username. Use a lower-case, hyphenated handle such as northwind-log. If it is already taken anywhere on the platform you will be told on save.
4. Set the contact email. Enter a real, monitored mailbox — password-reset and verification mail go here.
5. Set a strong initial password. It must satisfy the platform password policy (see Chapter 3 / Security). Communicate it to the customer over a secure channel.
6. Optionally set a dial prefix. Add an outbound prefix only if this customer needs one; otherwise leave it blank.
7. Create. Click Create tenant. On success the tenant appears at the top of the list with status Active and the primary login is live.
8. Verify. Confirm the new row, then refresh the Tenants badge and the dashboard Tenants KPI — both should increment by one.

6.2.3 What can go wrong

6.3 Seat & feature limits — how licensing works

CloudCX gates commercial capacity with a per-count entitlement engine. Every limit is a single number, and the platform follows one golden rule throughout:

6.3.1 Where caps live

A scope is the entity a limit applies to. Today, caps are stored on the reseller row, so every tenant inherits its head-room from its parent reseller. Three numeric caps drive tenant capacity:

The platform scope (a tenant created directly, with no reseller) has no stored caps today, so its limits resolve to unlimited. The enforcement gate is nonetheless wired into the create path, so the moment a platform-level cap is ever stored it will start blocking automatically — no code change required.

6.3.2 The full feature catalogue

The engine recognises a broad catalogue of licensable features — mirroring the reference license dashboard — even though only the three caps above are stored as numbers today. The rest resolve to unlimited until a cap is configured, so they never block spuriously. Knowing the catalogue helps you read the entitlement panel and anticipate future metering.

6.3.3 What happens at the cap

The gate is checked before the work is done. When you (or a reseller) try to add a tenant or seat that would exceed a stored cap, the request is refused cleanly and nothing is created:

If the tenant_limit check fails, the API returns 409 Conflict with a message such as “Customer limit reached for this reseller” (reseller path) or the engine’s detail “License limit reached for ‘tenant_limit’: used N + requested 1 > allotted N”. The same pattern protects agent-seat creation against agent_sessions.

6.4 Reading entitlements & usage

CloudCX makes the entitlement engine observable. The platform Licensing view (sidebar → Revenue → Licensing) shows the platform-wide picture; each reseller and tenant portal shows its own scope. Behind it, GET /api/v1/admin/platform/entitlements returns an entitlements summary: headline used counts plus a per-feature row of allotted / used / unlimited / remaining.

The summary payload is small and self-describing. Read the per-feature rows like this:

// platform scope — no stored caps today, so allotted = 0 (unlimited)
{
  "scope": "platform",
  "customers_used": 86,        // live tenant count
  "agents_used": 512,          // agent + tl users, platform-wide
  "entitlements": [
    { "feature":"tenant_limit",    "allotted":0, "used":86,  "unlimited":true,  "remaining":null },
    { "feature":"agent_sessions",  "allotted":0, "used":512, "unlimited":true,  "remaining":null }
  ]
}

For a reseller scope the shape is identical but the numbers bite: allotted carries the stored cap and remaining is allotted − used (never negative). That is how the reseller portal renders headlines like “12 / 50 customers”.

6.5 Worked example — provision “Northwind Logistics”

A reseller, Acme Comms, has just signed a new end-customer, Northwind Logistics, and asked you to stand up their tenant. Acme is licensed for 50 customers and currently has 49. Follow the flow end-to-end.

6.5.1 1 — Check the head-room

1. Open Licensing. Go to Revenue›Licensing and locate Acme Comms in Licensed seats by reseller. Confirm its customer line reads 49 / 50 — exactly one slot free.
2. Decide. One free slot is enough for one tenant. (If it read 50 / 50, you would first raise Acme’s max_customers in Chapter 5 → Resellers → Entitlements, otherwise the create would 409.)

6.5.2 2 — Create the tenant

Because Northwind belongs to a reseller, the cleanest path is for Acme to create it from its reseller portal (which forces the new tenant under Acme and enforces max_customers automatically). As platform-admin you can also create it here; if you do, remember to set its owning reseller so it counts against Acme’s cap. Either way the field values are the same:

1. Fill the form with the values above and a strong initial password, then click Create tenant.
2. Read the result. A 201 means success: the tenant row and its primary tenant login both exist. The console drops Northwind Logistics at the top of the Tenants list as Active.

{
  "id": "e7c1…a93f",
  "name": "Northwind Logistics",
  "username": "northwind-log",
  "email": "[email protected]",
  "status": "active",
  "dial_prefix": "9",
  "created_at": "2026-06-15T09:42:11Z"
}

6.5.3 3 — Confirm the meters moved

1. Re-open Licensing. Acme’s customer line now reads 50 / 50 — the create consumed the last slot.
2. Test the cap. Try to add a 51st tenant under Acme; CloudCX refuses with 409 “Customer limit reached for this reseller”. That is the entitlement engine working as designed.
3. Resolve (if needed). To let Acme grow, raise max_customers (Resellers → Entitlements). The very next create will succeed — no restart, no migration.

6.6 Recap

• A tenant is an isolated business customer; create it from Tenancy → Tenants → Add tenant.
• Four required fields — name, username, email, password — plus an optional dial prefix; saving also bootstraps the tenant’s primary login in one transaction.
• Username is unique platform-wide (409 on clash); the password is policy-checked (422) before anything is written.
• Seat & feature limits follow 0 = unlimited; the stored caps (max_customers, max_agents, max_channels) live on the reseller; platform-direct tenants are uncapped today.
• Caps are enforced at create time — over the limit returns 409; lowering a cap freezes new creates but never evicts existing tenants.
• The Licensing view and the entitlements summary expose live allotted / used / remaining per feature — usage is always a real DB count.

CloudCX Administrator & Training Manual

Ch. 07 · Users & Security

Users, teams, skills and per-user security

Everyone who signs in to CloudCX — you, your resellers, every tenant administrator, every team lead and every front-line agent — is a typed user account. This chapter is the operator’s guide to that directory: how the account types fit the platform hierarchy, where each kind of user is created, how to give agents the skills that route work to them, and how to harden sign-in with a password policy and two-factor authentication. It ends with a full worked example — standing up a supervisor and two skilled agents from scratch — and a Try-it exercise.

7.1 The six account types

Every login is a row in the platform users table with one user_type. The type fixes what the account can see and do, and which slice of the tenant tree it is scoped to. There are exactly six types:

Two phrases recur throughout this manual, so fix them now. A supervisor is a tl (team-lead) account — the words are interchangeable. An agent is an agent account. Skills-based routing (Chapter 8) only ever delivers interactions to agent and tl users, never to administrators.

7.2 The platform account directory

Open the console at admin.cloudcx.app, sign in as a platform administrator, and choose Security in the dark sidebar under the Governance group. The top of this view is the Platform accounts roster — every login the platform knows about, fetched live from GET /api/v1/users and shown newest-first.

Governance›Security›Platform accounts

7.3 Creating agents and supervisors

Agents and supervisors are created one tier down from the platform — by a reseller for its own team, or by a tenant administrator for the contact-centre staff. The mechanics are the same everywhere: a username, an email, a starting password (which must satisfy the platform password policy — § 7.5), and a role. The role you pick becomes the new account’s user_type.

7.3.1 Roles a reseller may assign

A reseller manages its team from the reseller portal’s Team panel (/reseller → Team), backed by GET /api/v1/reseller/team and POST /api/v1/reseller/team. A reseller is deliberately restricted to two roles for its own staff:

• Reseller — another administrator for the reseller’s brand (user_type = reseller).
• Agent — a front-line user (user_type = agent).

A reseller can never mint a platform admin, a tenant, a sub-tenant or a team-lead login — the server forces the new account’s reseller_id to the caller’s own reseller and rejects any role outside {reseller, agent} with 422. Team leads (supervisors) are created inside a tenant, not in the reseller team panel; see § 7.3.3.

7.3.2 Procedure — add a team member (reseller)

1. Open the Team panel. Sign in to the reseller portal and select Team. The list shows every user whose reseller_id is yours, newest-first.
2. Click Add team member. A short form appears with four inputs: Username, Email, Password and Role.
3. Enter the username. 3–128 characters, unique within your scope. This is what the person types to sign in.
4. Enter the email. A valid address is required — it is used for display, password resets and (optionally) email sign-in codes.
5. Set a starting password. It must satisfy the active password policy (§ 7.5). A violation returns 422 with a message listing exactly what is missing.
6. Choose the role. Agent for a front-line user, or Reseller for another brand administrator. (Defaults to Agent.)
7. Create. CloudCX hashes the password (Argon2), forces the new account onto your reseller, and adds the row. The account is active immediately. A duplicate username returns 409.

7.3.3 Agents and supervisors inside a tenant

Within a tenant, the staff directory is richer: a tenant (or sub-tenant) administrator creates agents and team leads (supervisors) for the contact centre. The account types are the same six from Table 7.1 — you pick Agent for a handler and Team lead for a supervisor who will monitor, whisper and barge (see Chapter 11 on supervision). Programmatically, every account is created through the platform user API:

Create a supervisor (team lead) under a tenant
POST /api/v1/users
# body
{
  "username": "maria.santos",
  "password": "Wint3r!Garden42",
  "user_type": "tl",            # tl = team lead / supervisor
  "email": "[email protected]",
  "tenant_id": "<northwind-tenant-id>",
  "first_name": "Maria",
  "last_name": "Santos"
}

Swap "user_type": "tl" for "agent" to create a front-line agent instead. The new account inherits the tenant’s scope from tenant_id, so it can only ever see that tenant’s data. The starting password is validated against the platform policy exactly as in the portal flow.

7.4 Skills — tag agents so the right work reaches them

A skill is a named competency — Billing, Spanish, Tier-2 Support, VIP — that you attach to agents at a proficiency level. Queues then require a skill at a minimum level, and the ACD only routes an interaction to an agent who holds every required skill at or above that level. This is skills-based routing; the routing engine itself is Chapter 8. Here we cover the three building blocks an administrator manages.

The three building blocks, with their endpoints, are:

7.4.1 Create a skill

Skills are managed under the ACD. Create one with a clear, reusable name — you will assign it to many agents and reference it from many queues:

Create the “Billing” skill
POST /api/v1/acd/skills
{ "name": "Billing", "description": "Invoices, refunds, payment disputes" }

# 201 Created
{ "id": "3f2a…", "tenant_id": "<tenant>", "name": "Billing", "description": "Invoices…" }

When a tenant or reseller administrator creates a skill, it is automatically stamped with their own tenant_id — you cannot create a skill in someone else’s tenant. A platform admin may target any tenant, or leave tenant_id NULL to create a shared platform-level skill.

7.4.2 Assign a skill to an agent (with a level)

Granting a skill to an agent records a proficiency level — a positive integer where higher means more capable. A common convention is 1 = trained, 3 = proficient, 5 = expert, but the scale is yours; what matters is consistency with the min level you put on queues.

1. Open the skill. Under the ACD, choose Skills and open the skill you want to staff (for example Billing).
2. Click Assign agent. Pick the agent or team lead from the tenant’s roster.
3. Set the proficiency level. Enter an integer of 1 or more. Choose it deliberately — it is the value queues test against.
4. Save. CloudCX records the (agent, skill, level) grant. Each agent may hold a skill only once, so re-adding the same skill returns 409 — remove and re-add to change the level.

Grant Billing at level 3 to an agent
POST /api/v1/acd/agents/<james-user-id>/skills
{ "skill_id": "3f2a…", "level": 3 }     # level defaults to 1 if omitted

7.4.3 Require a skill on a queue

Finally, tell a queue which skills it demands. A queue may require several skills, each with its own min level; an agent must clear every requirement to be eligible. Attach a required skill with:

Require Billing at min level 2 on the Billing queue
POST /api/v1/acd/queues/<billing-queue-id>/skills
{ "skill_id": "3f2a…", "min_level": 2 }    # min_level defaults to 1

With the example numbers, James (Billing 3) and Maria (Billing 5) clear the queue’s min 2, but Anya (Billing 1) does not — she will not be offered Billing interactions until her level is raised. You can confirm staffing live at GET /acd/queues/{id}/stats, which reports the queue’s member count, how many are available right now, and its required skills.

7.5 Password policy (platform-wide)

The password policy is a single platform-wide rule that every new password is checked against — reseller team members, tenant and reseller bootstrap logins, and any password change. You edit it from the platform console under Security → Password policy, backed by GET/PUT /api/v1/admin/platform/security/password-policy. The defaults are deliberately permissive (minimum length 8, no character-class requirements) so nothing breaks before you opt in.

1. Open Security → Password policy. The panel loads the current rule (or permissive defaults if none has been saved).
2. Set a minimum length. A practical floor is 10–14. The value is bounded 1–128 (a minimum above 128 would make every password impossible, since password fields cap at 128).
3. Turn on the classes you want. Each toggle adds a requirement: at least one uppercase, lowercase, digit, or symbol (a symbol is any non-alphanumeric, including space).
4. Save the policy. It takes effect immediately for the next password set anywhere on the platform.

7.6 Two-factor authentication and email sign-in codes

CloudCX supports two opt-in second factors, both off by default so that turning them on never disturbs anyone who has not enrolled. From Security → Two-factor authentication you manage the second factor on your own signed-in account; every account holder manages their own from their respective console.

• Authenticator (TOTP) — a time-based 6-digit code from an app such as Google Authenticator, 1Password or Authy.
• Email sign-in codes — a one-time code emailed at sign-in (an alternative for users without an authenticator app). TOTP takes precedence if both are somehow enabled.

7.6.1 Enrolling in TOTP two-factor

The panel walks through three states — enroll (scan a secret), activate (confirm a code, receive backup codes) and enabled. Behind them sit three endpoints: POST /auth/mfa/enroll, POST /auth/mfa/activate and POST /auth/mfa/disable.

1. Click Enable 2FA. CloudCX generates a fresh secret and shows it as a QR / otpauth deep link, plus the raw secret and URI for manual entry. This does not turn 2FA on yet.
2. Add it to your authenticator. Scan the code (or type the secret) into Google Authenticator, 1Password, Authy or similar. The app starts showing a rolling 6-digit code.
3. Enter a current code and Activate. CloudCX verifies it against the pending secret. On success, 2FA is now on and you are shown 10 one-time backup codes in the format XXXXX-XXXXX.
4. Save your backup codes. They are displayed once and never again — only their hashes are stored. Keep them somewhere safe; each lets you sign in once if you lose your authenticator.
5. Confirm. Click “I’ve saved my codes.” The panel now reads Enabled ✓. Future sign-ins will ask for a code.

7.6.2 Signing in with 2FA, and turning it off

Once enabled, the sign-in flow asks for a second factor after the password is accepted. Supply a current TOTP code (or, in a pinch, an unused backup code) in the code field. If you omit it, the API replies 401 mfa_required so the console knows to prompt; a wrong code returns 401 Invalid 2FA code. Email sign-in codes work the same way, challenging with otp_required and delivering the code by email.

To turn 2FA off, open the panel (it shows Enabled ✓), enter a current 6-digit code, and click Disable 2FA. CloudCX verifies the code (a backup code also works), then clears the secret and all backup codes. The account returns to single-factor sign-in.

7.7 Deactivating, locking and re-activating users

An account’s lifecycle is governed by its status, which has three values:

The most common operation — a leaver, or a contractor between shifts — is to deactivate rather than delete. Deactivating preserves all of the account’s history (CDRs, conversations, QA scores) while immediately barring sign-in. In a reseller’s Team panel this is the Active toggle (a one-click flip via PATCH /reseller/team/{id} with {"active": false}); for tenant staff the same status field is set to inactive.

1. Find the account. Locate the user in the relevant Team / Agents list (or confirm it on the platform Security roster).
2. Deactivate. Turn the Active toggle off (or set status = inactive). The change is immediate: any new sign-in is refused with 403 User is not active.
3. Verify. The status pill flips to inactive on the roster. Existing tokens expire on their normal schedule; the account cannot obtain new ones.
4. Re-activate when needed. Flip the toggle back on (status = active) to restore access — no re-creation, no lost history.

7.8 Worked example — stand up a billing team

Northwind Care, a tenant under the Acme Comms reseller, is opening a billing line. As the administrator you will: create a supervisor and two agents, build the Billing skill, grade the agents, require the skill on the Billing queue, harden the password policy, and turn on 2FA for the supervisor. Follow it end-to-end.

1. Tighten the password policy first. Under Security → Password policy, set Minimum length 12 and turn on uppercase, lowercase and digit. Save. Every account you create next must meet this bar.
2. Create the supervisor (team lead). Provision maria.santos as a tl in the Northwind tenant with password Wint3r!Garden42 (12+ chars, mixed case, a digit — it passes).
3. Create two agents. Provision james.lee and priya.raman as agent in the same tenant, each with a policy-compliant password.
4. Create the Billing skill. POST /acd/skills with name Billing. Note its returned id.
5. Grade the team. Grant Billing to Maria at level 5, James at level 3, and Priya at level 1 (still onboarding).
6. Require the skill on the queue. On your Billing queue, add required skill Billing at min level 2.
7. Staff the queue. Add Maria, James and Priya as queue members (POST /acd/queues/{id}/members).
8. Protect the supervisor. Have Maria sign in and enrol her account in 2FA, saving her 10 backup codes.
9. Verify routing eligibility. Call GET /acd/queues/{id}/stats. Maria and James clear min 2; Priya (level 1) does not — she is a member but not yet eligible for Billing work.

The skill calls, in order
# 4 — create the skill
POST /api/v1/acd/skills            { "name": "Billing" }            # -> id 3f2a…

# 5 — grade the three users
POST /api/v1/acd/agents/<maria>/skills   { "skill_id": "3f2a…", "level": 5 }
POST /api/v1/acd/agents/<james>/skills   { "skill_id": "3f2a…", "level": 3 }
POST /api/v1/acd/agents/<priya>/skills   { "skill_id": "3f2a…", "level": 1 }

# 6 — require it on the queue, min level 2
POST /api/v1/acd/queues/<billing-q>/skills  { "skill_id": "3f2a…", "min_level": 2 }

# 9 — confirm staffing
GET  /api/v1/acd/queues/<billing-q>/stats
# -> { members: 3, available_now: 2, required_skills: [{ skill_id: 3f2a…, min_level: 2 }] }

Result. The Billing queue is staffed by three members, two of whom are immediately eligible. When Priya finishes onboarding, remove and re-add her Billing grant at level 2 (or higher) and she joins the eligible pool with no other change. Maria’s sign-in is now protected by a second factor, and every account was forced to meet the stronger password policy at creation.

7.9 Recap

• Every login is a typed account — admin / reseller / tenant / subtenant / tl / agent — and each tier creates the tier below it.
• The platform Security roster is the read-only book of all accounts; agents and supervisors are created in the reseller portal and tenant consoles (a supervisor is a tl).
• Skills have three parts: create a skill, grant it to agents at a level, and require it on a queue at a min level — routing needs both membership and skill eligibility.
• The platform-wide password policy (length + character classes) gates every new password; existing ones are untouched until changed.
• Two-factor (TOTP or email codes) is opt-in and self-service; backup codes are shown once — protect your own admin account first.
• Deactivate (inactive) rather than delete to bar sign-in while preserving history and skill grants; re-activation is one click.

CloudCX Administrator & Training Manual

Ch. 08 · Numbers, Trunks & LCR

Numbers, SIP trunks and carriers, and LCR

Every voice interaction on CloudCX crosses a carrier. Inbound, a customer dials one of your DIDs (the numbers you own) and the platform routes the call to a flow, queue, extension or mailbox. Outbound, the dialer hands the call to a SIP trunk — an outbound carrier — chosen by your least-cost-routing (LCR) rules. This chapter covers the whole Call Routing workspace: managing the inbound DID inventory, registering a SIP carrier, writing LCR rules that pick the cheapest matching trunk per destination prefix, and reading the review-only SBC config the platform generates for each trunk. It closes with a fully worked carrier cut-over and a hands-on Try-it exercise.

8.1 Opening the Call Routing workspace

Open the console at admin.cloudcx.app, sign in with your platform-administrator account, and select Call Routing in the dark sidebar under the Platform group. The page brings four things together on one screen: the live ACD queues and inbound DIDs that decide where a call lands, and the SIP carrier trunks plus least-cost routing that carry outbound traffic.

Use the breadcrumb chip below as your map for the procedures in this chapter:

Platform›Call Routing›SIP carrier trunks

8.2 The inbound DID inventory

A DID (Direct Inward Dialing number) is a phone number a tenant owns. When a customer calls it, the inbound engine looks the dialled number up and routes the call to its configured destination. Every DID is tenant-scoped: a tenant user sees only their own numbers; a platform administrator sees all of them. Writes are admin-gated, so creating, editing or removing a DID requires an administrator.

On the Call Routing screen the Inbound DIDs panel is a read-only roster — it shows the number, its name, its destination and whether it is live. To add or edit a DID you use the dedicated Numbers view inside the IVR Builder, reached from Voice › IVR Builder › Numbers. Both surfaces talk to the same /dids API.

8.2.1 A DID’s four routing destinations

Each DID carries a destination_type and a destination_ref. The type chooses what kind of thing answers; the ref points at the specific one:

8.2.2 Adding a DID

1. Open the Numbers view. Go to Voice › IVR Builder › Numbers and click + Add DID.
2. Enter the number. Type the DID exactly as the carrier presents it inbound (E.164 is safest, e.g. +6531581200). This is the string the inbound engine matches a call against, so it must match what arrives on the trunk.
3. Name it. Give a human label such as SG main line — this is what appears in the roster and in reports.
4. Choose the destination type from flow, queue, extension or voicemail (Table 8.1).
5. Set the reference. For flow and queue the modal lets you pick from a live list; for extension and voicemail you type the target. Only a published flow can serve calls, so publish first (Chapter 7).
6. Leave Active on (the default) so the number routes immediately, then Save. A 201 adds the row; the platform stamps it onto the current tenant (a platform admin can target a specific tenant).

8.3 SIP carrier trunks

A SIP trunk is an outbound carrier the platform can route a call over. Each trunk is one row holding the gateway address, optional SIP authentication, transport and codec preferences, and a channel cap. Critically, the trunk’s name doubles as the CloudCX Switch CloudCX Switch gateway name — the dialer routes through byondswitch/gateway/<name>/<number> — so the name is restricted to a safe gateway charset (letters, digits and . _ - only; no spaces or metacharacters).

8.3.1 Trunk scope: platform, reseller or tenant

Every trunk (and every LCR rule) carries two optional owners, which together set its scope:

At call time a tenant call considers its own trunks plus the platform-shared ones; a reseller call considers its own plus platform-shared. A tenant can therefore never route over another tenant’s carrier, yet you can still offer a shared CloudCX wholesale trunk as a default. As a platform administrator you set the owner when you create the trunk; a self-provisioning reseller’s trunks are always pinned to that reseller.

8.3.2 The trunk form, field by field

From the Call Routing screen, click + Add trunk in the SIP carrier trunks panel. The form opens inline. Most fields are optional — only Name and Gateway host are required.

8.3.3 Procedure — register a carrier

1. Open the form. On Call Routing, click + Add trunk.
2. Name the trunk with a safe, descriptive gateway name — e.g. primary-carrier. Remember this becomes the gateway your dial strings reference.
3. Enter the gateway host (and port if not 5060) from your carrier’s SIP details.
4. Choose the authentication model. For an IP-authenticated trunk leave Username/Password blank and Register off. For a registration trunk, enter Username + Password and turn Register on.
5. Set transport and codecs to match the carrier (e.g. udp + OPUS,PCMU,PCMA), and set Max channels to your contracted concurrency (or leave 0 for unlimited).
6. Confirm Enabled is on and click Save trunk. A 201 adds the row to the trunk list and to the LCR Trunk dropdown. The carrier is not yet carrying calls — you still need an LCR rule (§ 8.4) and the SBC gateway installed (§ 8.5).

A saved trunk renders as one row: a green dot when enabled (grey when disabled), the name, and a monospace meta line of host:port · TRANSPORT · register|IP auth, followed by its channel cap (“30 ch” or “no cap”), an enabled / disabled pill, and three row actions: view config, edit and delete.

8.4 Least-cost routing (LCR)

With trunks registered, least-cost routing decides which trunk carries each outbound call. An LCR rule maps a destination prefix (the leading digits of the dialled number) to a trunk, with a priority and an optional per-minute cost. At call time the platform evaluates the rules in scope and picks the best matching trunk.

8.4.1 How a trunk is chosen

The dialled number is normalised to digits, then candidate rules (those in the call’s scope whose trunk is enabled) are ranked. Selection follows this order:

1. Prefix match. Keep only rules whose destination_prefix is a leading prefix of the dialled digits. The empty prefix “” is a catch-all that matches everything.
2. Longest prefix first. The most specific prefix wins — 6597 beats 65 beats the catch-all for a Singapore mobile.
3. Most-specific scope. Among equal-length prefixes, the call’s own tenant/reseller rule beats a platform-shared one.
4. Lowest priority value. Then the lowest priority number wins (lower = preferred).
5. Lowest cost, then newest. Then the lowest per_minute_cost (rules without a cost rank after those with one), and finally the most recently created rule.

The winning rule’s trunk supplies the CloudCX Switch gateway name for the byondswitch/gateway/<name>/<number> dial string. If that trunk is missing or disabled, or its name fails the safe-charset check, selection yields nothing and the call falls back to the default gateway — never a broken dial string.

8.4.2 The LCR rule form

In the Least-cost routing panel, click + Add rule.

8.5 The review-only generated config

Provisioning a trunk records its details; it does not touch your SBC. To install the gateway you ask CloudCX to generate the config text for the trunk, review it, and apply it on the SBC yourself. Click the view config action (⟨⟩) on a trunk row to open the config viewer.

The viewer calls GET /admin/telephony/trunks/{id}/config and shows two blocks for the same trunk:

• A CloudCX Switch <gateway> XML block — drop it in as conf/sip_profiles/external/<name>.xml (or inside the external profile’s <gateways>), then run CloudCX Switch service external rescan.
• An equivalent CloudCX SBC snippet — a dispatcher.list next-hop line, plus (for a registration trunk) a uacreg row for outbound REGISTER.

Because the operator needs a working gateway, the real SIP password is embedded in this text (decrypted only here) — which is exactly why the endpoint is admin-gated. If the password cannot be decrypted (no key, or none stored) the config emits the placeholder <SET_PASSWORD_ON_SBC> so the text is obviously incomplete rather than silently wrong.

# ============================================================
# Generated SBC gateway config for trunk 'primary-carrier'
#   host=sip.carrier.com:5060 transport=udp
#   REVIEW ONLY — apply manually on the SBC.
# ============================================================

<!-- CloudCX Switch CloudCX Switch gateway for SIP trunk primary-carrier -->
<gateway name="primary-carrier">
  <param name="username" value="byond-sg"/>
  <param name="password" value="s3cr3t-from-vault"/>
  <param name="auth-username" value="byond-sg"/>
  <param name="realm" value="sip.carrier.com"/>
  <param name="proxy" value="sip.carrier.com:5060"/>
  <param name="register" value="false"/>
  <param name="transport" value="udp"/>
  <param name="codec-prefs" value="OPUS,PCMU,PCMA"/>
</gateway>

# CloudCX SBC edge SBC config for SIP trunk primary-carrier
# dispatcher.list (reload: kamcmd dispatcher.reload)
# 1 sip:sip.carrier.com:5060;transport=udp 0 0 name=primary-carrier

8.6 Worked example — cut Singapore mobile traffic to a cheaper carrier

Goal: route Singapore mobile calls (prefix 6591…6599) over a cheaper wholesale carrier, while everything else continues to use the primary carrier — with the primary as the safety net.

1. Register the new carrier. On Call Routing → + Add trunk, create budget-mobile with the wholesaler’s host, the right transport/codecs, your channel cap, and Enabled on. Save and confirm the 201.
2. Install its gateway. Click view config on the budget-mobile row, review the CloudCX Switch block, apply it on the SBC and run CloudCX Switch service external rescan. Verify the gateway shows up / registers as expected.
3. Add the specific LCR rule. In Least-cost routing → + Add rule: prefix 659, trunk budget-mobile, priority 5, cost 0.0040. Save.
4. Add (or confirm) the catch-all. Ensure a rule with an empty prefix → primary-carrier at a high priority number (e.g. 100) exists, so all non-mobile traffic still has a home.
5. Confirm ordering. The list should show 659 above the catch-all (longest prefix first). A test dial to +65 9123 4567 now matches 659 and routes via budget-mobile; a dial to a +65 6… landline matches only the catch-all and stays on primary-carrier.
6. Validate, then watch costs. Place a live test call to a mobile and confirm it connects over the new carrier (CDR / SBC logs). Keep the catch-all on the primary so any routing gap fails safe to a known-good trunk.

Why this is safe: the new carrier only takes traffic the moment its LCR rule exists and its gateway is installed. If you add the rule but skip the gateway, the dialer can’t reach the trunk and the call falls back to the default gateway — you never strand mobile calls on a half-built carrier.

8.7 Recap

• Call Routing (Platform group) unites inbound — live ACD queues and DIDs — with outbound SIP trunks and LCR.
• A DID routes a number to a flow / queue / extension / voicemail; it is tenant-scoped, admin-written, and managed in Voice › IVR Builder › Numbers. Inactive DIDs are parked, not deleted.
• A SIP trunk is an outbound carrier; its name is the CloudCX Switch gateway name (safe charset). Only Name and Gateway host are required; the password is write-only and never read back.
• Trunk scope is set by (tenant_id, reseller_id): tenant-owned, reseller-owned, or both-NULL platform-shared. Calls see their own scope plus platform-shared trunks.
• LCR picks a trunk by longest prefix → most-specific scope → lowest priority → lowest cost → newest; the empty prefix is the catch-all. Only enabled trunks are candidates.
• It is idle-safe: no trunks/rules (or any lookup error) falls back to the default fs_outbound_gateway — outbound is unchanged until you opt in.
• The generated config (view config) is review only — a CloudCX Switch gateway block plus a CloudCX SBC snippet, with the real password embedded. CloudCX never writes or reloads your live SBC; you apply it by hand.

CloudCX Administrator & Training Manual

Ch. 09 · Call-Flow Builder

The visual IVR / call-flow builder

When a caller dials one of your numbers, something has to decide what they hear and where they land — a greeting, a press-1-for-sales menu, a queue of agents, a voicemail box, or a straight transfer to an extension. In CloudCX that decision is a flow: a small graph of nodes you draw on a drag-and-drop canvas, wire together, validate, and publish. This chapter takes you through the builder end to end — the canvas and its parts, every node type and its fields, how a flow is serialized and validated, how to attach it to a phone number, and a fully worked main-menu · hours · queue IVR you can reproduce in minutes.

9.1 Opening the builder

The call-flow builder is a dedicated tool that lives beside the admin console at admin.cloudcx.app/ivr-builder.html. It uses the same sign-in as the console (your admin session carries over); if your session has lapsed it shows a brief Sign-in required gate and bounces you to admin.cloudcx.app to re-authenticate. From the console you reach it via the Voice group in the sidebar; from inside the builder the ← CONSOLE chip in the top-left returns you to the dashboard.

Two things to know before you start drawing:

• Writes are admin-gated. Creating, editing, publishing and deleting flows requires an administrator. Reads are tenant-scoped — a tenant user sees only their own flows, a platform admin sees all and may pick the owning tenant.
• The builder has two modes. A Builder tab (the canvas) and a DIDs tab (the inbound-number table). The same tool authors the flow and wires the number that triggers it.