KatoCall logoKatoCall logoKatoCall EnglishEspañolPortuguêsFrançaisDeutschРусский中文日本語हिन्दीالعربية

The complete handbook

Install it, then set it up to carry calls

A plain-language guide to putting KatoCall on a server and getting it billing real phone calls. Follow the parts in order — no telecom background needed.

Version 1.0.0For Debian 12 servers~30–45 min to first call

Start here

How KatoCall works, in two minutes

KatoCall is a switchboard with a billing engine built in. Your customers place calls through it; it checks their balance, picks the cheapest route out, times the call and bills it — automatically.

Your customer places a call KatoCall checks the balance, picks the cheapest route, times & bills the call Your carrier (SIP trunk) Anyone dials routes Inbound calls work the same way in reverse: a phone number (a DID) rings in and forwards to a customer.
Every call — in or out — passes through KatoCall, where the billing happens.

Where your money comes from

You buy minutes from a carrier at one price and sell them to customers at a higher one. KatoCall stores both and keeps the difference on every call.

You pay the carrier
$0.0090
provider rate, per minute
You charge the customer
$0.0150
customer rate, per minute
You keep
$0.0060
your margin, automatically

Good to know: KatoCall does not convert currencies. Pick one currency in Settings (US Dollars is the default) and use it for buying and selling, so every margin is a simple subtraction.

Part 1

Install it on a server

You do this once, on a brand-new server. If someone technical sets the server up for you, hand them this part.

What you need first

A serverDebian 12 (Bookworm), 64-bit — a fresh one. Any decent VPS works (OVH, Hetzner, DigitalOcean, Vultr).
Size2 CPU cores, 4 GB RAM, 20 GB disk. 2 GB RAM is the floor.
A public IP addressThe server needs its own address on the internet — your provider gives you this.
Server loginThe root password, or a user with sudo.
From your carrierA SIP trunk (their host, and either an allowed IP or a username/password), plus any phone numbers (DIDs).
A domain name (optional)Only if you want the https padlock. You can start without one and add it later.

Do the install

Copy katocall-1.0.0.tar.gz onto the server and run these one at a time. Each prints what it does and stops with a clear message if something is missing.

  1. Unpack and check the server

    The first command changes nothing — it confirms the server is ready and tells you if anything is missing.

    root@your-server
    # unpack the package
tar -xzf katocall-1.0.0.tar.gz
cd katocall-1.0.0

# check the server (safe — changes nothing)
sudo bash install/00-preflight.sh

  2. Run the install scripts in order

    Run these one by one. Number 01 builds the phone engine and takes 10–20 minutes; the rest are quick.

    root@your-server
    sudo bash install/01-install-asterisk.sh   # the phone engine (10–20 min)
sudo bash install/02-install-base-stack.sh
sudo bash install/03-setup-admin-panel.sh
sudo bash install/04-configure-ami.sh
sudo bash install/05-production-hardening.sh
sudo bash install/06-configure-did-forwarding.sh
sudo bash install/07-configure-fail2ban.sh
sudo bash install/08-configure-nat.sh
sudo bash install/09-configure-outbound.sh
sudo bash install/11-configure-backups.sh
sudo bash install/12-configure-dialer.sh   # only if you want the dialer

    01 through 09 are required. Step 12 is only for the dialer — skip it and everything else still works.

  3. Confirm everything is healthy

    This runs about 65 checks — every service, the firewall, backups, security — and names what to fix for anything that fails.

    root@your-server
    sudo bash install/verify.sh

PASS 66   WARN 1   FAIL 0

  4. Log in for the first time

    Open the server’s address in a browser and sign in. It forces a new password immediately — nothing works until you set one.

    • Address: http://your-server-address/
    • Username: admin
    • Password (you must change it right away): Katocall

Before real calls: turn on HTTPS. Until you do, the panel runs on plain http and your login travels the internet unlocked. Once a domain points at the server, run:

sudo bash install/10-configure-tls.sh panel.yourcompany.com you@yourcompany.com

Part 2

Set it up to carry calls

Now you’re in the panel. Build these six things in this order — each uses the one before it. Everything is in the left-hand menu.

