Host Front — Setup Guide

This guide explains how to connect your WHMCS installation to the Host Front widget so your customers can authenticate, view invoices, open tickets, and get AI support from your website.

Overview

The widget runs on your website (marketing site, client area, WordPress, etc.) and talks to the Host Front backend. The backend calls your WHMCS installation using the WHMCS Remote API — your browser and your customers never receive WHMCS API secrets.

Your website (widget embed)
        ↓
Host Front backend
        ↓
Your WHMCS server (Remote API)

You will need:

• Admin access to your WHMCS installation
• Access to the Host Front dashboard (tenant account)
• The hostname(s) where you plan to embed the widget (e.g. www.yourhost.com, clients.yourhost.com)
• An OpenAI API key (for the AI assistant)

Step 1 — Create WHMCS API credentials

The backend uses WHMCS API credentials (Identifier + Secret) to look up clients, invoices, tickets, and related data.

1. Log in to your WHMCS Admin Area.

2. Go to Setup → Staff Management → Manage API Credentials.

3. Click Generate New API Credential (or open an existing credential you want to reuse).

4. Set a descriptive Admin Username / label (e.g. Host Front).

5. Save the credential.

6. Copy and store securely:

   • Identifier
   • Secret (shown only once when created)

7. Under Allowed API Actions (or equivalent permissions on the credential), enable the WHMCS API actions listed in Required WHMCS API actions below. At minimum, enable every action for the widget features you plan to use.

Important: Treat the API secret like a password. Only enter it in the Host Front dashboard — never in your website HTML or the widget embed code.

Required WHMCS API actions

The backend calls WHMCS on behalf of authenticated customers. Each API credential can restrict which actions are allowed. In Setup → Staff Management → Manage API Credentials, edit your credential and enable the actions below for the features you use.

If an action is not enabled on the credential, the related widget feature will fail with a WHMCS API error.

Step 2 — Whitelist the backend IP address in WHMCS

WHMCS can restrict Remote API access by source IP. The Host Front backend makes all WHMCS API calls from its own servers, not from your browser or your customers' browsers.

If the backend IP is not allowlisted, WHMCS returns errors such as:

• Invalid IP x.x.x.x
• HTTP 403 Forbidden

Symptoms in the widget include failed login after OTP ("No account found for this email") even when the email exists in WHMCS.

Find the IP address(es) to allowlist

In your Host Front dashboard, open Settings → API access. You will see the backend egress IP address(es) that must be allowed in WHMCS.

When the platform is deployed to production, these will be the fixed, static IP address(es) of the production backend. Each tenant must add those IPs in their WHMCS admin — not their own office or home IP, and not end-user IPs.

If you self-host the backend, use the public outbound IP of the server running the API.

Add the IP(s) in WHMCS

1. In WHMCS Admin, go to Setup → General Settings.
2. Open the Security tab.
3. Find API IP Access Restriction.
4. Add each backend IP address (one per line or as WHMCS instructs). Use the actual IPs from your dashboard API access tab — do not use placeholder examples.
5. Click Save Changes.

Note: This is a global WHMCS security setting, separate from per-credential options. All Remote API calls from the Host Front backend must originate from an IP listed here.

Local development vs production

Step 3 — Configure WHMCS connection in the dashboard

1. Log in to the Host Front dashboard.

2. Open Settings → WHMCS connection.

