Skip to main content

Communication Channel

The Communication Channel module is the central command station for managing how your organization communicates with its users, customers, and team members.

When important events happen in the system—such as a new user signing up, an invoice being generated, or a security alert triggering—Orbit needs to know exactly what message to send and where to send it.

This page allows administrators to:

  • Turn specific notifications on or off (e.g., disabling the "Welcome Email" while keeping the "Password Reset" email active).
  • Choose which medium to use (Email, WhatsApp, or both).
  • Customize the exact text, layout, and language of the messages being sent.
  • Connect specific external gateways (like Office 365 or WhatsApp Business) to specific modules.

If this section is not configured correctly, users may miss critical alerts, or clients might receive poorly formatted, generic system emails instead of your company's branded messaging.

Why Communication Channels Exist​

To understand how to use this page, it helps to understand the journey of a notification.

When a business event occurs, the system does not immediately send an email. Instead, it follows a strict ruleset defined on this page:

  1. Business Event: An action occurs (e.g., "Invoice Generated").
  2. Template: The system looks up the "Invoice Generated" template.
  3. Channel Check: It checks if you have toggled Email or WhatsApp to "ON".
  4. Gateway Check: It verifies that you have actually connected an Email or WhatsApp account to handle the delivery.
  5. Delivery: The message is formulated using your customized text and dispatched.

(Note: Whether failed notifications automatically retry is a backend process and cannot be confirmed from the frontend implementation.)

Interface Breakdown & Containers​

The Communication Channel screen is highly interactive and features multiple containers and tools. Here is every element you will encounter on the main screen:

Top Toolbar​

  • Search Bar: A text input in the top right that allows you to instantly filter the visible templates by name or description.
  • Global WhatsApp Sync (Arrows Icon): Manually triggers a synchronization with Meta to update the status (Approved, Pending, Rejected) of all WhatsApp templates in the current module.
  • Fullscreen Mode (Expand Icon): Pops the entire Communication Channel dashboard out into a full-screen overlay, hiding the main Orbit navigation for distraction-free editing. A floating button in the bottom right allows you to exit fullscreen.

The Module Sidebar (Left)​

Not all notifications belong together. The left sidebar groups templates into logical Modules (e.g., HR, Finance, Marketing).

  • Clicking a module loads the notification templates specific to that area.
  • Modules have a specific connection_type—they either apply to the entire Organization, or they are broken down by Project.

Project Context Tabs​

If you click a Project-based module in the sidebar, a scrollable row of Project Tabs appears at the top of the main content area.

  • This allows you to define entirely different email templates and gateway connections for Project A versus Project B.
  • Selecting a tab loads the templates and connections exclusively for that project.

Main Content Area & Watermark​

The center area displays your templates. In the background, a large, rotated, faint watermark displays the name of the currently selected Group (or Project) to ensure you always know what context you are editing.

Gateway Connection Banner​

At the top of the template list sits the Gateway Banner. This tells you exactly how messages are being delivered.

  • Email Gateway Avatar & Details: Shows the logo (e.g., Gmail, Office 365), Display Name, Account Email, and Platform Name.
  • WhatsApp Gateway Avatar & Details: Shows the Meta/WhatsApp logo, Account Name, Phone Number ID, and Platform Name.
  • Project Context Indicator: If in a project module, it explicitly lists the Project Name on the right side.
  • NOT CONFIGURED: If either gateway is missing, a prominent outlined chip reads "NOT CONFIGURED". Templates cannot send messages through a missing gateway.

Connection Settings Modal (The Gear Icon)​

Clicking the Settings (Gear) icon on the banner opens the Connection Settings Modal.

  • Project Mode Tabs: If configuring a project module, you can switch between projects inside the modal to configure them rapidly.
  • Access Errors: If you lack permission to view connections for a specific project, a yellow banner will appear warning you that "Project access is required," along with a link to request access.
  • Email Dropdown: Select an Email Gateway from the list of integrations connected to your Orbit workspace. Includes inherit/fallback options.
  • WhatsApp Dropdown: Select a WhatsApp Gateway. You will see the Account Name and Phone ID.
  • WhatsApp Scope Warning: A colored banner explains whether this module pulls from Organization-level connections or Project-level connections. If none exist, it provides a direct hyperlink to the Integrations page to set one up.
  • Apply to Other Modules: (Organization modules only) A list of chips representing all other modules. Clicking these chips allows you to instantly apply the chosen gateways to multiple modules at once.

Template Card Anatomy​

Each card represents a single automated notification. Every single element on the card has a specific function:

Header Section​

  • Template Name: The bold title (e.g., "User Welcome Email").
  • System / Custom Badge:
    • System (Outlined): The template is using the default Orbit wording.
    • Custom (Solid Primary Color): An administrator has overridden the text.
  • Sync Button (Two Arrows): (Project mode only, if Customized) Opens the Sync Menu to push this template's settings to other projects.
  • Reset Button (Clock/History): (If Customized) Reverts the template to the System Default, permanently erasing your custom text.

Toggle Controls​

  • Email Notification Toggle: Turns the email send on or off. Disabled if Email Gateway is disconnected.
  • Use HTML Format Toggle: Switches the email between rich HTML and Plain Text. Disabled if Email is turned off.
  • WhatsApp Notification Toggle: Turns the WhatsApp send on or off. Disabled if WhatsApp Gateway is disconnected, or if the template isn't mapped.

WhatsApp Status Row​

