20. Configuration Reference
A certification-grade reorganization of §4 Configuration, split exactly into the categories required for certification: Platform Configuration, Tenant Configuration, Secrets, Environment Variables, Feature Flags, Default Values.
20.1 Platform Configuration
Bound from appsettings.json's WhatsAppCloudApi section into WhatsAppCloudApiOptions:
| Key | Type | Default |
|---|---|---|
WhatsAppCloudApi:VerifyToken | string | (empty) |
WhatsAppCloudApi:AppSecret | string | (empty) |
WhatsAppCloudApi:SignatureValidationEnabled | bool | true |
WhatsAppCloudApi:LogRawPayload | bool | false |
WhatsAppCloudApi:AccessToken | string | (empty) |
WhatsAppCloudApi:PhoneNumberId | string | (empty) |
WhatsAppCloudApi:BusinessAccountId | string | (empty) |
WhatsAppCloudApi:GraphApiVersion | string | v25.0 |
WhatsAppCloudApi:BaseUrl | string | https://graph.facebook.com |
20.2 Tenant Configuration
WhatsAppOperationalSettings — resolved per-tenant via IAppSettingService.GetAppSetting<T>(), never
hardcoded:
| Property | Default |
|---|---|
WhatsAppTenantActivationTemplateNameAr / ...En | welcome_activation_ar / welcome_activation_en |
WhatsAppTenantActivationDefaultLanguageCode | ar |
WhatsAppTenantOtpTemplateNameAr / ...En | otp_verification_ar / otp_verification_en |
WhatsAppTenantOtpLanguageDefault | ar |
PhoneNumberId / BusinessAccountId / AccessToken / AppSecret / VerifyToken | (empty) — the tenant's own Meta credentials, used only by the Communication module |
DefaultLanguage | ar |
DefaultTemplatePrefix | send_document |
TemplateLanguageStrategy | ByRecipientLanguage |
A related, platform-level (not tenant-scoped) settings class, SaaSNotificationSettings, holds the same
template-name defaults consumed by the OTP/Activation message services specifically — see
§4.3 for the distinction
between the two classes.
20.3 Secrets
Declared in Shumoul.Application/Secrets/SecretsManifest.cs, checked by SecretsHealthCheck at startup:
| Environment Variable | Required | Production-Required | Rotation Supported |
|---|---|---|---|
WhatsAppCloudApi__VerifyToken | No | Yes | Yes |
WhatsAppCloudApi__AppSecret | No | Yes | No |
WhatsAppCloudApi__AccessToken | No | Yes | Yes |
WhatsAppCloudApi__PhoneNumberId | No | Yes | No |
WhatsAppCloudApi__BusinessAccountId | No | Yes | No |
No secret value is ever reproduced in this documentation set.
20.4 Environment Variables
The double-underscore ASP.NET Core convention, matching §20.3 exactly:
WhatsAppCloudApi__VerifyToken
WhatsAppCloudApi__AppSecret
WhatsAppCloudApi__AccessToken
WhatsAppCloudApi__PhoneNumberId
WhatsAppCloudApi__BusinessAccountId
There is no environment-variable override for SignatureValidationEnabled, LogRawPayload,
GraphApiVersion, or BaseUrl in the SecretsManifest — those four are ordinary appsettings.json values,
not treated as secrets (they contain no credential material).
20.5 Feature Flags
Boolean switches controlling whether WhatsApp functionality activates at all, all on WhatsAppOperationalSettings
unless noted:
| Flag | Default | Effect when false |
|---|---|---|
EnableWhatsApp | true | Master switch — disables all tenant WhatsApp functionality |
EnableWhatsAppOtp | true | OTP delivery via WhatsApp is skipped (falls back to whatever other channel is configured) |
EnableWhatsAppNotifications | true | Notification Framework's WhatsApp channel dispatch is skipped |
EnableWhatsAppTemplates | true | Template-based sends are blocked at the guard-chain level |
EnableWhatsAppActivationForFreeSubscriptions | false | Free-tier tenants do not receive an activation WhatsApp message |
EnableSending | false | The tenant's own WhatsApp Business number (Communication module) cannot send — master switch independent of the platform number |
WebhookEnabled | false | Signals whether this tenant's own number has webhook delivery configured (informational; does not itself disable the platform's shared webhook endpoint) |
WhatsAppTenantOtpIncludeUrlButton | true | OTP template is sent without its optional URL button component |
WhatsAppCloudApi:SignatureValidationEnabled (platform) | true | Must never be set to false in production — disables webhook authenticity verification entirely |
20.6 Default Values — Quick Reference
| Setting | Default |
|---|---|
| Graph API version | v25.0 |
| Graph API base URL | https://graph.facebook.com |
| Signature validation | enabled |
| Raw payload logging | disabled |
| Default template language (tenant) | ar |
| Default template language (OTP) | ar |
| Default template language (Activation) | ar |
| Default document template prefix | send_document |
| Template language resolution strategy | ByRecipientLanguage |
| OTP URL button | included |
| Free-tier activation messages | disabled |
| Tenant's own WhatsApp sending | disabled until explicitly enabled |