Skip to main content
Version: 1.0

15. Configuration

This chapter documents configuration key names and structure only — never real secret values. Secrets live in environment variables / server-side appsettings.Production.json (gitignored), never in the git-tracked appsettings.json. See docs/PLATFORM_SECRETS_RUNBOOK.md and docs/PLATFORM_LOCAL_DEVELOPMENT_SECRETS.md for the platform's general secrets handling process.

15.1 MailSettings (Email channel)​

"MailSettings": {
  "DisplayName": "SHUMOUL ERP",
  "EnableVerification": true,
  "From": "sender@example.com",
  "Mail": "sender@example.com",
  "Host": "smtp.example.com",
  "Password": "**FROM_ENVIRONMENT**",
  "Port": 587,
  "UserName": "sender@example.com"
}

15.2 PushSettings (Push / Firebase channel)​

"PushSettings": {
  "ProjectId": "",
  "CredentialJson": "**FROM_ENVIRONMENT**",
  "CredentialFilePath": "",
  "EnableSending": false
}

EnableSending defaults false — push sending is opt-in per environment; a fresh environment will not send real push notifications until this is explicitly set true with valid Firebase credentials configured (either CredentialJson inline or CredentialFilePath to a service-account JSON file).

15.3 WhatsAppCloudApi (WhatsApp channel)​

"WhatsAppCloudApi": {
  "VerifyToken": "**TENANT_SPECIFIC**",
  "AppSecret": "**FROM_ENVIRONMENT**",
  "SignatureValidationEnabled": true,
  "LogRawPayload": false,
  "AccessToken": "**FROM_ENVIRONMENT**",
  "PhoneNumberId": "",
  "BusinessAccountId": "",
  "GraphApiVersion": "v25.0",
  "BaseUrl": "https://graph.facebook.com"
}

SignatureValidationEnabled should never be set false in production — it disables HMAC-SHA256 verification of inbound Meta webhooks, which is the only authentication the webhook endpoint has (see §9.11). LogRawPayload should stay false outside of active debugging, since WhatsApp payloads can contain customer PII.

15.4 SaaSNotifications (cross-cutting toggles, SaaSNotificationSettings)​

"SaaSNotifications": {
  "EnableEmail": true,
  "EnableSms": true,
  "EnableWhatsApp": true,
  "EnableWhatsAppActivationForFreeSubscriptions": true,
  "WhatsAppTenantActivationTemplateNameAr": "welcome_activation_ar",
  "WhatsAppTenantActivationTemplateNameEn": "welcome_activation_en",
  "WhatsAppTenantActivationDefaultLanguageCode": "ar",
  "EnableWhatsAppOtp": true,
  "WhatsAppTenantOtpTemplateNameAr": "otp_verification_ar",
  "WhatsAppTenantOtpTemplateNameEn": "otp_verification_en",
  "WhatsAppTenantOtpLanguageDefault": "ar",
  "WhatsAppTenantOtpIncludeUrlButton": true,
  "EnableWhatsAppNotifications": true,
  "EnableWhatsAppTemplates": true
}

These are platform-level master switches, evaluated before any per-event NotificationEventConfiguration row — e.g. if EnableWhatsApp or EnableWhatsAppNotifications is false, WhatsApp dispatch is skipped regardless of what any individual event's configuration says (see the guard chain in §7.3).

15.5 SMS provider configuration​

No dedicated SMS settings section was found in the tracked Shumoul.Api\appsettings.json at the time of this documentation pass. SMS provider credentials (for the underlying FourJawalySmsProvider or equivalent) are environment-specific and configured outside the git-tracked configuration file — confirm the exact environment variable names with platform operations before configuring a new environment.

15.6 Environment variables & secrets​

See docs/PLATFORM_ENVIRONMENT_VARIABLES.md and docs/PLATFORM_SECRETS_RUNBOOK.md for the platform-wide list of environment variables and how secrets are injected per environment (local development vs. the GitHub Actions self-hosted runner vs. production). Anything marked **FROM_ENVIRONMENT** above is resolved from an environment variable at startup, never committed to git.

15.7 Firebase credential setup​

PushSettings.CredentialJson expects the full contents of a Firebase service-account JSON key (as a string), or CredentialFilePath can point to a file on disk containing the same. FirebasePushNotificationService and its underlying FirebasePushProvider guard on FirebaseApp.DefaultInstance == null before attempting any topic send — an unconfigured/misconfigured Firebase credential fails safe (returns false, logs a warning) rather than throwing.

15.8 SMTP setup​

MailSettings.Host/Port/UserName/Password configure the SMTP transport used by IMailService (consumed by EmailNotificationService/EmailChannelProvider). Port 587 implies STARTTLS; confirm your SMTP provider's required security mode matches the mail library's configuration before changing ports.

15.9 WhatsApp Cloud API setup​

Obtain AccessToken, PhoneNumberId, and BusinessAccountId from the Meta Business/WhatsApp Cloud API console. VerifyToken is the shared secret Meta echoes back during webhook subscription verification — it must match what is registered in the Meta app's webhook configuration. GraphApiVersion should track Meta's currently supported Graph API version; bumping it is a config-only change (no code change required) as long as the request/response shape used by Shumoul.Saas.WhatsAppIntegration remains compatible.