Because WhatsApp requires Meta approval, specialized controls appear for WhatsApp:

  • Status Chip: Indicates Meta's review status.
    • Green: Approved.
    • Yellow: Pending Meta review.
    • Red: Rejected by Meta. (Hovering over a red chip reveals a tooltip with the exact rejection reason from Meta).
  • Open Board (External Icon): Opens the WhatsApp Template Board for detailed deliverability stats.
  • Remove (Trash Icon): Withdraws the template, deleting it from your WhatsApp Business account and unmapping it.
  • Use Standard Template Button: If no template is mapped, this submits Orbit's standard blueprint to Meta for approval automatically.

A streamlined icon toolbar at the bottom of the card:

  • Email Preview (Eye): Opens a read-only preview of the email.
  • Email Customize (Pencil): Opens the Email Customizer Modal.
  • WhatsApp Preview (Green Eye): Opens a read-only preview of the WhatsApp message.
  • WhatsApp Customize (Green Pencil): Opens the WhatsApp Customizer dialog (allows rewording while keeping variables locked).
  • WhatsApp Mapping (Chain Link): Advanced feature. Opens the Mapping Modal to link a template you created directly in Meta Business Manager to this Orbit notification.

Customization Workflows​

1. Email Customizer Modal​

When you click the Email Pencil icon, the Customizer Modal appears:

  • Available Variables: A list of chips (e.g., {{first_name}}, {{invoice_amount}}) that you can insert into your subject or body.
  • Subject Input: Define the email subject line.
  • HTML / Text Tabs: Switch between editing the rich HTML version or the raw Plain Text version.
  • Preview Button: Injects sample data into your variables and renders the email exactly as the recipient will see it.
  • Security Validation: When you click Save, the system scans your HTML for malicious <script> tags or harmful attributes. If found, it blocks the save and alerts you. It also prevents saving if you use an invalid variable not listed in the Available Variables.

2. WhatsApp Customization & Mapping​

  • Customizing a Blueprint: Clicking the green Pencil allows you to reword the WhatsApp message. However, WhatsApp variables are strictly numbered ({{1}}, {{2}}). The editor locks these variables so you cannot accidentally break the mapping.
  • Mapping Modal (Chain Link): If you created a template in Meta Business Manager, you can map it here. The modal fetches your approved Meta templates. When selected, it scans the Meta template for numbered variables ({{1}}, {{2}}) and forces you to map each one to a valid Orbit variable (e.g., {{first_name}}) using dropdowns. If any variable is left unmapped, saving is blocked.

3. Syncing Across Projects​

If you are working inside a Project-based module and perfect an email template, you don't need to repeat the work:

  1. Click the Sync (Arrows) icon on the customized Template Card.
  2. The SYNC TO PROJECTS menu opens.
  3. A scrollable list of all other active projects appears with checkboxes.
  4. Select the destination projects.
  5. Click Sync to Selected. The system instantly copies your customized text, subject, and toggle states to all selected projects.

Technical Reference — Developers & QA​

This section contains implementation details verified directly from the OO-frontend repository.

Component Architecture​

  • Route: /org/communicationchannel
  • Main Component: src/routes/org/CommunicationChannelPage.tsx
  • Protection: Requires the org.commchannel.view permission to mount. Connecting gateways requires org.commchannel.manageconnection. Customizing requires org.commchannel.template.customize.

State & Scope Management​

The interface heavily relies on the concept of connection_type.

  • When group.connection_type === 'Organization', templates and gateways are fetched once for the group (groupId).
  • When group.connection_type === 'Project', the UI renders a <Tabs> component for project selection. API calls for templates, settings, and integrations append ?project_id={id} to scope the data strictly to the active tab. Connections are stored in connectionsCache keyed by Project ID.

API Interactions​

ActionEndpointMethodTrigger
Load Groups/org/comm-channel/groupsGETPage mount
Load Project Settings/org/comm-channel/groups/{id}/project-settingsGETSelecting a Project-type group
Load Templates/org/comm-channel/groups/{id}/templatesGETGroup selection or Tab change
Toggle Channel/org/comm-channel/templates/{id}/togglePATCHClicking Email/WhatsApp/HTML switches
Read Customize Data/org/comm-channel/templates/{id}/emailGETOpening Edit Email modal
Save Customization/org/comm-channel/templates/{id}/emailPUTSubmitting Edit Email modal
Reset to System/org/comm-channel/templates/{id}/emailDELETEClicking the Reset icon
Adopt WA Blueprint/org/comm-channel/templates/{id}/whatsapp/adoptPOSTClicking "Use standard template"
Remove WA Mapping/org/comm-channel/templates/{id}/whatsapp/removePOSTClicking the Trash icon on WA
Push Sync (Bulk)/org/comm-channel/templates/{id}/emailPUTFired in a Promise.all() loop for each selected destination project

QA Verification Checklist​

When testing the Communication Channel module, verify the following:

  • Gateway Banner Resolution: The banner correctly falls back to Organization-level connections if a Project-level connection is not explicitly set, but visually distinguishes them.
  • HTML Format Interlock: The "Use HTML Format" switch is disabled if the Email toggle is turned off.
  • WhatsApp Syncing: Clicking the green Sync icon in the top toolbar correctly hits the WhatsApp sync API and visually updates pending template chips to Approved/Rejected.
  • Dirty State Protection: Moving between project tabs while editing a template should gracefully handle unsaved changes (handled inside the child dialogs).
  • Meta Rejections: If Meta rejects a template, the red rejection chip should correctly display the whatsapp_rejection_reason inside a tooltip when hovered.
  • Full Screen Mode: Clicking the expand icon successfully triggers the portal overlay, preventing body scroll and trapping focus.
  • Security Validation: Entering <script>alert('xss')</script> into the Email HTML editor should trigger a validation toast and block the API PUT request.
  • Project Access Denial: Visiting the Connection Settings Modal for a project where the user lacks access should render a 403 PROJECT_ACCESS_REQUIRED inline banner instead of silently failing.
Last updated on