Integrations

WordPress & WooCommerce

The official WordPress plugins connect your site to WaCentra Connect API. WaCentra Connect API Auth adds WhatsApp OTP sign-in and optional two-factor authentication, while WaCentra Connect API for WooCommerce sends transactional order updates. Both add-ons run on top of the core WaCentra Connect API plugin.

Overview#

There are three plugins. Install the core plugin first; the add-ons cannot work without it.

PluginPurpose
WaCentra Connect API The core plugin. Stores your credentials, sends text and PDF document messages, verifies inbound webhooks, logs deliveries, honours STOP/START opt-outs and retries failed sends through Action Scheduler or WP-Cron. Required by both add-ons.
WaCentra Connect API Auth WhatsApp OTP authentication. Adds passwordless sign-in by phone number, optional two-factor authentication by role, phone capture on registration and profiles, and a front-end phone management shortcode.
WaCentra Connect API for WooCommerce Sends order status messages, captures checkout opt-in with consent and can attach a generated invoice PDF.

The API URL is fixed in the core plugin to https://wacentraconnectapi.com/api/v1 and can only be overridden with a constant or server environment variable. The add-ons do not call the API directly; all WhatsApp delivery goes through the core plugin.

Requirements#

  • WordPress 6.5 or newer and PHP 8.0 or newer.
  • A WaCentra Connect API account with an active link and a connected WhatsApp number.
  • A per-link API key generated on the link’s Webhook tab (API access). Account-wide API tokens cannot send messages through the plugins.
  • A public HTTPS site. Use HTTPS for login pages so codes and sessions are not sent in clear text.
  • For Auth: a phone number on each user who should sign in passwordlessly.
  • For order messages: WooCommerce installed and active, plus the WaCentra Connect API for WooCommerce add-on.
Create the link and its API key first. Link keys are bound to one link, can be restricted to IP ranges, expire after 90 days by default and are shown only once when generated.

Install the plugins#

  1. Upload the wacentraconnect folder to /wp-content/plugins/ and activate WaCentra Connect API.
  2. Open the WaCentra Connect API menu and enter the link Session ID and the per-link API key, then save. See Connect your link.
  3. For authentication, upload wacentraconnect-auth to /wp-content/plugins/ and activate WaCentra Connect API Auth.
  4. For order messages, install and activate WooCommerce, then upload wacentraconnect-woocommerce and activate WaCentra Connect API for WooCommerce.
  5. Configure the webhook before enabling sandbox mode, because sandbox links cannot change webhook settings.

The Session ID and key are encrypted before they are stored. The API URL, session ID, key, webhook URL and webhook secret can also be supplied through constants or environment variables.

Connect your link#

Copy the values from the link’s Credentials tab in WaCentra Connect API into the core plugin dashboard. All values are also available as environment variables or constants, which take precedence over saved settings. Both add-ons reuse the core connection.

SettingEnvironment variable / constantNotes
API URLWACENTRACONNECT_API_URLOptional. Fixed to https://wacentraconnectapi.com/api/v1 unless overridden.
Session IDWACENTRACONNECT_SESSION_IDThe link uuid used in every API path.
Link API keyWACENTRACONNECT_API_TOKENPer-link key, not an account-wide token.
Webhook URLWACENTRACONNECT_WEBHOOK_URLOptional when WaCentra Connect API should post to the WordPress REST route.
Webhook secretWACENTRACONNECT_WEBHOOK_SECRETUsed to verify the signature on every delivery.
Domain labelWACENTRACONNECT_CLIENT_DOMAINSent as X-Client-Domain. A label only; the API does not enforce it.

Other available constants

ConstantDefaultPurpose
WACENTRACONNECT_ALLOW_INSECURE_WEBHOOKfalseDevelopment only: allow an http:// webhook URL when testing locally.
WACENTRACONNECT_DEFAULT_COUNTRY_CODE254Country code applied when a number has no international prefix. Auth uses the same rule.
WACENTRACONNECT_OPT_OUT_KEYWORDSstop, unsubscribe, opt out, optoutInbound keywords that stop messages to a number.
WACENTRACONNECT_OPT_IN_KEYWORDSstart, unstopInbound keywords that resume messages.
WACENTRACONNECT_OPT_OUT_CONFIRMATIONtrueSet to false to disable STOP/START confirmations.
WACENTRACONNECT_LOG_RETENTION_DAYS300 keeps logs indefinitely.
WACENTRACONNECT_DEBUGfalseInclude API error details in logs.
WACENTRACONNECT_KEEP_DATA_ON_UNINSTALLfalseKeep logs and opt-outs when the plugin is deleted.

Use Check connection after saving to confirm the credentials work. The dashboard shows whether the link is in production or sandbox.

Authentication#

WaCentra Connect API Auth turns a WhatsApp number into a login factor. Codes are generated inside WordPress, hashed, stored as single-use transients and sent through the core plugin. The code itself is never stored in plain text or written to the message log.

  1. Install the core WaCentra Connect API plugin and confirm Check connection succeeds.
  2. Activate WaCentra Connect API Auth and open WaCentra Connect API → Auth.
  3. Choose a login mode and a login surface (see below).
  4. If you use dedicated pages, press Create auth pages and confirm both pages are selected.
  5. Add a WhatsApp phone number to each user who should sign in passwordlessly.
  6. Save the settings, then test in sandbox before enabling it for real users.
