# System Settings

## Overview

System Settings (Admin → Settings) is where the platform owner configures everything that isn't tied to a single workspace: the brand, the WhatsApp engine, signup behaviour, billing scope, SEO, the installable app, email, and integrations. Changes take effect immediately.

Secret values are encrypted. Sensitive credentials — the Meta App Secret, the webhook verify token, the Twilio Auth Token, Unofficial API tokens, and the Meta system-user and Ads tokens — are stored encrypted and never shown back to you in full.

The settings landing page shows a quick summary — how many settings are filled in, how many secrets are stored, what still “needs a test”, and when settings were last changed and by whom — followed by a card for each group. Each group has its own page:

Group | Where to find it | Covered in
--- | --- | ---
General & brand, signup, billing scope | Settings → General | General & Brand, Signup / Billing
WhatsApp engine & provider credentials | Settings → WhatsApp Message | WhatsApp Provider Configuration
Email (SMTP) | Settings → Mail | Email (SMTP)
Wallet rules | Settings → Wallet Rules | Wallet, Checkout & Integrations
SEO | Settings → SEO | SEO
Installable app | Settings → PWA | Installable App
Integrations (Shopify, WooCommerce, catalog) | Settings → Integration | Wallet, Checkout & Integrations
Privacy & analytics | Settings → Privacy | Wallet, Checkout & Integrations

## General & Brand

The General page (Settings → General) covers the platform's identity and default behaviour.

Field | Default / limit | Purpose
--- | --- | ---
App name | Required, up to 80 characters | The platform name shown throughout the app and emails.
App URL | Must be a valid web address | The main web address of your platform.
Support email, contact number, from email | — | Core contact and sender details.
Default timezone / language / currency | — | Platform-wide defaults applied to new workspaces. The language and currency pickers list your active Languages and Currencies.
Address, map URL | — | Optional company address and embedded map for public pages.
Preloader | On | Show the loading animation on page load.
Maintenance mode | Off | Take the platform offline for everyone except admins.
Public registration | On | Allow new accounts to sign themselves up.
Auto-verify email | Off | When on, new accounts are treated as verified at signup and skip the verify-email screen. Useful when email isn't set up, or for invite-only setups where you vet people yourself.
Platform branding footer | Up to 60 characters | The small footer line added to messages from workspaces whose plan doesn't include “remove branding”. Saving this updates every workspace right away.

### Brand assets

WaDesk uses a single favicon shared across all themes, plus one logo per theme so each look can carry its own version. The theme slots are:

Theme | Note
--- | ---
Paper (default) | Light, off-white — the default look.
Bright white | Higher-contrast white background.
Dark (beta) | Upload a light / inverted version of your logo here.
Doodle (fancy) | Pastel mint background.

The favicon accepts PNG, ICO, JPG, SVG, or WebP (up to 512 KB); logos accept PNG, JPG, SVG, or WebP (up to 1 MB).

> Tip. For the Dark theme, upload a light or inverted version of your logo so it stays legible against the dark background.

## Default Signup Plan, Trial & Billing Scope

Three settings on the General page govern what happens the moment a new owner finishes signing up:

Field | Default | What it does
--- | --- | ---
Default signup plan | (empty) | The plan a new workspace starts on. The picker lists your active plans and flags which are free. Leave empty to fall back to the first active free plan.
Registration trial days | 14 | When the chosen signup plan is a free plan, the new workspace gets a trial of this many days. Range 0–365.
Billing plan scope | Per workspace | How a paid plan applies across an owner's workspaces (see below).

- Per workspace — each workspace is billed separately on its own plan.
- Per account — the owner's paid plan unlocks all of their workspaces.

> Caution. The default signup plan must be a real plan, so create the plan first and then select it here. Changing the billing scope affects how every owner's plan benefits are worked out, so review your plans before switching it on a live platform.

## WhatsApp Provider Configuration

The WhatsApp Message page (Settings → WhatsApp Message) is the most important integration page. You pick exactly one messaging engine — it is used across the whole platform; individual workspaces don't get a choice. Clicking an engine card reveals that engine's credential fields.

Engine | Credentials needed
--- | ---
Unofficial API / WhatsApp API | The Unofficial API server URL.
Business API (Meta) | Meta App ID, App Secret, webhook verify token, Config ID.
Twilio | Account SID, Auth Token, WhatsApp From number.

> Switching engines mid-traffic drops messages already queued for sending. Pause campaigns first, then change the engine.

### Business API (Meta) fields

Field | Notes
--- | ---
Meta App ID | From developers.facebook.com → your app → Basic settings. Used for one-click sign-in.
App Secret | Stored encrypted. Only changed when you actually type a value — re-saving with the field blank keeps the stored secret. The form shows a “stored, leave blank to keep” placeholder once set. Re-paste only to rotate it. Also used to verify that incoming Meta messages are genuine.
Webhook verify token | This is the value you paste into Meta's Callback URL “Verify token” field. Meta sends it back when you connect; WaDesk only accepts the connection if it matches. Stored encrypted. Any random string works — it just has to match on both sides.
Webhook URL (read-only) | The page displays `https://YOUR-DOMAIN/webhooks/whatsapp/inbound` with a copy button. Paste it in App dashboard → WhatsApp → Configuration → Callback URL and subscribe to the `messages` and `message_status` fields.
Sign-in Config ID | Optional. From Meta Business Suite → Login Configurations. Fill it to enable the one-click “Sign in with Meta” connect flow; leave blank to have workspaces paste their token manually. (Requires the Tech Provider role on the Meta app.)
OAuth redirect URI (read-only) | Shown as `https://YOUR-DOMAIN/connect/wa-store/waba`. Paste in App dashboard → Facebook Login → Valid OAuth redirect URIs.

