Communications
Three channels reach your residents — email, WhatsApp, SMS. Here's how each is configured and used.
Channel overview
- Email — long-form, formatted (HTML), supports attachments. Default for invoice receipts, payment confirmations, statements, password resets.
- WhatsApp — short, conversational. Best for reminders, urgent notices, invites. Two underlying transports: linked-device (QR scan, free) and Meta Cloud API (official, more reliable).
- SMS— short, no formatting, charges per 160-char unit. Best for time-sensitive alerts to residents who don't check email/WhatsApp.
Two-tier configuration
Each channel has the same pattern:
- Tenant config first. If your community has its own credentials set at
/admin/settings, they're used. - Platform fallback. If not, the platform-wide system account is used (configured by the HOAPortal team at
/platform/...).
Day one, you can rely entirely on the platform account — every channel works out of the box. Configure your own only if you want a custom sender name / separate billing.
Email (SMTP)
/admin/settings → Email (SMTP). The form accepts standard SMTP credentials (host, port, user, password, From address). The most common providers:
- Gmail / Google Workspace:
smtp.gmail.com:587, STARTTLS, requires an App Password (not your normal Google password). - Resend:
smtp.resend.com:465, TLS on, user isresend, password is your Resend API key. - SendGrid:
smtp.sendgrid.net:587, user isapikey, password is the SendGrid API key. - Zoho Mail:
smtp.zoho.com:587, STARTTLS, App-specific password required.
After saving, click Send test email to me. If it lands in your inbox, residents will get yours fine. If it fails, the error message usually tells you exactly what's wrong (auth failed = bad password; connection refused = wrong host/port).
WhatsApp — linked device
/admin/whatsapp. The page shows a QR code; scan it from the WhatsApp mobile app on the community's phone (Settings → Linked devices → Link a device). Once connected, the portal sends through that phone. Per-community: each tenant has its own linked device, so messages show the community's number as the sender.
We include built-in anti-ban protection — rate-limiting (max 8 messages/minute), Gaussian-jittered delays between sends (1.5–5s), post-reconnect throttle, and auto-pause when the internal risk score goes high. These are tuned for HOA-volume bursts (50–200 messages on reminder days).
If a number gets banned anyway: the Meta Cloud API channel takes over automatically if configured. Re-link a fresh number from the same admin page.
WhatsApp — Cloud API (optional second channel)
Meta's official business API. Requires a Meta Business account, phone number, and access token. Set up at /admin/whatsapp → Cloud API. When both linked device and Cloud API are configured, the portal uses whichever you marked as primary and automatically falls back to the other on failure. The notification log shows which channel ultimately delivered.
SMS (mNotify)
/admin/settings → SMS (mNotify). mNotify is the Ghana-based SMS gateway we use. Sign up at mnotify.com, top up credit, register a sender ID (11-char alphanumeric, e.g. "GREENOPAL"), and copy the API key from their dashboard.
After saving, Send test SMS to me verifies the config.
Sending messages
Most of the time, HOAPortal sends automatically. You don't click "send" for routine flows:
- Payment approved/rejected → email/WhatsApp/SMS.
- Issue acknowledged → email.
- Poll opens → email to every active resident.
- Welcome invite → email + WhatsApp + SMS.
- Dues reminders → email/WhatsApp/SMS on scheduled days.
- Monthly statement → email on 1st of month.
Manual triggers (for one-off sends or after fixing a setting):
/admin/payments → Send reminders— fires dues reminders right now to every resident with a balance./admin/payments → Send statements— emails last month's statement. Idempotent unless you Shift-click./admin/residents → Invite everyone— bulk welcome to every household without a login.
Delivery log
Every send (success or failure) writes to the notifications table. The admin notifications page (/admin/notifications) lets you filter by channel, status, related entity, and see the full body and error reason. Useful when a resident says "I never got my reminder" — you can see exactly when and whether it was sent, and on which channel.