Recommended Services
Supported Scripts
HostCRM for WHMCS
A customer-service and CRM workspace built into WHMCS. Follow-ups, tickets, leads, collections, call-backs, staff KPIs and self-building reports — in one module.
Overview
HostCRM turns WHMCS into a complete customer-service desk. Your support team works from a single daily queue: follow-ups that fall due, overdue-invoice collections, promise-to-pay callbacks, website call-back requests, and support tickets — all in one place, all logged automatically.
Because every customer contact is recorded against the client as it happens, your support reports build themselves. You never write a report by hand; the numbers come from what your team logs as they work.
What HostCRM does
Automates follow-ups
Creates follow-up actions automatically when invoices fall overdue, clients sign up, or services suspend.
Works tickets inline
Read and reply to WHMCS support tickets without leaving the module.
Logs every contact
Calls, WhatsApp, email, SMS, chat and social contacts recorded against the client record.
Tracks money
Overdue invoices become worked follow-ups; promises to pay are booked and chased.
Measures the team
Per-staff KPIs with weighted scorecards and a single performance score.
Reports itself
Support volume by issue, channel, ticket, lead and collection — exportable to PDF.
Requirements
| Component | Requirement |
|---|---|
| Platform | A working WHMCS installation with admin access |
| PHP | PHP 7.4 or newer (PHP 8.x supported) |
| Database | The MySQL/MariaDB database WHMCS already uses — HostCRM creates its own tables |
| Access | Ability to upload files to modules/addons/ and activate addons in WHMCS |
| Outbound HTTPS | The server must be able to reach the licensing server over HTTPS to validate the license |
| License | A HostCRM license key issued for your domain |
HostCRM never modifies WHMCS core tables. It reads from them (clients, invoices, tickets) and stores all of its own data in dedicated mod_hncrm_* tables. Deactivating the module never deletes your data.
Installation
- Upload the module. Extract the HostCRM zip and upload the
hncrmfolder tomodules/addons/in your WHMCS root, so the path ismodules/addons/hncrm/. - Activate it. In the WHMCS admin, go to System Settings → Addon Modules (or Setup → Addon Modules on older versions). Find HostCRM and click Activate.
- Grant access. Still on the addon row, click Configure and tick the admin role groups allowed to use HostCRM, then save.
- Open the module. A HostCRM item appears in the WHMCS Addons menu. Open it — on first load it creates its tables and seeds default follow-up rules.
The database tables and default rules are created the first time the module page loads after activation. If you ever upgrade to a newer version, just open the module page once so any schema updates apply.
Activation & licensing
HostCRM is domain-locked. On first use it asks for a license key and validates it against the licensing server. Until a valid license is active, the admin interface is replaced with a license screen — but background automation (cron and hooks) keeps running, so no customer data is ever lost while a license is being sorted out.
- Open HostCRM. If no valid license is present you'll see the “HostCRM license required” screen.
- Enter your license key in the field provided and click Activate license.
- Done. On a successful check the module unlocks and loads normally. The result is cached, so day-to-day page loads don't call out every time.
These come from the licensing server, not the module. The most common cause is directory validation being enabled on the license — clear the “Valid Directories” field for the license (installation paths differ between servers). See Troubleshooting.
Once activated, the license status is visible any time under Setup → Settings → License, where the key can also be updated. A daily background check re-validates the license automatically.
First-run setup
After activation, spend five minutes on these settings so the module fits your business. All of them live under the Setup tab.
- Set business hours (in the addon's WHMCS configuration screen) so follow-up scheduling and response-time reporting reflect your working day.
- Review the follow-up rules under Setup → Follow-up rules. Sensible defaults for overdue invoices and new-client welcomes are seeded — adjust timing and messaging to taste. See Follow-up rules.
- Check issue types under Setup → Issue types. These drive your support reports, so make sure the list matches how you categorise work.
- Assign managers. In Setup → Settings, set which admins are managers — managers see Reports, KPIs setup, and the full team view.
- Optional: set your logo and accent colour under Setup → Settings → Appearance for a branded look.
That's enough to start working. The sections below explain each feature in depth — but your team can begin logging contacts and clearing the daily queue right away.
Core concepts
A few ideas underpin everything in HostCRM. Understanding them makes the rest obvious.
| Concept | What it means |
|---|---|
| Contact | A single logged interaction with a customer — a call, WhatsApp, email, SMS, chat, visit or social message. Contacts build the support reports. |
| Follow-up | A task that lands in someone's daily queue with a due date. Created by hand when you log a contact, or automatically by a rule. |
| Rule | An automation: “when X happens, create a follow-up.” For example, an overdue invoice creating a collections follow-up. |
| Issue type | The category of a contact or follow-up (Billing, Email, DNS, SSL…). What the support reports are grouped by. |
| Outcome | How a follow-up ended — resolved, promise to pay, no answer, and so on. Some outcomes (like a self-resolved invoice) are set automatically. |
| Lead | A non-client enquiry you're tracking toward becoming a customer. |
| Staff task | Internal work a manager assigns to a team member, optionally with an approval-based bonus. Separate from customer follow-ups. |
My day & the queue
My day is where every staff member starts. It's their work list: follow-ups due today, anything overdue, and everything assigned to them. The module opens here by default.
How to work it
- Clear money first. The Promises and collections items are time-sensitive — work them at the start of the shift. Both carry a count badge in the menu.
- Open a follow-up to see the client's context, what's owed, the history, and the reason the follow-up exists.
- Complete it with an outcome. If it needs another touch, the module schedules the next follow-up for you.
- Reschedule with a reason if you must push something — the trail stays honest, and the follow-up keeps its issue type so reporting stays accurate.
A healthy support operation aims to keep any customer contact from sitting unanswered more than 12 hours. My day surfaces overdue items so nothing slips.
Logging contacts
Whenever a customer reaches your team — by call, WhatsApp, SMS, email, live chat or social — log it under Log. This is the single most important habit: accurate logging is what makes the reports real.
- Search the client first so the contact attaches to their record. Matching is by phone and email, so repeat callers don't create duplicates. Always capture a phone number, even for a general enquiry, so the person is recognised next time.
- Pick the issue type under “What was it about” — Billing, Email, DNS, SSL, Website Down, Domain, Login/cPanel, Migration, Orders, Performance, Pre Sales, Onboarding, and so on. This is what the reports are built from.
- Tick “This needs a follow-up” if the matter needs a callback or further action, and it lands back in My day with the right owner and date.
If the person isn't a client yet, log them as a lead (real sales intent) or a general enquiry (just recorded). Either way, their history is kept and builds up over time.
The Log book tab shows the full day-book of what's been logged — yours or the whole team's — for checking what happened on any account.
Leads
A lead is a non-client enquiry with real sales intent. Logging someone as a lead keeps their contact history in one place and lets you track them toward conversion.
- Capture a lead from the Log screen when a non-client makes contact.
- Own it — leads are assigned to a staff member, who is credited on conversion.
- Convert it when they become a paying client. Conversion is what the Leads report and the “leads converted” KPI measure.
Tickets
The Tickets tab brings WHMCS support tickets into the module. Your team reads the full conversation and replies to the client directly — the reply reaches them exactly as it would from WHMCS.
What you can do
- See what needs a reply. A red badge shows tickets awaiting your response (Open and Customer-Reply).
- Filter and search by status, department, date range, and keyword (subject, ticket number, or message text).
- Read the full thread with the client's CRM context alongside — their follow-ups, invoices and history.
- Reply and set status from the module. The reply is attributed to the logged-in admin.
- Open in WHMCS for anything that needs the full ticket interface.
HostCRM adapts to your WHMCS version's ticket schema automatically, so ticket subjects and replies display correctly across WHMCS releases.
Collections & promises
Overdue invoices and unpaid orders generate collections follow-ups automatically, so chasing money is a worked queue rather than a manual hunt.
Working collections
- Collections follow-ups appear in My day, tagged with the Billing issue type so they report correctly.
- Guide the customer through payment, renewals and receipts; point them to the right upgrade or downgrade.
- If they commit to pay by a date, complete the follow-up and set the outcome to Promise to pay. The system books the callback for you and files it under Promises.
Self-resolving follow-ups
Some follow-ups close themselves. If a customer pays an overdue invoice (or a suspended service is reactivated, or an unplaced order is finally placed) before a staffer works the follow-up, HostCRM detects that the underlying reason is gone and closes the follow-up automatically with the outcome condition cleared. It's a positive signal — work your team didn't have to do.
Call requests & the website widget
HostCRM includes an embeddable “Call me” button for your website. A visitor leaves their name and number, and the request lands in the Requests tab for your team to action.
Enabling it
- Go to Setup → Settings → Website “Call me” button and turn it on. Until it's enabled, the public endpoint rejects everything.
- In Allowed website domains, list the domains your button is embedded on — one per line or comma-separated. Subdomains are included automatically. Requests from any other domain are rejected.
- Under Website widget code, copy the snippet (the endpoint is already filled in for your install) or download the HTML, and paste it into your site before
</body>.
The allowed-domains list is a security control (CORS). If it's blank, all cross-site requests are blocked — so the widget won't submit until your site's domain is listed.
The widget includes a hidden honeypot field and per-IP rate limiting, so bot and spam submissions are dropped automatically.
Staff tasks & bonuses
Separate from customer follow-ups, the Manage tab lets managers assign internal work to team members — with an optional bonus paid on approval.
- Create a task with a title, description, assignee, due date and priority.
- Set a bonus (or leave it at zero for unpaid work). Paid tasks require manager approval before the bonus is credited.
- Approve or send back submitted work. On approval, the bonus is credited to the staffer's ledger.
- Withdrawals let staff draw down earned bonuses; managers process them.
Recurring tasks can be scheduled so routine internal work is assigned automatically.
Calendar
The Calendar gives each staff member a dated view of their follow-ups and tasks, so they can see what's coming rather than only what's due today. It's a planning companion to My day.
Follow-up rules
Rules are the automation engine. Each rule says: when a trigger fires and its conditions match, create a follow-up with a chosen category, issue type, owner, timing and template. HostCRM ships with sensible defaults; you tune them under Setup → Follow-up rules.
Anatomy of a rule
| Part | What it controls |
|---|---|
| Trigger | The WHMCS event that starts it — invoice overdue, client created, client settled, service suspended, order placed, and so on. |
| Conditions | Extra filters, e.g. only if the client has (or hasn't) placed an order, or only after N days. |
| Timing | When the follow-up is due — immediately, or a set number of days after the trigger. |
| Issue type | The category stamped on the follow-up, so it reports correctly and carries through to the logged contact. |
| Assignment | Who the follow-up goes to — a specific admin, or round-robin across the team. |
| Template | The message text suggested to the staffer (email/SMS/call script), with placeholders like {client_first_name}. |
Resolve conditions & auto-close
A rule can define a resolve condition — the thing that makes the follow-up unnecessary. When that condition clears on its own (the invoice gets paid, the service reactivates), HostCRM auto-closes the follow-up with the outcome condition cleared. This is what stops your team chasing problems that already fixed themselves.
The issue type set on a rule copies onto the follow-up, and then onto the logged contact when the follow-up is completed — and onto any rescheduled or child follow-up. That's why completed collections work shows up correctly as “Billing” in your reports rather than “Not set”.
Issue types
Issue types are the categories your support work is grouped by — Billing, Email, DNS, SSL, Website Down, Domain, Login/cPanel, Migration, Orders, Performance, Pre Sales, Onboarding, and any others you add. They matter because the reports are built from them.
- Manage the list under Setup → Issue types.
- Each has a label and a colour used in reports and badges.
- Choose the right issue type every time you log a contact — it's the difference between a report that tells you what your customers actually need and one full of “Not set”.
Templates
Templates are reusable message bodies for follow-ups — a collections email, a welcome-call script, a renewal reminder. They're suggested to the staffer when they work a follow-up, so messaging stays consistent.
- Manage them under Setup → Templates.
- Use placeholders that fill in per client — for example
{client_first_name},{invoice_id},{amount},{due_date},{pay_link},{admin_name}, and WHMCS's{company}for your business name.
Onboarding & welcome
New clients can be welcomed automatically. HostCRM seeds welcome rules that fire after signup — with a delay so they land once the order has settled — and it distinguishes between clients who placed an order and those who signed up without one, so the message fits.
- Welcome follow-ups carry the Onboarding issue type, so onboarding effort shows up in your reports.
- Adjust the timing, script and assignment like any other rule under Setup → Follow-up rules.
KPIs & scorecards
HostCRM measures each staff member against targets you set, and rolls their KPIs into a single weighted performance score. Actuals are computed live from what's already logged — there's no extra data entry.
Setting targets
Under Setup → KPIs (managers only), set a target per staff member per metric, choosing weekly or monthly, and a weight.
| Metric | Measures | Percentage mode |
|---|---|---|
| Follow-ups completed | Follow-ups the person completed | % of follow-ups assigned |
| Leads converted | Leads that became clients | Conversion rate (% of leads owned) |
| Collections recovered | Value recovered on their collections follow-ups | — |
| Tickets replied | Ticket replies they sent | — |
| Promises to pay secured | Payment commitments obtained | % of collections follow-ups worked |
| Staff tasks approved | Internal tasks approved | % of tasks assigned to them |
| Contacts logged | Customer contacts logged | — |
Number vs percentage
Each KPI is set as a number (e.g. 40 follow-ups) or a percentage (e.g. 80% of tasks assigned). Percentage is only offered for metrics that have a sensible denominator — the others are counts. A percentage KPI shows both the rate and the raw numbers behind it, e.g. “80% (15 of 20).”
Weights & the overall score
Each KPI carries a weight. The overall score is the weighted average of achievement across a person's KPIs. Two rules keep it fair:
- Each KPI caps at 100% before weighting, so overachieving one target can't mask a weak area.
- Weights should total 100% per person. The setup screen shows a running total and warns if it doesn't add up — but it still scores with whatever weights are set.
The score is colour-banded: ≥90 excelling ≥70 on track ≥50 attention below behind
Where scores appear
- Manager overview — under Reports → KPIs: every staffer's targets vs actuals, progress bars, and overall score. Managers only.
- My KPIs — a main-menu tab (after Calendar) where each staff member sees only their own scorecard. Hidden by default; enable it under Setup → Settings → Staff KPI view when you're ready to share scores with the team.
Weight outcomes (leads converted, collections recovered, promises secured) above activity (contacts logged) — activity metrics are easy to game. Only weight metrics you've actually set a target for, and tailor the mix to each person's real role.
Reports
Reports compile themselves from what your team logs. They're under the Reports tab (managers only), each with its own date range and a one-click PDF export.
| Report | Shows |
|---|---|
| Support issues | Contacts received, broken down by issue type and channel, with period-on-period comparison. |
| Leads | Lead volume and conversions, per staff. |
| Collections recovery | Money recovered through worked collections follow-ups. |
| Most rescheduled | Follow-ups pushed most often — a signal of stuck work. |
| Most contacts | Clients and leads ranked by how often they've been in touch. |
| Call requests | Website call-backs received, handled and waiting, by website and staff. |
| Tickets | Opened, still-open, replies by staff, first-response time, ageing, busiest days and hours. |
| Follow-ups | Created, completed, overdue, by category, per staff, and by outcome. |
| Staff tasks | Internal tasks created, approved, awaiting approval, and bonuses credited, per staff. |
| KPIs | The team scorecard — targets vs actuals and weighted overall scores. |
Exporting to PDF
Every report has a Print / Save as PDF button. It opens your browser's print dialog with everything except the report hidden, so you get a clean, styled PDF of just the report.
In Chrome or Edge, tick More settings → Background graphics in the print dialog so the coloured bars and badges print. It's a one-time browser setting.
Settings reference
All settings live under Setup → Settings. Here's what each does.
| Setting | Effect |
|---|---|
| License key | Your HostCRM license. Changing it re-validates immediately. |
| Product name | Fixed to HostCRM. |
| Logo | Shown in place of the page title. Blank keeps the text heading. |
| Accent colour | Used for tabs, links and primary buttons. |
| Colour follow-ups by | Whether follow-up badges are coloured by action type or issue type. |
| Manager admin IDs | Which admins are treated as managers (see Reports, KPI setup, team views). |
| Maximum automated follow-ups per client | A fatigue cap so automation can't over-contact one client. |
| Fatigue window (days) | The period the fatigue cap applies over. |
| Staff KPI view | Shows the “My KPIs” tab to all staff. Off by default. |
| Website “Call me” button | Enables the public call-back endpoint. |
| Allowed website domains | CORS allow-list for the call-me widget. |
| Daily digest | Emails each staff member their follow-up counts every morning. |
| Diagnostics logging | Verbose logging for troubleshooting. Leave off in normal use. |
Roles & permissions
HostCRM has two levels of access, on top of the WHMCS admin-role groups you allow at activation.
| Role | Can access |
|---|---|
| Staff | My day, My tasks, Promises, Leads, Log, Log book, Requests, Tickets, Calendar, and (if enabled) their own My KPIs. |
| Manager | Everything staff can, plus Reports, the KPI team overview, KPI setup, Staff-task management and approvals, and Settings. |
Set who's a manager under Setup → Settings → Manager admin IDs. Managers are defined by their WHMCS admin ID.
Licensing (admin)
HostCRM validates against the WHMCS Licensing Addon. Day to day there's nothing to manage — but here's how it behaves.
- Domain-locked. A license is valid for the domain(s) registered for it.
- Cached. A successful check is trusted locally so normal page loads don't call out. A daily cron re-check keeps it current and catches revocations.
- Grace on outage. If the licensing server is briefly unreachable, the last-known-good result is honoured for a grace period, so a network blip never locks out a valid install.
- Blocks admin only. When a license is invalid, the admin UI is replaced with the license screen — but cron and hooks keep running, so no data is lost.
Installs on localhost, 127.0.0.1, or .local / .dev / .test domains don't require a license, so staging environments just work.
Branding
HostCRM presents in your business's identity, not the vendor's.
- Logo — set your own under Appearance; it replaces the page title.
- Accent colour — drives tabs, links and buttons.
- Currency — all money is shown in your WHMCS default currency automatically.
- Templates — default messages use WHMCS's
{company}placeholder, so they carry your company name out of the box.
Troubleshooting
“HostCRM license required” — Directory Invalid
The license key and domain are fine, but the licensing server is rejecting the installation path. Edit the license in your WHMCS Licensing Addon and clear the Valid Directories field (installation paths differ between servers, so directory-locking causes this). Then reload the module.
“License signature check failed”
The response signature didn't verify. Confirm the licensing secret configured in the module matches the product's Secret Key in the Licensing Addon exactly. Turn on Diagnostics logging in Settings to see the raw exchange on the license screen.
A report shows “Not set” for issue type
Contacts were logged without an issue type. Make sure staff select an issue type every time, and that your follow-up rules have an issue type assigned so completed follow-ups carry it through.
The call-me widget doesn't submit
Check two things: the Website “Call me” button setting is on, and your site's domain is listed under Allowed website domains. A blank domain list blocks all submissions.
The module page shows an error instead of loading
HostCRM catches errors and shows a clean message rather than a raw WHMCS error page. Turn on Diagnostics logging in Settings to see the detail, then reload. Most load-time issues clear on a second load as any pending schema update applies.
KPI weights look wrong
Weights and percentages display exactly as stored (10 shows as 10%, not 1%). If a weight total warning appears, it means that person's weights don't add to 100% — adjust them on the KPI setup screen.
FAQ
Does HostCRM change my WHMCS data?
No. It reads clients, invoices and tickets, and stores its own data in dedicated tables. Deactivating never deletes anything.
What happens to my data if the license lapses?
Nothing is lost. The admin UI locks, but background automation keeps running and all your logged data stays intact. Re-activate a valid license and everything's there.
Can staff see each other's KPIs?
No. The team overview is manager-only. When you enable the staff view, each person sees only their own scorecard.
Can I turn off the bonus/ledger system?
Yes — simply leave task bonuses at zero. Tasks then work as plain internal assignments with no payment.
Does the daily digest need configuration?
Just enable it in Settings. It sends on the first cron run each day using your server's mail setup — send yourself a test if none arrive.
Which WHMCS versions are supported?
HostCRM adapts to schema differences across WHMCS versions (for example, ticket columns), so it runs on current and recent releases.
Data & privacy
- Storage. All HostCRM data lives in
mod_hncrm_*tables in your WHMCS database. It never leaves your server except for the license check. - License check. The only outbound call is the license validation to the licensing server, which sends the license key, domain, server IP and install path — no customer data.
- Call-me widget. Submissions are validated, rate-limited and honeypot-protected, and stored only in your database.
- Retention. Deactivating the module keeps all data. Removal of data is only ever explicit.