SplatDev.Umbraco.Plugins.WhatsApp 3.4.2

SplatDev.Umbraco.Plugins.WhatsApp

WhatsApp Business Cloud API integration for Umbraco — a backoffice inbox, template and free-form sending, and an inbound webhook receiver.

v3.0.0 is a rewrite. Versions 2.x shipped a wa.me deep-link button, not an API integration. There is no upgrade path for the old WhatsApp:* configuration keys — see Configuration.

Compatibility

On Umbraco 13 the plugin still sends messages and receives webhooks; only the UI is Umbraco 17-only.

Installation

dotnet add package SplatDev.Umbraco.Plugins.WhatsApp

The composer registers itself — no Program.cs change is required.

Configuration

Bound from the SplatDev:WhatsApp section.

{
  "SplatDev": {
    "WhatsApp": {
      "PhoneNumberId": "1311077628745755",
      "BusinessAccountId": "1777491496760147",
      "AccessToken": "",
      "WebhookVerifyToken": "",
      "AppSecret": "",
      "GraphApiVersion": "v21.0",
      "CustomerServiceWindowHours": 24
    }
  }
}

Never commit AccessToken or AppSecret. Use user-secrets locally and environment variables or Key Vault on the server:

dotnet user-secrets set "SplatDev:WhatsApp:AccessToken" "EAAG..."
# or, as environment variables:
export SplatDev__WhatsApp__AccessToken=EAAG...
export SplatDev__WhatsApp__AppSecret=...

Storage

Conversations live in a SQLite sidecar at umbraco/Data/whatsapp.db, created at startup. The Umbraco database is never touched. Override with ConnectionStrings:WhatsAppDb.

Webhook setup

The plugin exposes:

GET  /umbraco/whatsapp/webhook   # Meta's verification handshake
POST /umbraco/whatsapp/webhook   # messages + delivery statuses

In the Meta app → WhatsApp → Configuration → Webhook, set the callback URL to https://your-site/umbraco/whatsapp/webhook, the verify token to your WebhookVerifyToken, and subscribe to the messages field.

Running alongside an existing integration

A phone number belongs to the WABA, not to an app, and a WABA accepts multiple subscribed apps (POST /{waba-id}/subscribed_apps). Each app receives the same events at its own callback URL, and Meta resolves overrides per app (phone-number override → WABA override → app default).

So if another system already consumes a number's webhooks, do not repoint the app-level callback — you would silently cut that system off. There are two safe routes:

1. Per-number override (simplest). Overrides are resolved per phone number, so point only the number Umbraco owns at this plugin and leave the others alone:

   curl -X POST "https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/settings" \
     -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
     -d '{"webhooks":{"override_callback_uri":"https://your-site/umbraco/whatsapp/webhook",
          "verify_token":"YOUR_VERIFY_TOKEN"}}'
   

2. A second Meta app subscribed to the same WABA, with its own callback URL. Use this when the two integrations need separate tokens or permissions.

The 24-hour customer-service window

WhatsApp only allows free-form messages within 24 hours of the user's last inbound message. Outside that window, only an approved template will deliver.

The plugin models this directly: LastInboundUtc is set by inbound messages only — sending does not extend the window — and the inbox disables the reply box once it closes, pointing the operator at a template instead of letting them type a reply that would bounce with error 131047.

Backoffice

Adds a WhatsApp section with four views:

• Inbox — threads, transcript, live window countdown, reply box
• Send — approved template with variable filling and live preview, or free-form
• Templates — every template on the WABA with status and variable count
• Status — phone health, quality rating, and setup warnings for anything unconfigured

API

All endpoints require a backoffice user (AuthorizationPolicies.BackOfficeAccess); anonymous callers get 401.

Building the client

cd client
npm install --include=dev
npx vite build      # emits ../App_Plugins/WhatsApp/dist

Testing

dotnet test SplatDev.Umbraco.Plugins.WhatsApp.Tests

# live, read-only checks against the Graph API (excluded from CI)
export SplatDev__WhatsApp__AccessToken=...
export SplatDev__WhatsApp__PhoneNumberId=...
export SplatDev__WhatsApp__BusinessAccountId=...
dotnet test --filter "Category=Integration"

Troubleshooting

License

MIT © SplatDev