3. Fill in:

   Field	Where to find it
   WHMCS System URL	WHMCS: Setup → General Settings → General → WHMCS System URL (e.g. https://billing.yourhost.com). Do not append /includes/api.php.
   API identifier	Setup → Staff Management → Manage API Credentials → your credential
   API secret	Same screen (re-enter if already saved)
   Allowed domains	Hostnames where the widget will be embedded (see Step 5). Not a WHMCS setting.

4. Click Save connection.

5. Click Test connection.

   • Success: WHMCS URL, credentials, and IP allowlist are correct.
   • Failure with Invalid IP: Return to Step 2 and add the reported IP under API IP Access Restriction.
   • Other errors: Check URL, identifier, secret, and that Remote API is enabled on your WHMCS install.

Step 4 — Configure AI settings

1. Open Settings → AI Model.
2. Enter your OpenAI API key (platform.openai.com → API keys).
3. Choose a model (e.g. GPT-4o Mini for cost/capability balance).
4. Save and use Test connection if available.

Step 5 — Set allowed embed domains

The backend only serves widget configuration to websites you explicitly allow.

1. In Settings → WHMCS connection, find Allowed domains.

2. Enter each hostname where the widget will load, one per line or comma-separated, for example:

   yourhost.com
   www.yourhost.com
   clients.yourhost.com
   

3. Save.

Include all variants you use (www and non-www, subdomains, etc.). Requests from other origins are rejected.

Step 6 — Enable features (optional)

Under Settings → Features, turn on capabilities you want customers to use via the AI, for example:

• View invoices
• Generate payment links
• Read/create support tickets
• Initiate password reset
• Check credit balance

Save after changes.

Step 7 — Embed the widget on your site

1. In the dashboard, open Settings → Embed code.
2. Copy the embed snippet. It looks like:

<script
  src="https://dashboard.your-saas.com/widget.js"
  data-tenant-id="YOUR_TENANT_ID"
  data-api-base-url="https://api.your-saas.com"
  async
></script>

3. Paste the snippet into your site template before the closing </body> tag.

Common placements:

• WHMCS client area theme footer
• WordPress theme footer or a header/footer plugin
• Static site / Next.js layout component

Attributes:

No WHMCS addon or plugin is required for the widget embed.

Step 8 — Verify end-to-end

1. Open a page on an allowed domain where you embedded the script.
2. Open the widget launcher.
3. Enter the email of a real WHMCS client.
4. Enter the OTP code sent to that email.
5. Confirm you are signed in and can use enabled self-service options (e.g. pay an invoice, view tickets).

Troubleshooting

"No account found for this email" (after OTP)

Often not a missing client — commonly WHMCS blocked the API lookup due to IP restriction.

1. Check Test connection in the dashboard or backend logs.
2. If you see Invalid IP x.x.x.x, add that IP under Setup → General Settings → Security → API IP Access Restriction.
3. Confirm the email exists as a client in WHMCS (Clients → View/Search Clients).

"Invalid IP …" on Test connection

Add the shown IP under Setup → General Settings → Security → API IP Access Restriction and save.

Widget does not load / bootstrap fails

• Confirm the embed domain is in Allowed domains.
• Confirm data-api-base-url and data-tenant-id match the dashboard.
• Check browser devtools → Network for errors on /api/widget/bootstrap.

OTP never arrives

1. Confirm the backend has RESEND_API_KEY set (see WHMCSAIAssistant_backend/.env.example) and the API process was restarted after changing .env.
2. Check the Resend dashboard Logs for delivery errors.
3. Resend dev sender (onboarding@resend.dev): emails can only be delivered to the email address on your Resend account. Use that address when testing, or verify your own domain in Resend and set MAIL_FROM to an address on that domain.
4. If RESEND_API_KEY is not set, the backend logs the OTP to the server console instead of sending mail (local dev fallback).
5. Check spam/junk folders.

Connection works in dashboard but not on site

• Allowed domains may omit the site you are testing.
• Use HTTPS in production; mixed content can block scripts on secure pages.

Security checklist

• Production backend IP(s) added under WHMCS API IP Access Restriction
• WHMCS API secret stored only in the dashboard, never in client-side code
• Allowed domains lists only your real site hostnames
• Widget embed uses HTTPS URLs in production
• OpenAI key kept in dashboard settings, not exposed to the browser

Quick reference — WHMCS admin paths

Support

If Test connection succeeds but customers still cannot log in, verify the client email in WHMCS matches exactly what they enter in the widget. If Test connection fails with an IP error, complete Step 2 before retrying.