Communications

The Communications module provides comprehensive multi-channel messaging capabilities for your school. From announcements and newsletters to real-time chat and automated campaigns, this module ensures effective communication with students, parents, staff, and the broader school community.

---

Navigation path

Communication (segment: communication)

Sub-section	Path	Description
Dashboard	communication	Overview and quick actions
Announcements	communication/announcements	School-wide announcements
Campaigns	communication/campaigns	Bulk messaging campaigns
Chats	communication/chats	Real-time messaging
Templates	communication/templates	Message templates
Topics	communication/topics	Communication topics
Preferences	communication/preferences	User preferences
Subscriptions	communication/my-subscriptions	My subscriptions
Suppressions	communication/suppressions	Blocked addresses
Notifications	communication/notifications	Notification center

---

Communications architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                    Communications Management System                      │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                      Communication Channels                       │   │
│  │                                                                   │   │
│  │   📧 Email  •  📱 SMS  •  🔔 Push  •  💬 In-App  •  📞 Voice     │   │
│  │                     •  💚 WhatsApp  •  💭 Chat                    │   │
│  │                                                                   │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                   │                                      │
│         ┌─────────────────────────┼─────────────────────────┐           │
│         │                         │                         │           │
│         ▼                         ▼                         ▼           │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────────┐  │
│  │  Announcements  │    │   Campaigns     │    │      Chats          │  │
│  │                 │    │                 │    │                     │  │
│  │  School-wide    │    │  Bulk targeted  │    │  Direct & Group     │  │
│  │  notices        │    │  messaging      │    │  conversations      │  │
│  │                 │    │                 │    │                     │  │
│  └────────┬────────┘    └────────┬────────┘    └──────────┬──────────┘  │
│           │                      │                        │             │
│           └──────────────────────┼────────────────────────┘             │
│                                  │                                      │
│                                  ▼                                      │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                        Templates Engine                           │   │
│  │                                                                   │   │
│  │   Handlebars • Liquid • Markdown • MJML • Plain Text              │   │
│  │   Variable substitution • Preview rendering                       │   │
│  │                                                                   │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                  │                                      │
│         ┌────────────────────────┼────────────────────────┐             │
│         │                        │                        │             │
│         ▼                        ▼                        ▼             │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────────┐  │
│  │    Topics       │    │  Subscriptions  │    │   Preferences       │  │
│  │                 │    │                 │    │                     │  │
│  │  Categories &   │    │  User opt-in/   │    │  Channel settings   │  │
│  │  organization   │    │  opt-out        │    │  Quiet hours        │  │
│  │                 │    │                 │    │                     │  │
│  └─────────────────┘    └─────────────────┘    └─────────────────────┘  │
│                                                                          │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                     Delivery & Tracking                           │   │
│  │                                                                   │   │
│  │   Outbox queue • Retry policies • Delivery logs • Analytics       │   │
│  │   Suppressions • Compliance checks • Rate limiting                │   │
│  │                                                                   │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

---

Part 1: Communication channels

Messages can be delivered through multiple channels.

Channel definitions

Channel	Description	Best for
email	Email messages	Detailed communications, newsletters, documents
sms	SMS text messages	Urgent alerts, reminders, confirmations
push	Mobile push notifications	Real-time alerts, updates
in_app	In-application notifications	System messages, activity updates
chat	Real-time chat messages	Direct conversations, group discussions
voice	Voice calls	Critical alerts, emergencies
whatsapp	WhatsApp messages	Parent communication, rich media

Channel selection guide

Scenario	Recommended channel
Monthly newsletter	Email
Emergency school closure	SMS + Push
Fee payment reminder	Email + SMS
Daily announcements	In-app
Parent-teacher discussion	Chat
Attendance notification	Push
Event invitation	Email
Urgent safety alert	SMS + Voice

---

Part 2: Announcements

School-wide announcements for broadcasting important information.