> Per-workspace credentials. Each workspace connects its own phone number and access token while adding a connected number (Devices → Add device). You, the admin, only configure the platform-level Meta App credentials here.

#### Advanced Business API controls (shown only when Business API is active)

Field | Default | Notes
--- | --- | ---
Multi-workspace sending | Off | Sends every message through each workspace's own connected Meta account instead of a single platform-wide token. Required when serving many merchants in production.
Graph API version | `v23.0` | The Meta API version used for sending. Must look like `v23.0`.
New template submission / sync | Off | When on, new message templates are submitted to Meta when you save them, and their approval status updates automatically.
Template check interval (min) | 30 | How often WaDesk re-checks templates that are still pending after an hour. Range 5–240.
Strict template checker | On | When on, ban-prevention warnings (risky trigger phrases, over-long bodies) block submission instead of just warning you.

### Unofficial API field

Field | Notes
--- | ---
Server URL | Must be a valid web address (e.g. `http://localhost:8888`). The address where your Unofficial API server runs; it must be able to reach the WaDesk servers. Incoming messages and status updates are handled automatically.

### Twilio fields

Field | Notes
--- | ---
Account SID | From the Twilio Console dashboard.
Auth Token | Stored encrypted. Only changed when you type a value (“stored, leave blank to keep” once set). Also used to verify that incoming Twilio messages are genuine.
WhatsApp sender | The approved sender or sandbox number, including the country code (for example `+14155238886`).
Status callback URL (read-only) | Shown as `https://YOUR-DOMAIN/webhooks/whatsapp/inbound`. Paste in your Twilio Messaging Service → Integration tab.

### Sending speed & batching

The bottom of the page controls how fast messages go out, to help you stay under WhatsApp's limits.

Field | Default | Range
--- | --- | ---
Gap between messages (seconds) | 3 | 1–600
Batch size (recipients per batch) | 50 | 1–10000
Gap between batches (minutes) | 5 | 1–1440
Enable batches | Off | On / off

> Pacing tip. Lower the gap between messages only after running smoothly for a day — Meta throttles senders that move too fast. 3 seconds is the safe default. See the three engines overview for how each engine differs, and the Webhooks page for incoming vs outgoing messages.

## Email (SMTP)

The Mail page (Settings → Mail) sets up outgoing email. Every field starts from whatever your installation was set up with, so a fresh install isn't blank. Saving takes effect immediately — the very next email uses the new settings.

Field | Notes / default
--- | ---
Mailer | SMTP / sendmail / log / array / Mailgun / SES / Postmark / Resend
Host | Up to 200 characters
Port | 1–65535 (default 587)
Username | Up to 200 characters
Password | Stored encrypted. Shown as a “(set)” placeholder — never the real value. Leave blank to keep the saved password.
Encryption | TLS / SSL / STARTTLS / none
From name | Up to 120 characters (defaults to your app name)
From address | A valid email address

> Send a test. The page has a Send test button: enter an address and WaDesk sends a one-line test email using the saved settings, then shows success or the exact error. A successful test is recorded in the audit log and clears the “needs test” flag on the settings page.

## SEO

The SEO page (Settings → SEO) sets how your platform appears in search results and when shared on social media, with a live preview that uses your brand name. Fields include the page title, description, and keywords; a robots directive (default `index, follow`); a canonical URL and author; the social-share card details (title, description, image, type, URL) used by Facebook and Twitter; and search-engine verification codes for Google and Bing. A fresh install ships sensible defaults so the preview is never empty.

## Installable App (PWA)

The PWA page (Settings → PWA) lets visitors install your platform like an app on their phone or desktop, and controls how that installed app looks.

Field | Default
--- | ---
PWA enabled / install prompt / offline enabled | Off / On / On
App name, short name, description | Falls back to your brand name
Start URL, scope | `/`
Display | standalone (or fullscreen, minimal-ui, browser)
Orientation | portrait
Theme color, background color | `#075E54`, `#FBFAF6`
Icons (192, 512) and splash | URLs to your icon assets

> Tip. Provide both the 192×192 and 512×512 icons — browsers use the small one for the home-screen tile and the large one for the splash screen. Theme and background colors must be valid hex values.

## Wallet, Checkout & Integrations

Beyond the groups above, System Settings also covers:

- Wallet rules (Settings → Wallet Rules) — how many credits a new signup gets from a referral, how many credits each outgoing message costs, and how many credits a customer gets per unit of currency when they top up.
- Checkout settings — how the plan checkout behaves, in its own area (Admin → Checkout Settings).
- Integrations — the integration hub, plus Shopify (on/off, app keys, permissions, redirect URL) and WooCommerce connection settings, and the product catalog (with its own test button).
- Privacy & Analytics — the cookie banner, GDPR / CCPA and accessibility options, and analytics tracking IDs (Google Analytics, Google Tag Manager, Meta Pixel, Microsoft Clarity, Plausible, PostHog, and more).

All your settings can be exported to a file, and a “needs test” indicator flags any saved integration — email, catalog, or Shopify — that hasn't yet passed a successful test.

> Caution. Provider tokens, app secrets, the webhook verify token, and the email password are stored encrypted using your installation's security key. If that key is ever changed, the saved secrets can no longer be read — you would need to re-enter every secret afterwards.

## Related Pages

- AI & API Keys — the global AI provider credentials.
- Security & Audit Log — platform security policy and the record of settings changes.
- Announcements — the platform-wide marquee bar.
- Webhooks — outbound webhooks, and where the inbound platform webhook is wired.