Requires the core plugin. Auth does not contact the WaCentra Connect API API directly. If the core plugin is deactivated, codes cannot be sent and the Auth menu warns that the dependency is missing.

Login modes#

Pick one mode on the Login tab of WaCentra Connect API → Auth:

ModeWhat users doNotes
Disabled Use the normal WordPress login only. No codes are sent and the WhatsApp login links are hidden.
Passwordless Enter a phone number, receive a WhatsApp code, then sign in. The user must already have a phone number on file. The request always shows the same generic message, so the form does not reveal whether an account exists.
Password + code (two-factor) Enter the password as usual, then confirm with a WhatsApp code. Applies only to the roles you select. The default role list is Administrator. Select at least one role or the module will warn you.

Users without a phone number can still sign in with their password and add a number later. Passwordless login cannot find an account by phone until a number is saved. With two-factor enabled, email fallback can send the code to the account email instead.

Login surfaces#

Choose where the phone and code forms appear:

Dedicated pages (shortcodes)

ShortcodePagePurpose
[wacentraconnect_login]Login pagePhone number and code entry for passwordless login.
[wacentraconnect_2fa]Verification pageCode entry after a password login when two-factor is enabled. Required in two-factor mode.
[wacentraconnect_phone]Any pageSigned-in users can add, update or remove their own WhatsApp number.

Use the built-in Create auth pages button on the Quick setup tab to create the pages with the right shortcodes and select them automatically. You can also create the pages manually and select them under Login.

WordPress login screen

Select WordPress login screen (wp-login.php) as the login surface. The phone/code form is then available at wp-login.php?cc_auth=1, and two-factor verification stays on wp-login.php. A Login with WhatsApp link is added to the normal login form.

If you use a full-page cache, exclude the login and verification pages. The plugin sends no-cache headers, but a page cache can still serve a stale form or reuse a verification link.

Phone capture#

Auth needs a normalized WhatsApp number for each user. Numbers are validated with the core phone rules, stored in E.164 format and can only be linked to one account.

  • Profile: add or edit the number under Contact Info → WhatsApp phone number on the user profile.
  • Registration: enable Registration on the Phone capture tab to add an optional WhatsApp phone field to WordPress and WooCommerce registration forms.
  • WooCommerce: enable WooCommerce billing phone to copy a billing phone to the profile when the account has no number yet.
  • Self-service: place [wacentraconnect_phone] on a page so signed-in users can manage their own number.

Numbers without an international prefix use WACENTRACONNECT_DEFAULT_COUNTRY_CODE (default 254). A number that is already linked to another account is rejected.

Code delivery & limits#

Codes are six digits, valid for 10 minutes by default and accepted once. The following settings are on the Code delivery tab:

SettingDefaultRangePurpose
Code lifetime600 seconds60–3600How long a code remains valid.
Maximum attempts51–20Wrong-code attempts before the code is discarded.
Resend cooldown60 seconds0–3600Minimum wait before another code can be requested for the same destination.
Codes per hour (phone or email)51–100Hourly cap per destination.
Codes per hour (per IP)201–100Hourly cap across all destinations from one address.

The message template supports {code} and {site_name}. Keep the site name and the expiry wording aligned with the lifetime you configure.

Email fallback

When enabled, two-factor sends the code to the account email if the user has no phone or WhatsApp delivery fails. Passwordless login does not fall back to email; it shows a generic failure and logs the error in WaCentra Connect API.

Emergency bypass

If administrators are locked out, add this to wp-config.php to skip two-factor verification:

define( 'WACENTRACONNECT_AUTH_DISABLE_2FA', true );

Remove the constant as soon as access is restored.

Scope and developer hooks

Auth protects interactive WordPress logins. It does not cover REST API application passwords or XML-RPC logins; disable those if two-factor is mandatory. Auth fires wacentraconnect_auth_logged_in, wacentraconnect_auth_2fa_verified, wacentraconnect_auth_phone_updated and wacentraconnect_auth_phone_removed, and provides the wacentraconnect_auth_login_redirect filter for the post-login destination.

Webhook setup#

Webhooks belong to the core plugin. They let WordPress react to inbound messages, delivery status changes and STOP/START keywords. Configure them before turning on sandbox mode, because sandbox links cannot change webhook settings. Authentication codes are sent outbound and do not require a webhook.

  1. Copy the webhook URL shown on the WaCentra Connect API core plugin dashboard.
  2. Open the link in WaCentra Connect API and add that URL as the webhook payload URL. It must be public HTTPS.
  3. Subscribe the link to messages.received at minimum.
  4. Paste the webhook signing secret into the plugin dashboard and save again.
Leave the webhook URL blank in the plugin to use the WordPress REST route. Every delivery is signed; the plugin rejects requests whose signature does not match the saved secret. See the events guide for the payload shape and signature rules.

Test and sandbox#