Announcement types

Type	Description	Icon
general	General announcements and updates	FileText
news	News and school updates	Newspaper
event	Event announcements	Calendar
alert	Important alerts and notices	AlertCircle

Priority levels

Priority	Description	Color	Use case
low	Low priority	Gray	FYI messages
normal	Standard priority	Blue	Regular updates
high	High priority	Amber	Important notices
critical	Critical priority	Red	Emergencies

Announcement statuses

Status	Description
draft	Not published, editable
published	Live and visible
archived	No longer active

Creating an announcement

1. Navigate to Communication → Announcements
2. Click New Announcement
3. Fill in details:
   • Title (required)
   • Content (required) — Rich text editor
   • Summary — Short description
   • Type — General, news, event, alert
   • Priority — Low, normal, high, critical
4. Configure visibility:
   • Is Public — Visible outside school
   • Allow Comments — Enable discussions
5. Set scheduling:
   • Publish At — Schedule for later (optional)
   • Expires At — Auto-archive date (optional)
6. Select audience:
   • Everyone
   • By role (students, parents, teachers, staff)
   • By grade level
   • By class
   • By department
   • Specific users
7. Add attachments (optional)
8. Add tags (optional)
9. Save as draft or publish

Audience targeting

Target type	Description	Example
all	Everyone in school	All-school assembly notice
role	Specific user roles	Teachers-only meeting
grade	Specific grade levels	Grade 10 exam schedule
class	Specific classes	Class 8A field trip
department	Specific departments	Science department update
user	Individual users	Award recipients

Announcement actions

Action	Description
Publish	Make visible to audience
Schedule	Set future publish date
Archive	Remove from active view
Edit	Modify (if draft/published)
Delete	Permanently remove
Duplicate	Create copy

Bulk operations

• Bulk Publish — Publish multiple drafts
• Bulk Archive — Archive multiple announcements

---

Part 3: Campaigns

Targeted bulk messaging campaigns for coordinated communications.

Campaign types

Type	Description	Icon
newsletter	Regular newsletters	Mail
announcement	Broadcast announcements	Zap
alert	Urgent alerts	AlertCircle
reminder	Scheduled reminders	Clock
custom	Custom campaigns	MessageSquare

Campaign statuses

Status	Description	Terminal
draft	Being prepared	–
scheduled	Scheduled for sending	–
processing	Currently sending	–
completed	Successfully sent	✓
cancelled	Manually cancelled	✓
failed	Delivery failed	✓

Campaign workflow

┌─────────────────┐
│      Draft      │ ← Create campaign
└────────┬────────┘
         │
    ┌────┴────────┐
    │             │
 Schedule      Start
    │             │
    ▼             │
┌─────────────────┐       │
│   Scheduled     │───────┘
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Processing    │ ← Sending messages
└────────┬────────┘
         │
    ┌────┴────────┐
    │             │
 Success       Fail
    │             │
    ▼             ▼
┌─────────────────┐    ┌─────────────────┐
│   Completed     │    │     Failed      │
└─────────────────┘    └─────────────────┘

Creating a campaign

1. Navigate to Communication → Campaigns
2. Click New Campaign
3. Configure basics:
   • Name (required)
   • Description
   • Type — Newsletter, announcement, alert, reminder, custom
   • Channel — Email, SMS, push, in-app, multi-channel
   • Priority — Low, normal, high, critical
4. Select template (optional)
5. Define audience filters:
   • Roles
   • Grade IDs
   • Class IDs
   • Department IDs
   • Specific user IDs
   • Opt-in status
6. Configure delivery:
   • Scheduled At — When to send
   • Delivery Window — Start and end times
   • Rate Limit — Messages per minute
7. Set retry policy:
   • Max Attempts
   • Backoff Seconds
8. Save or schedule

Audience filters

Filter	Description
roles	Target specific roles
gradeIds	Target grade levels
classIds	Target classes
departmentIds	Target departments
userIds	Specific users
hasOptedIn	Only users who opted in

