> For the complete documentation index, see [llms.txt](https://comunity.gitbook.io/learning.comunityplatform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://comunity.gitbook.io/learning.comunityplatform/26.x/toolkit-guides/communications/communication-settings.md). # Communication Settings This section outlines how to configure communication settings within the ComUnity Toolkit. It includes: * Global and environment-specific configuration * Supported communication channels * Provider setup requirements * Best practices for secure and reliable messaging workflows {% hint style="info" %} **Version Note** > The features in this section are available from ComUnity Toolkit version 25.2 onwards. > > If you’re planning to manage communication credentials independently for QA, Dev, and Production environments, upgrading to v25.2 or later is strongly recommended. > {% endhint %} ## Configuration Overview The Toolkit supports communication via multiple channels, including [**Email**](/learning.comunityplatform/26.x/toolkit-guides/communications/configuring-dynamic-action-templates-for-event-driven-communication-channels/email.md), [**SMS**](/learning.comunityplatform/26.x/toolkit-guides/communications/configuring-dynamic-action-templates-for-event-driven-communication-channels/sms-and-whatsapp.md), [**INAPP**](/learning.comunityplatform/26.x/toolkit-guides/communications/configuring-dynamic-action-templates-for-event-driven-communication-channels/inapp.md),[ **Push Notifications**](/learning.comunityplatform/26.x/toolkit-guides/communications/configuring-dynamic-action-templates-for-event-driven-communication-channels/push-notifications.md), and [**WhatsApp**](/learning.comunityplatform/26.x/toolkit-guides/communications/configuring-dynamic-action-templates-for-event-driven-communication-channels/sms-and-whatsapp.md). Configurations are managed at three levels: * Platform Defaults: Baseline channel and provider settings configured once per platform installation by a Toolkit administrator. Any project channel left set to Default inherits these settings. Project users cannot view or change them.\ \ Platform defaults are managed outside project settings. See Platform Administration: *<<\>>*.
* [Global Settings](#global-settings): Application-wide constants and default priorities used across all environments in your project. * [Environment-Specific Settings](#environment-specific-settings-v25.2-update): Channel and provider configurations tailored for each environment (for example Development, QA, Production). {% hint style="warning" %} *In deployed environments, users are fully responsible for setting up third-party providers and securely managing all credentials.*. {% endhint %} ## **Global Settings** Global settings define the baseline behaviour and default data for communications across your project. 1. **Channel Priorities** * Access: **Project Settings** > **Global** > **Communications** * Description: These settings establish the default delivery importance for each channel. | Channel | Example Priority | | -------- | ---------------- | | Email | Medium | | In-App | Medium | | SMS | Medium | | WhatsApp | Medium |

A channel must be added here before it can be used. If no channel is added, communications will not be sent, even when the event and template are configured correctly.

Channel priority does more than record importance. It also acts as a delivery filter:a channel only sends messages at or above the priority assigned to it. For example, setting SMS to **Critical** means SMS is used for critical messages only, and lower-priority messages are not sent over SMS even when the template includes the SMS channel. This is commonly used to control cost on high-volume channels. 2. **Custom Values** * Access: **Project Settings** > **Communications** > **Custom Values** * Description: Used to define and inject global constants into your application logic. Each value can be toggled to apply globally or be overridden per environment. Sensitive values can be marked with a secrecy shield. | Setting Name | Example Value | Description | | ------------------ | ------------------------------ | ------------------------------------ | | Tenant | `ComUnityTest` | Identifier for multi-tenant setup. | | SourceEmailAddress | `noreply@comunityplatform.com` | Default sender address. | | ReplyToAddress | `noreply@comunityplatform.com` | Email used for replies. | | ReplyToEntity | `MessageEvent` | Binds replies to a messaging entity. | | Namespace | `comcity` | Logical grouping for communications. | | LogLevel | `3` | Verbosity of system logging. | | FromAddress | `noreply@comunityplatform.com` | Alias used for outbound messages. | ## Environment-Specific Settings (v25.2 Update) From version 25.2, the ComUnity Toolkit provides an enhanced interface for managing communication settings independently for each environment. This allows you to define a specific communication provider and its unique credentials for each supported channel, ensuring a clear separation between your Development, QA, and Production configurations. **Configuration Steps** 1. Navigate to the **Communications** hub * Access the settings via **Project Settings** > **Communications**. * Select the tab for the environment you wish to configure: **Dev**, **QA**, or **Prod**. 2. Select a Communication Channel * Within the chosen environment, select the tab for the channel you want to set up (e.g., Email, SMS, Push, In-App, WhatsApp). 3. Choose a Service Provider * From the Service Provider dropdown, select the provider you wish to use for the chosen channel. * Select Default to inherit the platform's provider configuration for that channel. No credentials are required and the platform's own provider account is used. Select a named provider instead touse your own account; the channel will not send until its required fields (for example API URI and API key) are completed * Click the Save icon to apply your selection any dynamic fields\ required by the selected provider will then be loaded automatically. * For local development and testing, it’s recommended to use the Mock Service option. 4. Enter Provider Credentials * Once a provider is selected, the required configuration fields (e.g., API keys, usernames, base URIs) will be displayed. * You must obtain these credentials from the provider’s official administration portal and enter them securely into the fields provided. ### WhatsApp Client Configuration WhatsApp provider selection is configured per deployment environment in the Toolkit. To configure it: 1. Open your project. 2. Go to **Project Settings**. 3. Select a deployment environemnt for which these changes should apply. 4. Open **Communications**. 5. Select the **WhatsApp** tab.
6. Set the `WhatsAppClient` value independently for Dev, QA, and Prod. The Toolkit currently exposes the following values: | Value | Purpose | | -------------- | -------------------------------------------------------------------------------------------------------------- | | `Default` | Uses the default configured WhatsApp behaviour for the environment. | | `Twilio` | Routes WhatsApp delivery through the Twilio WhatsApp provider integration. | | `Mock Service` | Uses a mock provider, typically for non-production validation where live WhatsApp messages should not be sent. | The `WhatsAppClient` setting determines which WhatsApp client the environment uses. Provider-side onboarding, sender approval, WhatsApp Business setup, templates, and compliance requirements must still be completed with the selected provider. ## **Service Provider Requirements & Setup Guides** To integrate external services, you must have an active account with the provider and obtain the necessary credentials. ## Microsoft 365 Follow these steps to register an application in Azure and configure it with the necessary credentials and permissions. **1. Register the Application** 1. Navigate to the **Azure Portal** → **Azure Active Directory** → **App registrations**. 2. Click + New registration and create a new application (e.g., ComUnityEmailClient). **2. Record Credentials & Secrets** 1. From the application's Overview page, copy the following IDs: * Application (client) ID → Use this for the `O365Client` field. * Directory (tenant) ID → Use this for the `O365Tenant` field. 2. Go to the Certificates & secrets tab. 3. Click + New client secret. After creating it, copy the secret's Value. * Use this value for the `O365ClientSecret` field. {% hint style="warning" %} The client secret value is only displayed once upon creation. Ensure you copy and store it in a secure location immediately. {% endhint %} **3. Set API Permissions** 1. Go to the API Permissions tab. 2. Click + Add a permission, select Microsoft Graph, and choose Delegated permissions. 3. Add the following permissions: * `Mail.Send` * `User.Read` * `offline_access` 4. After adding the permissions, ensure you Grant admin consent for your directory. References: [Learn Microsoft](https://learn.microsoft.com/en-us/exchange/mail-flow-best-practices/how-to-set-up-a-multifunction-device-or-application-to-send-email-using-microsoft-365-or-office-365) ### Twilio (SMS & WhatsApp) 1. Login to your [Twilio Console](https://www.twilio.com/console). 2. From the main account dashboard, copy your: * `Account SID` * `Auth Token` 3. For WhatsApp integration, you must also: * Configure approved Senders in your Twilio account. * Set the `TwilioWhatsAppUser`, `Password`, `From`, and `Callback` values within the Toolkit. References: [Twilio SMS Guide](https://www.twilio.com/en-us/guidelines/sms) | [Twilio WhatsApp Guide](https://www.twilio.com/docs/whatsapp/tutorial) ### SendGrid (Email) 1. Login to your [SendGrid Dashboard.](https://login.sendgrid.com/) 2. Navigate to Settings > API Keys. 3. Create an API Key with the necessary permissions and copy the generated key. Docs: [API Key Setup](https://www.google.com/search?q=%23) ### BulkSMS (SMS) #### Generating a BulkSMS API Token 1. Log in to the [BulkSMS Portal](https://www.bulksms.com/account/ui/index.html#/login). 2. Navigate to **Settings** > **Advanced Settings** > **API Tokens.** 3. Click **Create Token**. 4. Enter a descriptive name for the token (e.g., ComUnityIntegration). 5. Immediately copy the Token ID and Token Secret. {% hint style="warning" %} For security reasons, the Token Secret will only be displayed once. Please store these credentials in a secure location, like a password manager {% endhint %}
#### BulkSMS Toolkit Configuration When configuring the Bulk SMS toolkit, map your credentials as follows: * **BulkSMSUser**: Use the Token ID. * **BulkSMSPassword**: Use the Token Secret. {% hint style="success" %} **Try it out** \ Follow this tutorial to learn how to send SMS messages to real devices using the BulkSMS service in a [Bulk SMS Campaign](/learning.comunityplatform/26.x/toolkit-tutorials/bulk-sms-campaign.md#integrating-the-bulk-sms-service-final-step). {% endhint %} ## **CellSys** The CellSys integration is not self-service. Unlike providers such as BulkSMS or SendGrid, CellSys does not expose full setup documentation publicly. To integrate with engage their support team through their [website](https://cellsys.co.za/). Upon account registration and payment they will provide API credentials you can use the the platform. ## **Best Practices** * Secure Storage: Always store sensitive values securely and mark them with the secrecy shield in the Toolkit. * Limited Permissions: When creating API keys, grant only the minimum permissions necessary for the integration to function. * Regular Audits: Periodically review provider permissions and credentials to ensure ongoing compliance and security. * Use Mock Services: Use the built-in mock services for all local development and testing to avoid incurring costs or sending unintended communications. **For further assistance, please refer to the official provider documentation or contact your system administrator.**