Communication Rules

Communication Rules wires ProxPanel up to your transport providers and decides which events fire which message to which subscribers. The system has three channels — Email (SMTP), SMS (Twilio, Vonage, or a custom HTTP API), and WhatsApp (Ultramsg-compatible gateways) — and a small set of canonical events: FUP threshold reached, expiry approaching, subscriber expired, disconnected, renewed, invoice issued, invoice paid, payment failed, password changed, ticket reply received.

Every outbound message is rendered from a template, sent through the configured channel, and logged so you can see exactly what was delivered to whom and whether the provider accepted it.

How to get here

• Sidebar → Communication (chat icon).
• Direct URL: /communication.

Admins only. Resellers do not configure global gateways — they can, however, override the WhatsApp gateway per-reseller (see Reseller branding) so each reseller sends from their own business number.

Layout

Tab	Purpose
Channels	SMTP / SMS / WhatsApp credentials, test buttons, enable/disable per channel.
Templates	Reusable message bodies with variable substitution ({{username}}, {{expiry_date}}, etc.).
Rules	Map events → templates → channels. Toggle on or off per rule.
Logs	Every outbound message: timestamp, recipient, channel, provider response, retry state.

Channels

Email (SMTP)

Configure host, port, security mode (STARTTLS, SSL/TLS, NONE), username, password, from-name, and from-address. ProxPanel speaks standard SMTP — anything with a username + password works (Gmail, Office 365, SendGrid SMTP, your own postfix). The Send Test Email button posts POST /api/notifications/test-smtp, which sends a one-line message to the address you specify and returns the provider’s response so you can debug TLS issues without going through a real event.

Connection pooling is built in: a single SMTP socket is reused across consecutive sends until idle for 30 seconds. At scale (5,000+ subscribers, daily renewal blasts) this is the difference between a 30-second batch and a 30-minute one.

SMS

Three drivers are supported:

Twilio

• Account SID + Auth Token + From number.
• Uses the official Twilio Messages API.
• Cost-per-message is whatever Twilio charges in the destination country — store the rate in Settings to estimate monthly SMS spend in Reports.

Vonage (Nexmo)

• API Key + API Secret + From identifier (alphanumeric or shortcode, depending on country).
• Uses the Vonage SMS API.
• Good fallback when Twilio is unavailable in your market.

Custom HTTP

• Endpoint URL + method (GET or POST) + body template + auth header.
• The endpoint receives the rendered message + recipient number; ProxPanel reads the response code to decide if delivery succeeded.
• Use this for local SMS gateways (Lebanon, Egypt, Pakistan, etc.) where Twilio is impractical.

The Send Test SMS button (POST /api/notifications/test-sms) sends a probe message and surfaces the provider’s response. If you see HTTP 401, your credentials are wrong; HTTP 200 with error_code in the body usually means the destination is blocked.

WhatsApp

ProxPanel speaks the Ultramsg HTTP API (and any gateway that emulates it). You provide:

• Instance ID (instanceXXXXX from the gateway dashboard).
• API Token.
• Optional gateway base URL for self-hosted or other-vendor deployments.

Media is supported — invoice PDFs, payment receipts, and any other file path can be sent as an attachment. The gateway maintains its own WhatsApp Web session; if it disconnects (phone offline, QR re-pair required), test messages will fail with Client outdated (405) and the answer is to update the gateway, not the credentials.

Note

For the Titan Systems WhatsApp gateway used in several reference deployments, the fix when test messages fail is wget https://raw.titansystems.ph/wa/linux.zip on the gateway host. ProxPanel itself does not need to be restarted.

Templates

A template is a Markdown-flavoured body with {{variable}} placeholders. Available variables depend on the event but always include:

• {{username}}, {{full_name}}, {{phone}}, {{email}} — subscriber identity.
• {{expiry_date}}, {{plan_name}}, {{plan_price}} — service state.
• {{balance}}, {{last_payment}}, {{invoice_url}} — billing state.
• {{company_name}}, {{support_phone}}, {{support_email}} — branding (from Settings).

POST /api/communication/templates creates a template; PATCH /api/communication/templates/:id edits it. Each template is tagged with the channel it belongs to — a WhatsApp template can use Unicode emoji; an SMS template should stay under 160 characters to avoid concatenation costs.

