Communications

Part of the IP4CMS portal. ← All module guides

What it's for — Communications is the portal's outbound messaging hub. From here you reach your members and contacts across multiple channels — email, SMS and WhatsApp — either one message at a time through the Compose Wizard or as a bulk send to many recipients at once. You build messages from reusable templates, target them at saved recipient lists (channels) or live searches of your members, locations, accounts and transactions, and then send immediately or schedule for later. Every send is recorded in Send Logs so you can see what went out, to whom, and whether it succeeded.

Where to find it — Main left-hand navigation → Communications. The menu lands on Send Logs (/app/communications/send-logs). Sub-items in the nav include Compose (Compose Wizard), Bulk Communications, Saved Drafts, Send Logs, plus Surveys, E-Forms and News Stands (documented separately). The actual setup pages — Mail Servers, Email Wrappers, SMS Gateways, Omni Channels, Message Templates and Channels — live under Settings → Communication (see Before you start).

Before you start

• Licence module. Your tenant must have the communication module enabled for any of this to appear. The recipient-list feature (Channels) is gated behind a separate communication:channels sub-module — if it's off, the "Add from channels" options are hidden.
• Permissions. The Communications menu shows if you hold any of: communication:read:history, communication:send:email, communication:send:sms, communication:compose:send, communication:channels:read:all, communication:bulk_communications:read:all (or surveys:read:all). Specific actions need specific permissions — see Permissions & access.
• Mail server / SMS gateway must be configured first. You cannot actually deliver anything until the relevant transport is set up under Settings → Communication:
• Settings → Communication → Mail Servers — an outbound SMTP / Google / Microsoft mail server with a from-address (required for email).
• Settings → Communication → SMS Gateways — an SMS provider (Twilio, AWS SNS, Clickatell, SMS Portal, BulkSMS, Infobip, etc.) with a from-number (required for SMS).
• Settings → Communication → Omni Channels — a WhatsApp provider, e.g. Twilio WhatsApp or Infobip WhatsApp (required for WhatsApp).
• Settings → Communication → Email Wrappers and Message Templates — branding wrapper and the reusable templates the Compose Wizard and Bulk sends draw from.
• A Message Template that supports the channel you want to use is needed for Bulk Communications; the Compose Wizard can start from a blank draft instead.

Key tasks

Compose and send a single message (Compose Wizard)

The Compose Wizard is the main way to build and send one message. Open Communications → Compose (/app/communications/compose/new). It is a four-step wizard.

Step 1 — Select delivery method

1. Delivery Channels — pick one or more of Email, SMS, WhatsApp. (Only channels your tenant has transports for will deliver.)
2. Choose a Starting Point:

• Blank Draft — start empty.
• Template — pick from the grid of Message Templates (columns: Template, Channels, Priority; searchable; Use Template / View per row). Only templates supporting your chosen channels appear.
• Saved Draft — resume a previously saved compose draft (columns: Draft Name, Channels, Updated, Status).

1. Click Next.

Step 2 — Create message

The left panel holds Draft Details:

• Draft name (internal label for the draft).
• Email subject (shown when Email is selected).
• SMS content box ("Write the SMS content here") when SMS is selected.
• WhatsApp content box ("Write the WhatsApp content here") when WhatsApp is selected.
• Quick Placeholders — one-click insert buttons: {{member.first_name}}, {{member.last_name}}, {{location.name}}, {{account.account_name}}.
• Channel Summary — pills showing the active channels.

When Email is enabled, the centre shows a drag-and-drop HTML email builder (GrapesJS). Click Next.

Step 3 — Choose recipients

Add recipients three ways:

• Add Recipient — manually enter First name, Last name, Email, Mobile. At least one of email or mobile is required. This adds a draft-only recipient (it does not create a reusable channel subscriber).
• Add From Channels — import all subscribers from one or more saved Channels. You can also Manage a channel inline (add/remove ad-hoc subscribers) or Create Channel before importing.
• Add From Search — search and filter live entities — Members, Locations, Accounts, Transactions — and tick the ones to add. Use Add filter to narrow results.

