Skip to main content
Version: 2.0.0

Settings

This page explains every WhatsApp setting and where to find it. Open settings in Craft CP:

WhatsApp -> Settings (whatsapp/settings).

Settings are split into five tabs: Connection, Defaults, Logs, Test, Guide. A separate Enable switch (in the page's details panel) turns the whole plugin on or off.

Enable​

  • Enable: master switch for the plugin. When off, MessagesService::send() returns false immediately and nothing is sent — automations, MCP tools, and manual send() calls are all silenced without needing to remove groups or event subscriptions.

Connection tab​

  • Provider Endpoint: the HTTP endpoint used to send WhatsApp group messages. Supports environment variables ($WHATSAPP_ENDPOINT-style).
  • API Token: Bearer token for your WhatsApp provider. Leave empty if your endpoint doesn't require auth.
  • Sender ID: the WhatsApp sender ID or phone number ID configured at your provider, sent as from in every payload.
  • Request Timeout: HTTP timeout in seconds for provider requests (minimum 1).

Defaults tab​

  • Default Group: messages sent without an explicit group target go here. Must reference an existing, valid group handle — validated on save.
  • Global Prefix: used when the selected group doesn't have its own prefix set.
  • Include Site Name / Include Environment / Include Timestamp: lightswitches that prepend contextual info to outgoing messages.
  • Timestamp Format: PHP date() format string, used only when Include Timestamp is on.
  • Max Exception Trace Length: caps how many characters of a stack trace are included when an event notification carries exception details.

Logs tab​

  • Log Successful Deliveries: stores successful delivery records in the WhatsApp logs. Turn off if you only care about failures and want to keep the log table smaller.
  • Log Skipped Events: stores records for automation events that were evaluated but not sent (for example, a draft save).
  • Log Entry Limit: maximum number of rows kept in the whatsapp_logs table (minimum 1); older entries are pruned once the limit is exceeded.

Logs themselves are reviewed on the separate Logs page (whatsapp/logs), not on this settings tab — this tab only controls what gets written and how much is retained. The Logs page has a Clear action to empty the table on demand.

Test tab​

  • Test Group: which group receives the test message. Must reference an existing, valid group handle — validated on save.
  • Test Message: the text sent when you use the test action (max 1000 characters). Defaults to This is a WhatsApp test message from Craft CMS.

Use this tab after configuring the Connection tab and at least one group, to confirm delivery works before turning on automations.

Guide tab​

A short in-CP walkthrough covering the same steps as Basic setup in the main plugin page: provision a provider endpoint, fill in the Connection tab, create groups, fill in each group's provider-specific group identifier, then test before enabling automations.

Groups​

Groups are managed on their own page, WhatsApp → Groups (whatsapp/groups), not on the Settings page. Each group has two tabs:

General tab​

  • Name: display name shown throughout the CP.
  • Handle: internal key used by code and by Default Group / Test Group settings (for example sales, support, warehouse). Required; lowercase letters, numbers, hyphens, and underscores only.
  • Group Identifier: the provider-specific WhatsApp group ID used as the to value when sending. Required; supports environment variables and must resolve to a non-empty value.
  • Group Prefix: optional group-specific prefix, used instead of the global prefix for messages sent to this group.
  • Enabled: lightswitch — a disabled group is skipped by automations and by sendEventNotification(), and can't be selected as a Default Group or Test Group.

Automation tab​

  • Event Triggers: checkboxes for every registered event type (built-in Craft events plus anything registered by other plugins), grouped by provider and category.
  • Message overrides: a per-event text template used instead of the event's default template when sending to this group.

Validation and save behavior​

  • Provider Endpoint, API Token, Sender ID, Default Group, Test Group, Global Prefix, Timestamp Format, and Test Message must be strings; Test Message is capped at 1000 characters.
  • Request Timeout, Max Exception Trace Length, and Log Entry Limit must be integers of at least 1.
  • Default Group and Test Group are validated against the current group list — saving fails if either points to a handle that doesn't exist or isn't enabled.
  • A group's Handle must be unique and match ^[a-z0-9\-_]+$; its Group Identifier must resolve to a non-empty value after environment-variable parsing; its Event Triggers selections must all be known, currently registered event handles.
  1. Set up Connection first (endpoint, token, sender ID) — nothing else works without it.
  2. Create at least one group in WhatsApp → Groups with the correct provider group ID.
  3. Set that group as Test Group in the Test tab and send a test message to confirm delivery end to end.
  4. Set a sensible Default Group so ad-hoc send() calls without an explicit group still land somewhere expected.
  5. Enable the automation events you actually want per group — start narrow (for example, just entry saved) rather than subscribing every group to everything.
  6. Review Log Entry Limit if you expect high message volume, so the logs table doesn't grow unbounded.

Troubleshooting​

Test message fails to send​

  1. Confirm Provider Endpoint is reachable from the Craft server and accepts the documented JSON payload.
  2. Confirm API Token matches what your provider expects, if required.
  3. Check WhatsApp → Logs — a failed attempt logs the HTTP status code and response body (or the exception message) for the specific failure.

An automation event never sends a message​

  1. Confirm the group is Enabled.
  2. Confirm the specific event is checked on that group's Automation tab.
  3. Confirm you're not saving a draft or a revision — those are skipped by design and, if Log Skipped Events is on, appear in the log as skipped.

Settings won't save — "Selected group does not exist or is not enabled"​

Default Group or Test Group points to a handle that was deleted or disabled. Pick a currently enabled group, or re-enable the one you intended to use.