The handler renders with simple string-substitution — it does not evaluate arbitrary Go templates, so there is no template-injection surface from untrusted variables.

Rules

A rule binds three things together:

Field	Description
Event	One of: fup_threshold_reached, expiry_7_days, expiry_3_days, expiry_today, expired, disconnect, renewed, invoice_issued, invoice_paid, payment_failed, password_changed, ticket_reply.
Channel	email, sms, or whatsapp.
Template	The template to render. Must belong to the same channel.
Enabled	Toggle to pause without deleting.

Multiple rules can fire on the same event — for example, expiry-in-3-days can trigger both an SMS and a WhatsApp message. Each rule fires independently; if one channel’s provider is down, the others still fire.

Rules are also scoped by target audience:

• All subscribers.
• A specific reseller (sub-reseller logic respected).
• A specific service plan.
• A custom filter (e.g., “only subscribers with payment_method=cash”).

Event triggers

Events are fired from inside their respective subsystems:

• fup_threshold_reached — fired by QuotaSync when a subscriber crosses a FUP tier (3 daily + 3 monthly tiers).
• expiry_7_days, expiry_3_days, expiry_today — fired by the daily ExpiryReminder service, which runs once per day in your configured timezone.
• expired — fired on the same daily run when expiry_date < today.
• disconnect — fired by the operator action or by FUP enforcement.
• renewed — fired by the Renew handler and by the auto-renew path from collectors.
• invoice_issued, invoice_paid — fired by the Invoice handlers.
• password_changed — fired when an admin or the subscriber changes their portal password.
• ticket_reply — fired when a customer or admin posts a reply on a ticket.

All events check rule.enabled before sending; a disabled rule is a no-op.

Logs

ListLogs returns every outbound message in reverse-chronological order. Columns:

Column	Notes
Time	UTC; rendered in panel timezone.
Event	The trigger that fired the message.
Recipient	Subscriber + their phone/email.
Channel	Email / SMS / WhatsApp.
Status	queued, sent, delivered, failed.
Provider response	Verbatim body returned by SMTP server, Twilio, Vonage, or Ultramsg.
Retries	Up to 3 retries with exponential backoff before giving up.

Click a row to see the full rendered message body — useful when a customer asks “what exactly did you tell me?”

Common workflows

Set up WhatsApp expiry reminders

1. Channels → WhatsApp — paste the Instance ID and API Token from your gateway. Click Send Test WhatsApp, enter your number, confirm you receive it.
2. Templates → New — channel = WhatsApp, body = Hi {{full_name}}, your internet expires on {{expiry_date}}. Renew at {{invoice_url}} to avoid disconnection.
3. Rules → New — event = expiry_3_days, channel = WhatsApp, template = the one you just made, audience = All subscribers. Enable.
4. Save. The next daily expiry sweep will trigger the rule for every subscriber 3 days out.

Send a payment receipt over SMS after a collector marks paid

1. Make sure your SMS channel is configured and tested.
2. Templates → New — channel = SMS, body = Thank you {{full_name}}. Payment of {{amount}} received. New expiry: {{expiry_date}}. Keep it short — 160 characters or less.
3. Rules → New — event = invoice_paid, channel = SMS, template = above, audience = All. Enable.
4. Next time a collector marks an assignment collected, the SMS goes out automatically.

Investigate why a customer says “I never got the email”

1. Open Logs, search by the subscriber’s username.
2. Check the latest row for the matching event (e.g., invoice_issued).
3. If status = failed, the provider’s response tells you why (bounced address, throttled, auth error).
4. If status = sent but the customer denies it, ask them to check spam. The audit trail is on our side.

Permissions

Permission	What it gates
communication.view	See the page and Logs.
communication.edit	Edit channel credentials, templates, and rules.
communication.test	Run the Send Test buttons.

Channel credentials are masked once saved — admins see the last four characters. Editing requires re-entering the secret, so a casual viewer cannot exfiltrate Twilio tokens.

Related pages

• Billing & Invoices — invoice events feed into Communication rules.
• Cash Collection — collector WhatsApp receipts use the WhatsApp channel.
• Tickets — ticket reply notifications go through the same gateways.
• Reports — outbound message volume by channel.
• Settings — company name and branding variables available in templates.