Recipients appear in a grid (Name, Email, Mobile, Origin, Status) with a Remove action. Click Next.

Step 4 — Confirm and send

Review the summary (draft name, channels, recipient count — note primary recipients only; CC is not supported in bulk compose) and the per-channel previews (Email Preview with subject, SMS Preview, WhatsApp Preview). Then either:

• Send Message — sends now (button shows "Sending…").
• Schedule Message — opens a Send at date/time picker (must be at least ~60 seconds in the future) and queues it.

Save, resume and reuse drafts

• Compose drafts are saved automatically as you work. Find them under Communications → Saved Drafts (/app/communications/compose/drafts).
• Each draft row (Draft Name, Channels, Updated, Status) offers Resume Editing (reopens the wizard) and Duplicate Draft (clones it into a new draft).
• New Compose Wizard starts a fresh one.

Work with Message Templates (and predefined content)

Reusable, multi-channel templates are managed under Settings → Communication → Message Templates (not inside the Communications module). A Message Template can carry content for several channels at once:

• Email: subject, HTML content, plus the Mail Server, Email Wrapper and Mail Template to use.
• SMS: plain-text content + SMS Gateway.
• WhatsApp: content + Omni Channel (provider) and any provider template metadata.
• Push / In-app: title/body/icon/action URL or in-app content.
• Variables: placeholder names (e.g. {{first_name}}, dotted paths like {{account.balance}}) that are merged in at send time.
• Priority: Low / Normal / High / Urgent, and an Active flag.

Create one here first if you want it available as a starting point in Compose or as the basis for a Bulk Communication.

Set up mail wrapper (branding) templates

Settings → Communication → Email Wrappers holds the branded shells that surround your email content. A wrapper defines header/footer HTML, header/footer/body/content background and text colours, and a wrapper HTML body that must include a {{content}} placeholder — your message content is injected there at send time. Mark one as default to apply it automatically. (The plainer header/footer content templates are the related Mail Templates, also referenced from a Message Template.)

Bulk send to groups and audiences

For a campaign-style send driven by a Message Template, use Communications → Bulk Communications (/app/communications/bulk).

1. Click Add Bulk. Enter an optional Name, choose a Message template (only active templates appear; if none, the page links you to Set up message templates in Settings), and tick the Channels to use (Email / SMS / WhatsApp — only channels the template supports can be selected). Click Create.
2. On the bulk detail page, add receivers while it's still a draft:

• Add from channels — adds all subscribers of the selected Channels.
• Add from search — search/filter Members, Locations, Accounts or Transactions and select recipients.

1. Use Preview to see the rendered message with sample placeholder values, and Edit to change name/template/channels.
2. Send via Publish (immediate) or set a date/time and click Schedule.
3. The detail page shows live stats cards — Total recipients, Sent, Pending, Failed — and a receivers grid (Name, Email, Mobile, Origin, Status). You can only delete a bulk (or remove receivers) while it is a draft.

Bulk status values: draft → scheduled → published; each receiver is tracked as pending → sent / failed.

Manage channels and subscribers

A Channel is a reusable, named recipient list (an audience / distribution list). Channels live under Settings → Communication → Channels (/app/settings/communication-channels) — the old /app/communications/channels links redirect there.

• Add Channel — enter a Name (required) and optional Description.
• The channels list shows Name, Description, Subscribers (count) with View / Edit / Delete.
• On a channel's detail page, click Add subscriber and choose a Source:
• Ad-hoc — First name, Last name, Email, Mobile (at least one of email/mobile required).
• Entity — pick an entity type (Member / Location / Account) and supply the entity ID, linking the subscriber to a real record.
• Remove subscribers individually. Channels are then selectable in the Compose Wizard and Bulk Communications via "Add from channels".