Campaign statistics

Metric	Description
total	Total recipients
sent	Successfully sent
delivered	Confirmed delivered
failed	Delivery failed
opened	Opened by recipient
clicked	Links clicked
optedOut	Unsubscribed

Message statuses

Status	Description
draft	Not sent
queued	In queue
pending	Awaiting delivery
processing	Being sent
sent	Sent to provider
delivered	Confirmed delivered
opened	Opened
clicked	Link clicked
read	Marked as read
failed	Delivery failed
cancelled	Cancelled

---

Part 4: Real-time chats

Direct and group messaging for real-time communication.

Conversation types

Type	Description	Use case
direct	One-on-one	Private discussions
group	Multiple participants	Team collaboration
channel	Broadcast channel	Department updates

Conversation visibility

Visibility	Description
private	Only participants can see
org	Organization-wide visible
tenant	Tenant-wide visible

Participant roles

Role	Permissions
owner	Full control, can delete
admin	Manage participants
member	Read and send messages

Message types

Type	Description
text	Plain text message
image	Image attachment
file	File attachment
system	System notification
voice	Voice message

Starting a conversation

1. Navigate to Communication → Chats
2. Click New Conversation
3. Select conversation type:
   • Direct message
   • Group chat
   • Channel
4. Search and add participants
5. Enter title (for groups/channels)
6. Set visibility
7. Create conversation
8. Start messaging

Chat features

Feature	Description
Real-time messaging	Instant message delivery
Read receipts	See when messages are read
Typing indicators	See when others are typing
Replies	Reply to specific messages
Mentions	@mention participants
Attachments	Share files and images
Edit messages	Modify sent messages
Delete messages	Remove messages
Mute conversations	Disable notifications
Archive	Hide from main list

Chat workspace layout

Panel	Content
Sidebar	Conversation list, search
Message area	Chat history, composer
Info panel	Participants, details

Message actions

Action	Description
Reply	Reply to message
Edit	Modify message
Delete	Remove message
Pin	Pin important message
Copy	Copy message text

---

Part 5: Templates

Reusable message templates for consistent communications.

Template categories

Category	Description	Icon
newsletter	Regular updates and news	Megaphone
alert	Urgent notifications	AlertCircle
reminder	Scheduled reminders	Clock
marketing	Promotional content	Sparkles
academic	Educational content	GraduationCap

Template channels

Channel	Description
email	Email templates
sms	SMS templates
push	Push notification templates
in_app	In-app message templates
chat	Chat message templates
voice	Voice message scripts

Render engines

Engine	Syntax	Best for
handlebars	{{variable}}	General purpose
liquid	{{ variable }}	Complex logic
markdown	Markdown with vars	Rich text
mjml	MJML tags	Responsive emails
plain_text	Plain text	Simple messages

Template properties

Field	Type	Description
name	string	Template name
description	string	Description
category	enum	Category type
channel	enum	Target channel
renderEngine	enum	Rendering engine
subjectTemplate	string	Subject line template
bodyTemplate	string	Body content template
variables	array	Required variables
validationSchema	object	Variable validation
tags	array	Searchable tags
isSystem	boolean	System template
isActive	boolean	Currently active

Creating a template

1. Navigate to Communication → Templates
2. Click New Template
3. Enter template details:
   • Name (required)
   • Description
   • Category — Newsletter, alert, reminder, marketing, academic
   • Channel — Email, SMS, push, etc.
   • Render Engine — Handlebars, Liquid, etc.
4. Define subject template (for email)
5. Write body template:
   • Use variable syntax: {{variableName}}
   • Add conditional logic
   • Include formatting
6. Define variables:
   • Add variable name
   • Set type (string, number, boolean, array)
   • Mark as required/optional
   • Add default value
7. Test render with sample data
8. Save template

Variable syntax

