WhatsApp

yui/craft-whatsapp sends WhatsApp messages to configured WhatsApp groups from the Craft control panel and from automation events. It gives store owners a way to get real-time WhatsApp alerts for content changes — new orders, entry edits, user sign-ups — without building a custom integration.

Use it when your team already watches a WhatsApp group for store activity and you want Craft to post there directly, instead of relying on email or checking the CP manually.

What it does

• Adds a WhatsApp section to the Craft control panel for managing connection settings, delivery groups, and a delivery log.
• Lets you define any number of Groups — each one a separate WhatsApp destination with its own provider group ID, message prefix, and enabled/disabled state.
• Sends built-in Craft automation events (entry, asset, category, and user saved/deleted) to any group subscribed to them, with an optional per-group, per-event message template override.
• Lets other YUI plugins register their own custom event types and dispatch notifications through the same delivery pipeline (see Developer / API reference).
• Keeps a searchable delivery log of successful, failed, and skipped sends for troubleshooting.
• Exposes MCP tools so an AI agent can send a plain message or a formatted order notification to a group.

How it works

The plugin does not talk to WhatsApp directly. It sends an HTTP POST to a provider endpoint you configure — your own middleware, a WhatsApp Business API gateway, or a third-party bridge service — with this JSON payload:

{
  "to": "GROUP_ID",
  "from": "SENDER_ID",
  "message": "Message body",
  "groupHandle": "ops"
}

If an API token is configured, it's sent as an Authorization: Bearer header. The plugin does not provision a WhatsApp Business account or a phone number for you — you need a working provider endpoint before setup makes sense.

Where admins work with this plugin

In Craft CP, open the WhatsApp section (whatsapp) from the primary navigation. It has three areas:

1. Groups (whatsapp/groups) — create, edit, and delete delivery groups, and manage per-group automation subscriptions.
2. Logs (whatsapp/logs) — a log of delivery attempts (success, failed, skipped), with a Clear action.
3. Settings (whatsapp/settings) — connection details, defaults, and logging behavior. See Settings.

A License page is also available under the plugin's CP navigation, consistent with other YUI plugins.

Basic setup

1. Open WhatsApp → Settings and fill in the Connection tab: provider endpoint, optional API token, and sender ID.
2. Open WhatsApp → Groups and create one record per WhatsApp group you want to send to, filling in the provider-specific group identifier for each.
3. Go back to Settings → Test, pick a test group, and send a test message to confirm the connection works end to end.
4. On each group's Automation tab, enable the built-in Craft events that group should receive.

Example: alerting on new entries

A common setup is a single "content" group that gets pinged whenever an editor publishes something:

1. Create a group with handle content-team and the WhatsApp group ID from your provider.
2. On that group's Automation tab, enable Entry saved.
3. Optionally override the default template (Entry "{{ title }}" was saved in {{ sectionName }}.) with your own wording under Message overrides.
4. From then on, every entry create/update (excluding drafts and revisions) posts to that WhatsApp group automatically — no code required.

Example: sending from a queue job or another plugin

Any PHP code in the project — a queue job, a controller, another plugin — can send a message directly:

use Yui\Whatsapp\Plugin as WhatsAppPlugin;

WhatsAppPlugin::$plugin->messages->sendToGroup(
    'ops',
    'Stock for SKU-1234 just dropped below the reorder threshold.'
);

This is the same pipeline used by the built-in automations and by the MCP tools, so it's logged and honors the group's enabled/disabled state.

Built-in automation events

Each group's Automation tab lets you subscribe to these Craft events:

• Entry saved / deleted
• Asset saved / deleted
• Category saved / deleted
• User saved / deleted

Draft and revision saves are skipped automatically — only real create/update/delete actions on published elements trigger a message. Each event supports a per-group message override with basic variables (for example {{ title }}, {{ sectionName }}, {{ filename }}, {{ volumeName }}, {{ username }}, {{ email }} depending on the element type).