View send history and logs

Communications → Send Logs (/app/communications/send-logs) is the record of everything sent.

• Columns: Status (Sent / Pending / Failed), Channel (Email / SMS badge), Date, Entity (linked record, if any) and Recipient.
• Use the filter toolbar (Add filter → field + value) to narrow by status, channel, date or linked entity.
• Click View Details on a row to open the detail panel: Channel, Status, Subject, Recipients (count), Sent By, Sent At, Linked Entity, and the full message Content (rendered HTML or plain text). Close when done.

How the data connects

• What you enter → where it's stored. Channels and their subscribers are saved as reusable lists (communicationchannel / communicationchannelsubscriber); a subscriber is either ad-hoc (typed-in name/email/mobile) or linked to a real Member / Location / Account. Message Templates, Email Wrappers, Mail Templates, Mail Servers, SMS Gateways and Omni Channels are tenant-level configuration records under Settings.
• A Compose or Bulk send captures its recipients as receivers — a snapshot of each recipient's name/email/phone is taken at the moment you add them, alongside a link to the source channel subscriber or entity. So editing a member later does not retroactively change an already-built send.
• What it feeds. Recipients are drawn from your members, contacts, locations, accounts and transactions (via Add From Search) and from saved channels. After a send, every message is written to Send Logs, and bulk sends additionally maintain per-receiver status (Sent / Pending / Failed with an error message). Placeholders such as {{member.first_name}} are merged from the linked entity at send time. Messages reach members through their email/SMS/WhatsApp; in-app/push content (where templates define it) surfaces in the member portal.
• Sends run asynchronously. Publishing or scheduling does not block the page — each recipient is queued as a background job (BullMQ on Redis) on the Communications queue. These jobs are at-least-once: a job can in principle run more than once after a crash/retry, so the system uses deterministic, idempotent job IDs (one job per bulk + receiver) to avoid sending the same recipient twice. Scheduled sends are released at the chosen time and then fan out one job per pending receiver. Because delivery is async, a recipient may briefly sit at Pending before flipping to Sent or Failed.

Permissions & access

The whole module requires the communication licence module (and communication:channels for the Channels/recipient-list features). Key permission strings:

Menu items, buttons (e.g. Compose Wizard on the Bulk list) and Settings tabs are hidden when you lack the matching permission or module, so different operators may see different subsets.

Tips & gotchas

• Set up a transport before you send. No mail server = no email delivery; no SMS gateway = no SMS; no omni channel = no WhatsApp. The Compose Wizard will let you build a message for a channel you can't actually deliver on, so confirm the relevant Settings → Communication transport exists first.
• Channels and the rest of the setup live in Settings, not Communications. The /app/communications/channels URLs redirect to Settings → Communication-Channels; templates, wrappers, gateways, mail servers and omni channels are all under Settings → Communication tabs.
• "Add Recipient" in Compose is draft-only. Manually typed recipients are not saved as reusable channel subscribers — use the Manage option inside Add From Channels, or the Channels settings page, if you want a reusable list.
• CC is not supported in bulk compose — every recipient is a primary recipient.
• You can only edit/delete while in draft. Once a bulk communication is published, it (and its receivers) are locked; removing receivers and deleting are draft-only actions.
• Bulk needs a Message Template; Compose doesn't. If the Bulk template dropdown is empty, create/activate one under Settings → Communication → Message Templates. The Compose Wizard can start from a blank draft instead.
• Channel checkboxes follow the template. In a Bulk send you can only tick channels the chosen Message Template actually supports.
• Scheduling has a minimum lead time — the "Send at" picker won't accept a time less than ~60 seconds out.
• Pending is normal, briefly. Because sends are queued background jobs, expect a short Pending window. A stuck Failed row carries an error message in the receiver record / Send Log detail.
• Email wrappers must contain {{content}}. A wrapper template without that placeholder has nowhere to inject the message body.