Skip to main content

Admin quickstart

This page takes a new company from an empty install to a first working call: the setup wizard, a trunk, a number (DID), an inbound route, an IVR, users, and softphone onboarding. Each step names the console page. The matching API is in API getting started, and the full reference is at /api/docs.

Before you start, finish one install: Docker Compose, Ubuntu VM or Kubernetes. Have the recovery key and the carrier's onboarding details at hand.

:::info Status Everything on this page exists on the main branch. Anything that is not built yet is marked coming in Alpha. MonoPbx does not verify carrier settings: the trunk templates are best-effort starting points that you check against the carrier's documents. :::

1. Setup wizard​

Open the single-use setup link that the installer printed. On a VM, sudo mpbx-ctl setup-url issues a new one. The wizard:

  1. creates the System Owner (e-mail, name and a password of your choice);
  2. enrols the owner's authenticator app (TOTP). This uses up the link;
  3. shows the recovery codes once. Store them with the recovery key;
  4. sets the company name and default language, asks for a certificate for the install address (ACME when configured, otherwise an upload), shows the proposed trunk from [setup.trunk], and invites the first users.

Each step can be skipped and finished later in the console. The wizard reads answers prepared in mpbx.toml under [setup], so you only confirm them. See the setup wizard guide.

Installation-wide settings (backups, the install's certificates) need a fresh code from your authenticator app. Open Account security, then Installation-wide administration.

2. Company, departments and roles​

  • Admin > Departments. Every company has a Default department. Create more only when you need separate roles or call routing per group.
  • Admin > Roles. New users get the built-in User role (own calls, voicemail, directory). Give extra rights per company or per department. The API decides every request; the console shows only the buttons a user may use.
  • Keep at least two people with the Owner role. The last Owner cannot be disabled or stripped of the role.

3. Trunk​

A trunk connects the company to a carrier.

  1. Admin > Trunks > New trunk. Pick a provider template if one fits, or the generic registration or IP template. Templates are unverified: fill every placeholder from the carrier's portal.
  2. Choose register (the PBX registers with the carrier using digest credentials) or ip (the carrier sends calls from known addresses; set the allow-list).
  3. Enter the host, port, transport and account credentials. Secrets are write-only: the console never shows them again.
  4. Set max channels to your contracted call limit, and the main number (E.164) used for caller ID.
  5. Check the live state in the list (up, registering, registration failed, and so on). A failure shows the last error in words.

Every field is described in SIP trunks.

4. Number (DID)​

Admin > DIDs. Add each number you bought in E.164 form (for example +525512345678) and assign it to the trunk it arrives on. A number belongs to one company. A number another company already holds is refused (MPBX-TRUNK-DID-TAKEN).

5. Inbound route​

Admin > Routing > Inbound. An inbound route sends a DID to a destination:

  • a user extension, a ring group (Admin > Ring groups), a queue (Admin > Queues), an IVR (below) or reject;
  • a route with no DID is the catch-all for numbers without a route. The exact DID on that trunk wins over the exact DID on any trunk, which wins over the trunk's catch-all, which wins over the company's catch-all.

Use Admin > Routing > Test (the rule tester) before you take live calls. It runs the same router as live calls, so it shows where a call from a given number to a given DID would go.

Emergency numbers are set under Admin > Emergency. Check them before go-live: the console explains when a change needs approval.

6. Outbound rules​

Admin > Routing > Outbound. Outbound rules decide which trunk carries a dialled number, in which order, with failover. Start with one rule for national calls and one for international calls, then test both in the rule tester. The dial plan guide describes the toll-fraud safety rules; read them before you open international destinations.

7. IVR menu​

Admin > IVR menus. An IVR is a menu: a greeting of up to 16 prompts, up to 12 keys each leading to a destination, the number of attempts, the wait for a key, and the prompts played after a wrong key or no key. Publish the menu when it is right. A published version never changes; a further edit creates a new draft.

Point an inbound route at the IVR to use it.

Office hours (Admin > Hours, holidays under Admin > Hours > Holidays) can send calls to a different destination when the company is closed or on break. Ring groups, queues and forwarding defaults are set under Admin > Ring groups, Admin > Queues and Admin > Forwarding defaults.

8. Extensions, users and invitations​

  1. Admin > Extensions. Each user has an extension number. Voicemail mailboxes belong to user extensions. They are created automatically when the company turns on auto-create in its voicemail defaults (Admin > System > Voicemail).
  2. Admin > Users > New user. Enter the name, e-mail, department and roles. Leave the password empty and send the invitation. The user gets a one-time link by e-mail and chooses a password. No password is ever sent by e-mail.
  3. Users can also be imported from CSV (up to 2000 rows per file) on the Users page. Export uses the same format.
  4. Disabling a user ends their sessions at once. An administrator can reset a user's two-factor enrolment or password.

The password policy requires at least 12 characters. Five failed sign-ins lock the account for 15 minutes.

9. Devices and softphone onboarding​

Every device registers with its own SIP credentials. Nobody shares the extension password.

  • Browser phone. Nothing to install. A user who signs in to the web client gets a browser device, and the softphone dock registers it.
  • Desk phones. Admin > Phones lists the phone templates for the models you use. Attach each device to the user's extension under Admin > Devices, then follow the template's provisioning notes.
  • Mobile and desktop apps. The web client shows a QR code for a device. The code is valid for 10 minutes and works once. The app scans it, receives new credentials for that one device, and stores them in the device keychain. The QR code itself holds no password. Details are in the SIP credentials guide.
  • Push for incoming calls on mobile is configured on Admin > Phones > Push. Check the push health there after setup.

Rotating or revoking a device ends its registrations at once.

10. First test call​

  1. Sign in as a test user on the browser phone and call another extension.
  2. Call a DID from an outside phone. Confirm the inbound route, the IVR prompts and the ringing.
  3. Check Admin > History for the calls and Admin > Audit log for the configuration changes.
  4. Run sudo mpbx-ctl selftest (VM) or scripts/smoke.sh (Compose) once the first trunk is up.

When a call fails, the rule tester and the call history show the reason. Error codes are listed in error codes.

Coming in Alpha​

  • Upgrade and rollback of a running install (mpbx upgrade). Until it exists, a bundle of another version is refused unless you pass --force-bundle.
  • Published download channels for the VM installer. The download domain in the one-line command is a placeholder today.