Requirements

• Craft CMS 5 project.
• yui/craft-core version 1.
• A WhatsApp provider endpoint (your own bridge/middleware or a third-party gateway) that accepts the JSON payload described above.
• Composer access to https://packages.yui.sk/.

Installation

composer config repositories.yui composer https://packages.yui.sk/
composer require yui/craft-whatsapp
php craft plugin/install whatsapp
php craft migrate/all

Migrations create the whatsapp_groups and whatsapp_logs tables.

FAQ

Does this plugin connect to the official WhatsApp Business API for me? No. It sends an HTTP request to a provider endpoint you supply. You still need a WhatsApp Business API account, a third-party gateway, or your own bridge service that can actually deliver messages to WhatsApp.

Can I send to more than one WhatsApp group? Yes. Create one Group record per destination, each with its own provider group ID, prefix, and automation subscriptions.

Will draft saves or revisions trigger a notification? No — the plugin explicitly skips drafts and revisions, so only real publish/update/delete actions notify subscribed groups.

Can another plugin add its own WhatsApp events? Yes — see Developer / API reference.

Developer / API reference

MCP tools

When the yui/mcp plugin is installed, WhatsApp registers these tools so an AI agent can send messages directly:

Tool	Permission	Purpose
whatsapp_send	write	Send a plain text message to a WhatsApp group (handle). Omit group to use the configured default group.
whatsapp_send_order_notification	write	Send a formatted order notification with an order_number header and a details object rendered as key-value lines, to an optional group.

Notable services (Yui\Whatsapp\services)

• MessagesService — builds and sends the outbound payload. Key methods: send(), sendToGroup(), sendOrderNotification(), and sendEventNotification() for dispatching a registered event to every subscribed group.
• GroupsService — CRUD and lookup for group records, including getGroupByHandle().
• EventTypesService — the built-in event registry plus any events registered by other plugins.
• LogsService — writes and reads delivery log entries.

Registering a custom event type from another plugin

Other plugins can register their own WhatsApp event types and dispatch them at runtime through:

• Yui\Whatsapp\interfaces\WhatsAppEventProviderInterface — implement getWhatsAppEventTypes() and pass the provider to the registration event.
• Yui\Whatsapp\events\RegisterEventTypesEvent — fired as EventTypesService::EVENT_REGISTER_EVENT_TYPES; use addType() or addProvider() to add entries.
• Yui\Whatsapp\services\MessagesService::sendEventNotification() — dispatches a registered event handle to every group subscribed to it, applying each group's message override when present.

use craft\events\CancelableEvent;
use Yui\Whatsapp\events\RegisterEventTypesEvent;
use Yui\Whatsapp\services\EventTypesService;
use yii\base\Event;

Event::on(
    EventTypesService::class,
    EventTypesService::EVENT_REGISTER_EVENT_TYPES,
    function(RegisterEventTypesEvent $event) {
        $event->addType('orderShipped', [
            'provider' => 'shop',
            'providerLabel' => 'Shop',
            'group' => 'Orders',
            'label' => 'Order shipped',
            'description' => 'Sent when an order is marked as shipped.',
            'defaultTemplate' => 'Order {{ orderNumber }} has shipped.',
        ]);
    }
);

Once registered, the event handle (orderShipped in this example) appears in every group's Automation tab, and any plugin can trigger it with:

Yui\Whatsapp\Plugin::$plugin->messages->sendEventNotification('orderShipped', [
    'orderNumber' => $order->number,
]);

Routes

Control panel (whatsapp/*): whatsapp (redirects to groups), whatsapp/groups, whatsapp/groups/new, whatsapp/groups/<groupId>, whatsapp/groups/<groupId>/delete, whatsapp/logs, whatsapp/logs/clear, whatsapp/settings, whatsapp/license.

No storefront routes are registered by this plugin.