Handlebars:

Dear {{studentName}},

Your attendance for {{month}} is {{attendancePercentage}}%.

{{#if hasAbsences}}
You have {{absenceCount}} absences.
{{/if}}

Liquid:

Dear {{ student_name }},

Your attendance for {{ month }} is {{ attendance_percentage }}%.

{% if has_absences %}
You have {{ absence_count }} absences.
{% endif %}

Test rendering

1. Open template
2. Click Test Render
3. Enter sample variable values
4. Preview rendered output
5. Verify formatting
6. Adjust template if needed

---

Part 6: Topics

Organize communications into subscribable topics.

Topic categories

Category	Description
academic	Academic updates and grades
operations	School operations
finance	Fees and payments
alerts	Urgent notifications
custom	Custom topics

Topic properties

Field	Type	Description
name	string	Topic name
description	string	Description
category	enum	Topic category
defaultChannel	enum	Default delivery channel
isSystem	boolean	System-defined topic
metadata	object	Additional data

Creating a topic

1. Navigate to Communication → Topics
2. Click New Topic
3. Enter details:
   • Name (required)
   • Description
   • Category — Academic, operations, finance, alerts, custom
   • Default Channel — Email, SMS, push, etc.
4. Save topic

Seeding topics

For new schools, seed default topics:

1. Navigate to Communication → Topics
2. Click Seed Topics
3. Select scope:
   • Tenant — Tenant-wide topics
   • School — School-specific topics
4. Confirm seeding

---

Part 7: Subscriptions

Manage user subscriptions to topics.

Subscription properties

Field	Type	Description
topicId	string	Topic subscribed to
subscriberId	string	User ID
subscriberType	enum	Staff, student, parent, contact
channel	enum	Delivery channel
deliveryMode	enum	Immediate, digest, muted
status	enum	Subscribed, unsubscribed, suspended

Subscriber types

Type	Description
staff	School staff members
student	Students
parent	Parents/guardians
contact	External contacts

Delivery modes

Mode	Description
immediate	Send immediately
digest	Bundle into digest
muted	Don't send

Subscription statuses

Status	Description
subscribed	Actively receiving
unsubscribed	Opted out
suspended	Temporarily paused

Managing subscriptions

Subscribe to topic:

1. Navigate to Communication → My Subscriptions
2. Find available topic
3. Select channel
4. Choose delivery mode
5. Click Subscribe

Unsubscribe from topic:

1. Find active subscription
2. Click Unsubscribe
3. Provide reason (optional)
4. Confirm

Bulk subscribe:

1. Select multiple topics
2. Choose channel
3. Subscribe all

---

Part 8: User preferences

Configure personal communication preferences.

Preference settings

Setting	Description
Channel Preferences	Enable/disable channels
Quiet Hours	Do not disturb period
Timezone	User timezone
Locale	Language preference

Setting quiet hours

1. Navigate to Communication → Preferences
2. Enable quiet hours
3. Set start time (e.g., 22:00)
4. Set end time (e.g., 07:00)
5. Select timezone
6. Save preferences

During quiet hours:

• Non-critical messages are held
• Critical alerts still delivered
• Messages delivered after quiet hours end

Channel preferences

Enable or disable specific channels:

Channel	Setting
Email	✓ Enable / ✗ Disable
SMS	✓ Enable / ✗ Disable
Push	✓ Enable / ✗ Disable
In-app	✓ Enable / ✗ Disable
WhatsApp	✓ Enable / ✗ Disable

---

Part 9: Suppressions

Manage addresses that should not receive messages.

Suppression reasons

Reason	Description
hard_bounce	Email permanently undeliverable
soft_bounce	Temporary delivery issue
complaint	Recipient complained (spam)
unsubscribe	User unsubscribed
manual	Manually suppressed
invalid	Invalid address format

Suppression sources

Source	Description
admin	Added by administrator
import	Imported from list
provider	From email/SMS provider
system	Automatic system action

Adding suppression

1. Navigate to Communication → Suppressions
2. Click Add Suppression
3. Enter details:
   • Destination — Email or phone number
   • Channel — Email, SMS, etc.
   • Reason — Why suppressed
   • Source — How added
4. Save suppression

Checking suppression status

Before sending, the system checks if destination is suppressed:

• If suppressed → Message not sent
• If not suppressed → Proceed with delivery

Removing suppression

1. Find suppression in list
2. Click Release
3. Confirm removal
4. Address can receive messages again

---

Part 10: Delivery and tracking

Monitor message delivery and performance.

Outbox management

Messages queue in outbox before delivery:

Status	Description
pending	Waiting in queue
processing	Being sent
held	On hold
completed	Successfully sent
failed	Delivery failed
cancelled	Cancelled

Retry policies

Configure automatic retry for failed messages:

Setting	Description
maxAttempts	Maximum retry attempts
backoffSeconds	Delay between retries

Delivery logs

Track each delivery attempt:

Field	Description
provider	Delivery provider used
providerMessageId	Provider's message ID
attempt	Attempt number
status	Delivery status
latencyMs	Delivery time
errorCode	Error code (if failed)
errorMessage	Error details

Rate limiting

Control message sending speed:

• Set messages per minute limit
• Prevents provider throttling
• Ensures consistent delivery

---

Permissions required

Action	Required permission
View announcements	announcements.view
Create announcement	announcements.create
Edit announcement	announcements.update
Delete announcement	announcements.delete
Publish announcement	announcements.publish
View campaigns	campaigns.view
Create campaign	campaigns.create
Edit campaign	campaigns.update
Delete campaign	campaigns.delete
Schedule campaign	campaigns.schedule
Start campaign	campaigns.start
View chats	chats.view
Create conversation	chats.create
Send messages	chats.send
Manage templates	templates.manage
Manage topics	topics.manage
Manage suppressions	suppressions.manage
View preferences	preferences.view
Update preferences	preferences.update

---

Best practices

Announcements

• Use appropriate priority levels
• Target relevant audiences only
• Set expiration for time-sensitive content
• Review before publishing
• Archive outdated announcements

Campaigns

• Test with small audience first
• Use templates for consistency
• Schedule during appropriate hours
• Monitor delivery statistics
• Handle failures promptly

Templates

• Use meaningful variable names
• Include fallback values
• Test with sample data
• Keep templates organized by category
• Version control important templates

Chats

• Respond to messages promptly
• Use appropriate conversation types
• Keep conversations on topic
• Archive completed discussions
• Respect notification preferences

Preferences

• Respect user quiet hours
• Honor channel preferences
• Process suppression requests immediately
• Maintain up-to-date contact info
• Handle bounces automatically

---

Troubleshooting

Message not delivered

Causes:

• Recipient suppressed
• Invalid destination
• Channel disabled
• Quiet hours active
• Provider error

Fix:

1. Check suppression list
2. Verify destination format
3. Check recipient preferences
4. Review delivery logs
5. Retry sending

Campaign stuck in processing

Causes:

• Rate limit reached
• Provider throttling
• Network issues
• Large audience

Fix:

1. Check outbox status
2. Review rate limits
3. Check provider status
4. Wait for queue to clear

Template rendering fails

Causes:

• Missing required variable
• Invalid variable type
• Syntax error
• Engine mismatch

Fix:

1. Check all variables provided
2. Verify variable types
3. Review template syntax
4. Test with sample data

Chat messages not syncing

Causes:

• Network connectivity
• Session expired
• Permission denied
• Server issue

Fix:

1. Check network connection
2. Refresh page
3. Re-authenticate
4. Contact support

---

Related documentation

• Dashboard — Notification widgets
• Students — Student contact info
• Staff — Staff contact info
• Events — Event notifications
• Settings — Communication settings