WhatsApp Notifications

AlpenFX WhatsApp Notifications (Magento 2)

Sends order-status notifications to customers over the WhatsApp Cloud API using approved, language-specific message templates. Magento-2 counterpart to the AlpenFX WhatsApp plugin for Shopware.

When an order's status changes, the module dispatches a WhatsApp template message to the customer's phone number (resolved from the order's shipping or billing address), normalised to E.164 and rendered in a template language derived from the order's store locale.

Features

• Order-status WhatsApp notifications via the official Cloud API (graph.facebook.com/v20.0/{phone_number_id}/messages).
• Automatic E.164 phone normalisation using the address country (handles leading 0, 00, existing +, and bare subscriber numbers).
• Per-store language resolution: maps the store locale onto a WhatsApp template language code, with a configurable fallback.
• Non-blocking and fault-tolerant: the send runs inside the order-save observer but is fully guarded — a bounded HTTP timeout and swallowed errors mean a WhatsApp failure can never abort the order save. Failures are logged with the context needed to diagnose them (target URL, template, resolved language, the substituted placeholders and the Graph API error body); the recipient number appears masked (4917******34), because a log file travels.
• Admin-only configuration; the access token is stored encrypted.

Requirements

• Magento Open Source / Adobe Commerce 2.4.7+ (PHP 8.2+).
• A WhatsApp Business account with the Cloud API enabled:
  • a permanent access token,
  • a phone-number ID (sender),
  • at least one approved message template for order-status updates.

Installation

composer require alpenfx/module-whatsapp
bin/magento module:enable AlpenFX_WhatsApp
bin/magento setup:upgrade
bin/magento setup:di:compile   # production mode only
bin/magento cache:flush

Configuration

Stores → Configuration → AlpenFX → WhatsApp Notifications (Section: alpenfx_whatsapp). All settings are scope-aware (default / website / store view).

| Group | Field | Config path | Notes | |-------------|-----------------------------|--------------------------------------------------|-------| | General | Enable WhatsApp Notifications | alpenfx_whatsapp/general/enabled | Master on/off switch. | | General | Default Template Language | alpenfx_whatsapp/general/default_language | WhatsApp language code used when a store locale cannot be mapped (e.g. en, en_US, de). | | Cloud API | Cloud API Base URL | alpenfx_whatsapp/api/base_url | Graph API base incl. version. Defaults to https://graph.facebook.com/v20.0; point it at a sandbox to exercise the integration without messaging real people. | | Cloud API | Access Token | alpenfx_whatsapp/api/access_token | Permanent Cloud API token. Stored encrypted, decrypted on read. | | Cloud API | Phone Number ID | alpenfx_whatsapp/api/phone_number_id | Cloud API sender phone-number id. | | Templates | Order Status Template Name | alpenfx_whatsapp/templates/order_status | Approved template name (default order_status_update). |

The module only sends when it is enabled and an access token and a phone-number ID are present (ModuleConfig::isConfigured()); otherwise every entry point is a silent no-op.

Message template

The order-status template receives two ordered body parameters:

1. {{1}} — order increment ID (e.g. 000000123)
2. {{2}} — the new order status (e.g. shipped)

Create and get approval for an equivalent template per language you intend to support (the resolved language code is sent in the API request). Language resolution maps the store locale onto a WhatsApp code via LanguageResolver (e.g. de_DE/de_AT/de_CH → de, en_US → en_US, pt_BR → pt_BR), falling back to the configured default language.

Phone number handling

Recipient numbers are taken from the order's shipping address (falling back to billing) and normalised to digits-only E.164 using the address country:

| Input | Country | Result | |------------------|---------|-----------------| | +49 170 1234567| any | 491701234567 | | 0049 170 … | any | 491701234567 | | 0170 1234567 | DE | 491701234567 | | 0660 1234567 | AT | 436601234567 | | 079 123 45 67 | CH | 41791234567 |

A national number whose country cannot be resolved to a dial code is skipped (no message is sent) rather than dispatched in an invalid format.

How it works

sales_order_save_after → OrderStatusNotificationObserver (acts only on a real status change) → NotificationService (builds the template message, resolves the language) → WhatsAppClient (POSTs to the Cloud API). The observer catches every \Throwable, so notification problems never break the order save.

Testing

vendor/bin/phpunit            # unit tests (PhoneNormalizer, LanguageResolver, …)
vendor/bin/phpstan analyse

License

Proprietary — © Felix Astner Software.