Test without messaging real users. On the WaCentra Connect API Developer page, enable sandbox for the link and add the numbers you want to use as sandbox recipients. The plugins link to that page directly.

  1. Enable sandbox mode for the link on the Developer page.
  2. Add your own number as an allowed sandbox recipient.
  3. Run Check connection in WaCentra Connect API and confirm the sandbox status.
  4. Test an auth code or a test message with an allowed number. WaCentra Connect API rejects any number that is not an allowed sandbox recipient.

Sandbox messages are watermarked and do not consume the live message allowance. Test messages are available only while the link is in sandbox mode. Read the full sandbox guide.

WooCommerce setup#

The WooCommerce add-on sends transactional order updates over WhatsApp. It supports classic and block checkout and is compatible with WooCommerce High-Performance Order Storage (HPOS). It also pairs with Auth: billing phones can feed passwordless login, and Auth can capture a phone during WooCommerce registration.

  1. Install and configure the core WaCentra Connect API plugin first.
  2. Install and activate WooCommerce.
  3. Upload the wacentraconnect-woocommerce folder to /wp-content/plugins/.
  4. Activate WaCentra Connect API for WooCommerce.
  5. Open WaCentra Connect API → WooCommerce and enable the order events you need.

The add-on depends on the core plugin. If the core plugin is deactivated, order messages stop until it is active again.

Order messages#

Each order event has its own enable toggle and message template. Supported events:

EventTypical use
Order receivedConfirm the order and set expectations.
ProcessingTell the customer the order is being prepared.
CompletedConfirm fulfilment or pickup.
CancelledNotify the customer that the order was cancelled.
RefundedConfirm the refund was issued.
FailedAsk the customer to retry payment.

Templates support order variables such as the order number, customer name, total and items. The admin screen includes a live template preview and sandbox-only test messages.

No duplicate sends

Each event is recorded in order meta, so re-saving an order does not resend the same message. A per-order delivery log shows status, errors, retries and allows a manual resend.

Pacing and retries

Order messages are queued through Action Scheduler about one second apart, keeping a burst of status changes within the API rate limit. If Action Scheduler is unavailable the plugin falls back to WP-Cron; a real cron job is recommended for reliable delivery.

These are transactional order updates, not marketing messages. Marketing and cart-recovery messages are not part of this version.

Checkout opt-in#

Both classic and block checkout show a WhatsApp number field and a separate consent checkbox. Entering a number without checking consent does not opt the customer in, and no order message is sent to that number.

The consent source, label and timestamp are stored on the order for audit. A phone number alone is never treated as consent. Keep the consent label clear about which order updates the customer will receive.

Invoice PDFs#

Enable PDF attachments and choose which events should include one. The plugin generates the invoice from the order and sends it as a WhatsApp document, using the message text as the caption.

  • PDF only, with a maximum size of 5 MB.
  • Generated at delivery time and deleted after the send.
  • Internal order notes are never included.
  • If the PDF cannot be generated or attached, the plain text message is sent instead.

Troubleshooting#

SymptomCause and fix
No code arrives during testing The link may be in sandbox mode. Only sandbox recipients receive messages. Add the number on the WaCentra Connect API Developer page, or switch the link out of sandbox when you are ready.
Passwordless login always says a code was sent That message is intentionally generic. If no code arrives, confirm the user has a phone number on file and that the core link is connected. Check WaCentra Connect API logs for delivery errors.
Two-factor code does not arrive Check the user’s phone number and WhatsApp delivery. With email fallback enabled, the code goes to the account email when the phone is missing. If you are locked out, use the emergency bypass constant.
Two-factor prompts for a phone number The user has no phone and email fallback is disabled. Add a phone or enable email fallback on the Code delivery tab.
Verification page error Two-factor requires a selected verification page containing [wacentraconnect_2fa] when using the dedicated-page surface. Run Create auth pages or select the page manually.
Phone already linked Each number can belong to one account only. Remove it from the other profile or use a different number.
401 from the API The link key expired or was revoked. Link keys expire after 90 days by default. Generate a new per-link key in WaCentra Connect API and save it in the core plugin.
403 from the API The key is not valid for this link, an account-wide API token was used, or the request came from an address outside the key’s IP ranges.
Webhooks never arrive The URL must be public HTTPS, the link must subscribe to messages.received, and the signing secret in the plugin must match the link. Confirm the site is reachable from the internet.
Cannot change webhook settings The link is in sandbox mode. Sandbox links cannot manage webhooks or keys; configure them first, then enable sandbox.
Order messages are duplicated Order messages are recorded in order meta and are not resent when an order is saved again. Check the per-order delivery log and any custom code that calls the API directly.
Order messages are delayed Action Scheduler processes the queue. If WP-Cron is handling it instead, configure a real server cron job for wp-cron.php.
PDF not attached Attachments must be PDF and no larger than 5 MB. If generation fails, the text message is still sent. The delivery log records the error.
Keep the API key and webhook secret on the server. Never commit them to source control or expose them in front-end code. Rotate the webhook secret on the link’s webhook page if it leaks.

© 2026 WaCentra Connect API. All rights reserved.