1SuppliersWho you buy minutes from
2Rate CardsYour buy & sell prices
3TrunksThe line to your carrier
4Routing GroupsWhich line for which call
5AccountsYour customers
6DIDsIncoming numbers

  1. Suppliers — who you buy minutes from

    A supplier is a carrier you buy minutes from. Start here because everything points back to it. Open Suppliers → New Supplier and give it a name.

    DashboardSuppliersRatesTrunksAccounts
    Suppliers+ New Supplier
    e.g. IDT Gold
    USD — $ US Dollar▾
    Account manager, contract terms…
    Suppliers → New Supplier

  2. Rate Cards — your buy and sell prices

    A rate card is a price list, one line per destination (a prefix like 1 for the USA, 44 for the UK). Make two kinds:

    • Provider Rates — what your supplier charges you.
    • Customer Rates — what you charge customers (higher — that gap is your profit).

    Don’t type hundreds of prefixes: open the card and click Import CSV to load your carrier’s price file at once.

    DashboardSuppliersRatesTrunksAccounts
    USA Wholesale — ProviderImport CSV
    DestinationPrefixPer min
    United States1$0.0090
    United Kingdom44$0.0110
    Mexico Mobile521$0.0180
    Rates → Import CSV

    Good to know: Rates are stored to 4 decimal places; a 5-decimal deck is rounded on import.

  3. Trunks — the actual line to your carrier

    A trunk is the live connection to a supplier. Open Trunks → New Trunk. Two things matter:

    • Direction — Outbound, Inbound, or Both.
    • Authentication — IP-based (they trust your server’s address) or Username/Password (they gave you SIP login details).

    After saving, use Test Call to prove it dials before pointing customers at it.

    DashboardSuppliersRatesTrunksAccounts
    New TrunkSave
    IDT-GOLD
    Outbound▾
    IP-based▾
    sip.idtgold.com
    30
    Trunks → New Trunk

    A trunk name can’t contain spaces — use IDT-GOLD, not IDT GOLD.

  4. Routing Groups — which line for which call

    A routing group says: for this kind of number, try these trunks, in this order. Two dials:

    • Priority — lower is tried first. Put your cheapest carrier at priority 1.
    • Weight — splits traffic between trunks that share a priority.

    If the first trunk is busy or fails, KatoCall falls to the next. Use Preview to type a number and see which trunk it would use.

    DashboardTrunksRouting GroupsAccounts
    Standard LCR+ Add Route
    TrunkPriorityWeight
    IDT-GOLD1 first100
    Backup-Carrier2100
    Routing Groups → Add Route

  5. Accounts — your customers

    An account is one customer. Open Accounts → New Account. The important choices:

    • Billing Type — Prepaid (load a balance; calls stop at zero) or Postpaid (invoiced later).
    • Rate Card — the customer price list from step 2.
    • Routing Group — how their calls leave, from step 4.
    • How they connect — an allowed IP, or a username & password for their phone/PBX.
    DashboardTrunksRouting GroupsAccounts
    New AccountSave
    Acme Telecom
    Prepaid▾
    $250.00
    USA Retail▾
    Standard LCR▾
    Accounts → New Account

    Good to know: Every account that makes outbound calls needs a customer rate card covering the prefixes you sell — otherwise those calls are refused (never billed at zero).

  6. DIDs — numbers that ring in

    A DID is a phone number people call to reach one of your customers. Open the account, go to DIDs → Add DID, type the number and where it forwards. (Save the account first.)

    DashboardTrunksAccountsSettings
    Acme Telecom · DIDs+ Add DID
    DID NumberForwards To
    +1 305 555 0100Acme main lineactive
    Accounts → DIDs → Add DID

Every field in the panel has a small ? beside it explaining what it does, in all ten languages. Settings → Network pushes your setup to the phone engine after big changes.

Part 3

Run a dialer campaign

The dialer calls a list of numbers, plays a recorded message, and lets people press a key to be connected, call back, or opt out. Install step 12 must be done first.

Know what it is: this is a power dialer, not a predictive one. No answering-machine detection (a voicemail counts as answered) and no automatic pacing — you set a fixed number of simultaneous calls. It runs on one server at a time.

  1. Create the campaign

    Open Dialer Campaigns → New Campaign. Pick the account it bills to, name it, set the pacing: Max Concurrent Calls, Max Attempts, and the Retry gap.

    DashboardAccountsDialer CampaignsAgents
    New CampaignSave
    Acme Telecom▾
    10
    3
    Upload a .wav / .mp3…
    Dialer Campaigns → New Campaign

  2. Add your message and the menu

    Upload the Prerecorded Message that plays on answer. Then build the IVR Menu — what each key does:

    • Press 1 → transfer to an agent
    • Press 2 → request a call back
    • Press 9 → add to Do-Not-Call (never dialled again)

  3. Upload your contacts

    In the campaign’s Contacts section, click Upload CSV — a simple file of phone numbers.

  4. Press Start — and read the results

    Hit Start and it begins dialling within seconds; Pause stops it just as fast. When done, Download Results gives a file showing what happened to every number.

    DashboardAccountsDialer CampaignsAgents
    Spring PromoStart
    Phone NumberAttemptsResult
    +1 305 555 00001answered
    +1 305 555 00012no answer
    +1 305 555 00021transferred
    The campaign fills in a result for every number.

Part 4

Everyday operations

Four commands cover almost everything you’ll do on the server.

root@your-server
sudo bash install/verify.sh            # is everything healthy?
sudo /usr/local/sbin/katocall-backup    # take a backup now
sudo bash install/upgrade.sh           # apply a newer version
sudo bash install/uninstall.sh         # remove it (keeps your data)

Your backups sit on the same disk they protect. Copy them somewhere else on a schedule, or a disk failure takes the data and its only backup together.

Before you trust a revenue report, you can prove the books balance to the penny:

sudo -u softswitch admin/backend/venv/bin/python admin/backend/manage.py verify_ledger

Part 5

When something’s wrong

“Could not reach the server” when I log in.
A service may be restarting. Wait and refresh. If it persists, run install/verify.sh — it points at the exact service that’s down.
A call won’t connect.
Check three things in order: the Account has a balance and a rate card; the Routing Group has a trunk for that destination (use Preview); the Trunk’s Test Call works.
I got locked out after mistyping my password.
KatoCall blocks an address after repeated failures, on purpose. Wait for the block to expire, or clear it from the IP Bans page from another device.
My dialer says “Running” but nothing dials.
Install step 12 was probably skipped. Run install/12-configure-dialer.sh, then install/verify.sh.
The margin column is blank.
The customer’s currency and the trunk’s currency differ. KatoCall doesn’t convert currencies — buy and sell in one currency and the margin fills in.

Whatever the problem, sudo bash install/verify.sh is the first thing to run. It checks ~65 things and names the script to re-run.