Ctrlk

WhatsApp

WhatsApp

The Appmixer WhatsApp connector talks to the WhatsApp Business Cloud API hosted by Meta. This page has two distinct parts:

Part
Audience
What it covers

Part 1 — Configuring the connector

Appmixer administrator

One-time tenant setup: Meta App, WhatsApp product, Facebook Login for Business, Appmixer Backoffice, webhook endpoint, App Review

Part 2 — Using the connector

End customer / flow builder

What every customer must bring (WABA, phone, registration), how to connect their account, how Sender vs Recipient works, the 24-hour window, going Live

If you're setting WhatsApp up on a fresh Appmixer tenant for the first time — start with Part 1. If you're a customer building flows on an Appmixer where WhatsApp is already configured — skip to Part 2.

Part 1 — Configuring the WhatsApp connector

A one-time setup performed by an Appmixer administrator. End customers don't see any of these steps; once the Meta App is wired up they simply click "Connect WhatsApp" in the Designer.

1.0 Admin prerequisites

  • A Meta Business Account at business.facebook.com. A personal Facebook account can create one for free.

  • Admin / Backoffice access to your Appmixer tenant.

  • (Recommended for testing) a phone number you can use as a WhatsApp sender. Meta provides a free test phone number during App development.

1.1 Create the Meta App

  1. Open https://developers.facebook.com/ and choose My Apps → Create app.

  2. Use case: select Other, then on the next screen choose Business as the app type.

  3. Give the app a descriptive name (e.g. Appmixer – WhatsApp) and link it to your Business Account.

1.2 Add the WhatsApp product

  1. In the new app dashboard, scroll to Add products to your app.

  2. Click Set up on the WhatsApp card. This attaches a WhatsApp Business Account (WABA) to the app — Meta offers to create a brand-new test WABA if you don't already own one.

  3. After setup, you'll land on the API Setup page. Note the following — you'll need them for testing:

    • Phone number ID (the long numeric ID Appmixer's phoneNumberId input expects)

    • WhatsApp Business Account ID (WABA ID — used by the ListPhoneNumbers component, templates, etc.)

    • Temporary access token (24h lifetime; fine for smoke tests, not for production)

    • The pre-supplied test phone number Meta gives you

1.3 Add Facebook Login for Business

The end-user OAuth flow goes through Facebook Login for Business.

  1. In the app sidebar choose Add products → Facebook Login for Business → Set up.

  2. When prompted for Login variation, choose General — NOT "Conversions API for Business Messaging" (which is for ad-conversion tracking, not WhatsApp auth) and NOT "Instagram Graph API".

  3. Under Facebook Login for Business → Settings, set the Valid OAuth Redirect URIs to your tenant's WhatsApp callback URL:

    Replace YOUR_TENANT with the subdomain of your Appmixer tenant. Self-Managed customers can use any domain configured for the Appmixer API; append /auth/whatsapp/callback.

  4. Under App settings → Basic → App Domains, add your tenant domain(s) — at minimum the API host above. Without this Meta will reject the redirect at runtime.

1.3.1 Create a Login Configuration (Meta asset picker)

Plain OAuth shows the end customer a generic "Continue as X" consent screen — they grant access without explicitly choosing which WABA they share. Facebook Login for Business with a Login Configuration swaps this for a granular asset picker: customer explicitly selects which WhatsApp Business Accounts the connector can access. This is the same underlying flow Zapier, Make, and other competitors use, and Meta strongly recommends it for any 3rd-party WhatsApp integration. (Note: Zapier's UX additionally uses Meta's WhatsApp Embedded Signup via the JS SDK — a multi-step wizard with phone number setup inline. That requires Tech Provider designation and frontend SDK integration — not currently supported by Appmixer.)

  1. In the Meta App sidebar go to Facebook Login for Business → Configurations → Create new.

  2. Fill in the wizard:

    • Configuration name: anything descriptive, e.g. Appmixer WhatsApp OAuth

    • Login Variation: General

    • Permissions: whatsapp_business_messaging, whatsapp_business_management

    • Assets: check WhatsApp Business Accounts

  3. Save → Meta displays a Configuration ID (long numeric). Copy it — you'll paste it into Backoffice in the next section.

When the connector's OAuth URL contains config_id=<ConfigurationID>, Meta:

  • Shows the WABA / Business asset picker instead of a plain consent screen

  • Reads scopes from the Login Configuration (ignores scope query parameter)

  • Returns granular_scopes[] in the access token with WABA target_ids, used by the connector to auto-discover the customer's businessAccountId

If you skip this step the connector falls back to plain OAuth (still works, just worse UX).

1.4 Configure Appmixer Backoffice

  1. From the app dashboard, copy the App ID and App Secret (under App settings → Basic).

  2. Open your Appmixer Backoffice → Connector Configuration.

  3. Create (or edit) the entry with configuration ID appmixer:whatsapp and add:

    • clientId = Meta App ID

    • clientSecret = Meta App Secret — used both for the OAuth token exchange and for HMAC verification of incoming webhooks (X-Hub-Signature-256)

    • configId = Login Configuration ID from section 1.3.1. (Optional — without it the connector falls back to plain OAuth, no asset picker.)

    • verifyToken = any string you choose. You'll enter the same value into Meta App Dashboard when configuring webhook callback URL (section 1.6). Treat it as a shared secret.

  4. Save.

End customers on your tenant can now click Connect WhatsApp in the Designer and walk through the Meta asset picker.

Auto-discovery of WABA ID: During OAuth the connector automatically queries Meta's /debug_token endpoint and extracts the user's WhatsApp Business Account ID from granular_scopes. It's stored on the account's profile (profileInfo.businessAccountId) so end customers don't need to paste it into every component. The businessAccountId input fields on Send/Upload and trigger components are optional overrides — only fill them when the customer's account has access to multiple WABAs.

1.5 Required permissions (scopes)

The connector requests these scopes during OAuth:

Scope
Why

whatsapp_business_messaging

Send/receive messages, mark as read, upload media

whatsapp_business_management

Manage the WABA, phone numbers, templates, business profile

Both are part of Meta's standard WhatsApp product and do not require Advanced Access for development testing. They do require App Review before going Live for users outside your test list (see section 1.7).

1.6 Webhook setup for triggers (one-time admin step)

The Appmixer WhatsApp NewMessage and MessageStatusUpdated triggers receive events from Meta over HTTPS webhooks. Meta allows one webhook callback URL per Meta App, so Appmixer uses a connector-level plugin endpoint that all customers' WABAs share. The admin configures this once per tenant; per-customer WABA subscription happens automatically when a trigger flow starts.

One-time admin steps

  1. Get the plugin endpoint URL for your tenant:

    (Self-Managed customers: substitute your Appmixer API base URL for https://api.YOUR_TENANT.appmixer.cloud.)

  2. In the Meta App Dashboard go to WhatsApp → Configuration → Webhooks.

  3. Click Edit on Callback URL:

    • Callback URL = the plugin endpoint URL from step 1

    • Verify token = the verifyToken value you set in Backoffice → appmixer:whatsapp (section 1.4)

  4. Click Verify and save. Meta sends a GET to the endpoint with hub.mode=subscribe&hub.challenge=…&hub.verify_token=…. The plugin echoes back hub.challenge when the verify token matches.

  5. On the same page, find the messages field in the webhook fields table and click Subscribe. This single field covers:

    • Inbound messages (value.messages[]) — used by NewMessage trigger

    • Outbound status updates (value.statuses[]) — used by MessageStatusUpdated trigger

    • Reactions, button clicks, system messages, etc.

That's the entire admin setup. From here, every customer whose flow includes a WhatsApp trigger gets webhook events automatically (Part 2, section 2.5).

How the routing works

This means:

  • ✅ One Meta App serves unlimited customers on the same Appmixer tenant

  • ✅ Customer A's messages never leak to customer B's flows (eventName includes wabaId)

  • ✅ HMAC signature verification is centralized (uses the Meta App Secret stored in appmixer:whatsapp.clientSecret)

  • ❌ But: still only one Meta App per Appmixer tenant. Multiple tenants need a Meta App each.

1.7 App Review for production

Until your Meta App is reviewed and switched to Live mode, only verified test recipients and limited features are available. To onboard real customers you must submit for App Review:

  1. App settings → Basic — fill in app icon, category, privacy policy URL, terms of service URL.

  2. App Review → Permissions and Features — request advanced access for whatsapp_business_messaging and whatsapp_business_management.

  3. Business Verification — verify your business entity in Meta Business Manager. Requires a business document (commercial register entry, articles of incorporation, …) and may take several days.

  4. Tech Provider designation — required if you plan to onboard other businesses' WABAs via Embedded Signup. Appmixer hosted plans typically already operate under a Tech Provider Meta App; Self-Managed customers will need to apply separately.

Part 2 — Using the WhatsApp connector

This part is for the end customer / flow builder on an Appmixer tenant where the WhatsApp connector is already configured (Part 1 complete).

2.0 What you need on Meta's side

Before you can use the connector in your flows, you need an active WhatsApp Business presence on Meta. Appmixer does not provision this for you — each customer brings their own.

Must have

  1. Active Meta Business Account — at business.facebook.com, free. A personal Facebook account can create one.

  2. Active WhatsApp Business Account (WABA) — created under your Business Account, either:

    • Manually via Meta Business Suite → Settings → Business Settings → Accounts → WhatsApp Accounts → Add, OR

    • Automatically when you sign up via a Business Solution Provider (BSP) or template setup.

  3. At least one phone number added to the WABA — added via WhatsApp Manager, verified by Meta with an SMS / voice OTP code. During verification you also set a 6-digit two-step verification PIN for the number — write it down, you'll need it for Cloud API registration in section 2.2.

  4. Phone number registered for Cloud API — one-time activation. Easiest via the Ensure Sender Phone Number Registered component (section 2.2 below). Required before sending/receiving any message; without it Meta returns 133010 — Account not registered.

  5. Business Verification in Meta Business Manager — strictly required only for going Live (section 2.6), but recommended even in Development mode for better sender quality rating.

Hierarchy of Meta entities

Phone Number ID is auto-assigned by Meta when you add a phone number into a WABA. It's stable for the lifetime of the number on that WABA — but if you migrate the number to a different WABA, it gets a new Phone Number ID.

Where to find your IDs

What
Where in Meta UI

WABA ID (businessAccountId)

business.facebook.com → Settings → Business Settings → Accounts → WhatsApp Accounts → click WABA → ID at top

Phone Number ID

Same path → click the phone number in the Phone Numbers tab → ID in the details panel

PIN (for register)

Set during phone verification. Reset via Meta Business Manager → WhatsApp Manager → phone number → Two-step verification PIN

In practice you rarely need to look these up — Appmixer auto-discovers them after OAuth (see next section).

2.1 Connect your WhatsApp account in Appmixer

  1. In the Appmixer Designer, drop any WhatsApp component (e.g. Send Text Message) onto a flow.

  2. Click Connect new account → a Meta consent screen opens.

  3. Select the WABA you want to use. Meta explicitly asks which WhatsApp Business Account(s) to share — don't skip this, the connector relies on this selection to discover your WABA.

  4. Grant the requested scopes (whatsapp_business_messaging, whatsapp_business_management).

  5. Back in Appmixer, your account is connected. The WABA ID is auto-discovered and stored on the account — you don't need to paste it anywhere.

Already connected before? If you previously authorized Appmixer with the same Meta account, Meta will show a cached "Continue as X" screen instead of the asset picker. Click "Edit settings" to re-open the asset picker and review/change which WABA you share. Alternatively, revoke the prior authorization at facebook.com/settings?tab=applications and reconnect for a fresh flow.

What happens if you don't select a WABA

If you click Continue in the asset picker without selecting any WhatsApp Business Account (or your Meta account has no WABA at all), Appmixer deliberately fails the authentication with an error message asking you to retry. This is intentional — a connected account without a WABA can't send or receive anything, so we'd rather refuse than let you end up with a non-functional account that fails silently inside flows.

If you see this error:

  1. Open Meta Business Manager → Settings → Business Settings → Accounts → WhatsApp Accounts

  2. Add a WhatsApp Business Account if you don't have one (free)

  3. Add at least one phone number to it and verify it

  4. Reconnect in Appmixer — and make sure to select the WABA in the asset picker this time

Sender vs recipient terminology

Two distinct concepts often confused:

What it is
Where it lives
Identifier

Sender

YOUR business phone number — the number you message FROM

Inside your WABA

Phone Number ID (1044539225419737)

Recipient

An end user you message TO

Anywhere on WhatsApp

E.164 phone number (+420725657976)

Appmixer components named *PhoneNumber* (List/Get/Register/Deregister/EnsureRegistered/GetRegistrationStatus) always operate on YOUR sender numbers, never on recipients. Recipients need no registration — they're just E.164 phone numbers in the to field of Send components.

2.2 Register your sender phone number for Cloud API

One-time step per sender phone number. Without it the Cloud API returns 133010 — Account not registered.

Two components:

  • Ensure Sender Phone Number Registered (recommended for onboarding) — idempotent: checks status first, only calls register if not already registered. Returns wasAlreadyRegistered so you can branch on first-time setup vs resume.

  • Register Sender Phone Number (explicit) — always calls register. Useful when you want a hard failure on PIN mismatch.

Both take:

  • Phone Number ID — your sender number's ID. Pick from the dropdown (loaded from your WABA) or paste manually.

  • PIN — the 6-digit two-step verification PIN you set during phone verification (section 2.0).

    • For Meta test numbers it's typically 000000.

    • For owned numbers, the one you wrote down. Forgot? Reset via Meta Business Manager → WhatsApp Manager → phone number → Two-step verification PIN.

  • Data Localization Region — leave empty unless your WABA is in a Meta data-localization program (AU/BR/DE/IN/ID/GB).

Run the component once per phone number. registered: true (Ensure) or success: true (Register) confirms.

For diagnostics there's also Get Sender Registration Status — read-only, no side effects. Returns { registered, platformType, codeVerified, qualityRating, … }.

Alternative: register via curl

2.3 Verified recipients (Development mode only)

While the Appmixer admin's Meta App is in Development mode, Meta only delivers to phone numbers explicitly added as test recipients on the App.

If you can't deliver to a phone:

  1. Open Meta App Dashboard → WhatsApp → API Setup. (Requires Meta App access — coordinate with your Appmixer admin if you don't have it.)

  2. In the To dropdown, click Manage phone number list and add the recipient.

  3. WhatsApp will send a verification code via WhatsApp; enter it back in Meta Console.

This restriction goes away once the Meta App is Live (App Review approved — Part 1, section 1.7).

2.4 Understanding message delivery — the 24-hour customer service window

This explains 90 % of "my Appmixer flow succeeded but the message never arrived" tickets. Read it carefully.

You can send free-form text / image / video / audio / document / location messages only during a 24-hour customer service window, which opens when the end user sends a message to your WhatsApp Business number. Outside that window, the only message type Meta will actually deliver is a pre-approved template message.

What makes this insidious:

  • Meta does not reject out-of-window free-form sends with an HTTP error. The API returns HTTP 200 with a valid messageId — your Appmixer flow shows green — but the message is silently dropped on Meta's side.

  • The Meta App Dashboard's built-in "Send Message" button uses hello_world (a template) by default, so a manual test there appears to work even when your text-based Appmixer flow does not.

  • The same applies to Meta-supplied test phone numbers — verified recipients still need to write to the test number first to open the 24-hour window.

How to verify delivery in practice

  1. First contact must be a template. Use Send Template Message with templateName: hello_world, languageCode: en_US.

  2. Add a Message Status Updated trigger to the same flow. Meta sends status webhook events through it:

    • sent — accepted by Meta's servers

    • delivered — reached the recipient's device

    • read — recipient opened it

    • failed — not delivered; the payload includes a errors[] array with the reason code

    If you receive delivered but never read, the message reached the phone. If you never receive delivered within ~30 seconds, the message was dropped — typically because the 24-hour window was closed or the recipient isn't on the verified list.

Switching to free-form text

You only get to use Send Text Message after the user replies. Two ways:

  • Manual: open WhatsApp on the recipient device, send any message ("hi") to your test number. The 24-hour window now starts ticking; your Send Text Message flow will deliver until 24 hours after that message.

  • Programmatic: start every conversation with a template, then react to the New Message trigger when the user replies — only then send text.

2.5 Triggers — how inbound messages reach your flow

When you drop a New Message or Message Status Updated trigger into a flow and start the flow, the trigger automatically:

  1. Calls POST /{wabaId}/subscribed_apps on Meta — tells Meta to start delivering webhook events for your WABA to the Appmixer plugin endpoint.

  2. Registers a listener so the plugin can route incoming events to this specific trigger instance.

No webhook URL or token entry on your side — the Appmixer admin configured the global endpoint once (Part 1, section 1.6).

What each trigger sees

Trigger
Fires on
Payload

New Message

Inbound from a user to your sender number (text, media, location, reaction, interactive response, system event)

{ id, from, timestamp, type, text/image/…, phoneNumberId, wabaId }

Message Status Updated

Status change of an outbound message you previously sent

{ id, recipientId, status (sent|delivered|read|failed), timestamp, errors[], conversation, phoneNumberId, wabaId }

Optional WABA override

Both triggers expose a WhatsApp Business Account ID inspector field. Leave blank to use the default WABA discovered during OAuth. Fill in only when your account has access to multiple WABAs and you want the trigger to listen on a non-default one.

Important constraint

Only one Meta App per Appmixer tenant is configured. If your tenant has many customers, they all share the same plugin endpoint — Appmixer routes events by WABA so isolation works fine. But if you operate multiple Appmixer tenants you need a Meta App per tenant.

2.6 Going Live — what changes and what does not

Switching the Meta App from Development to Live mode (after App Review approval) lifts a few restrictions but does not change the fundamental WhatsApp Business messaging policy.

What changes when you go Live

Restriction
Development
Live

Recipient must be on the Verified Recipients list

Required

Removed — message anyone

Available templates

Only Meta-provided (e.g. hello_world)

All approved templates in your WABA

Daily messaging cap

250 business-initiated conversations / 24h

Quality-tier based: 1K → 10K → 100K → unlimited

Geographic reach

Limited to Meta-approved regions

Worldwide

What does NOT change

These constraints apply to every WhatsApp Business app, forever:

  1. The 24-hour customer service window. Free-form messages allowed only within 24h of the user's last message. Outside → templates only.

  2. Opt-in requirement for business-initiated messages. Sending unsolicited templates puts your number's quality rating in the red zone and risks WABA suspension.

  3. Templates require pre-approval. Submit via Meta Business Manager → WhatsApp → Message Templates, or programmatically via POST /{waba-id}/message_templates. Approval typically takes hours to a day.

  4. Silent-drop behaviour for out-of-window sends. HTTP 200 + messageId on accept, no delivery, no error. Detect via MessageStatusUpdated (you'll get sent but never delivered / failed).

Common production patterns

A) User-initiated conversation (chatbot, support inbox)

Free-form messages are service conversations — typically free or at the lowest rate.

B) Business-initiated outreach (notifications, reminders, marketing)

Templates are billed per conversation by category and country:

Category
Typical use
Cost (EU, indicative)

Service

Reply within 24h window

Free (or very low)

Authentication

OTPs, login codes

~$0.005–0.015 / conv

Utility

Order status, account updates

~$0.015–0.04 / conv

Marketing

Promotions, newsletters

~$0.04–0.10 / conv

Exact rates depend on country and change periodically — see Meta's conversation-based pricing.

Designing a customer's flow — checklist

When asked "how do I broadcast to all my users":

  1. ☐ Did the recipient explicitly opt in? (Required; no opt-in = ToS violation.)

  2. ☐ Is the message intent Marketing, Utility, Authentication, or Service? Each has its own template category and pricing tier.

  3. ☐ Is there an approved template for this message? If not, submit one and wait for approval.

  4. ☐ Does the flow gracefully handle the failed status webhook (number blocked, opted out, invalid)?

  5. ☐ Is the recipient potentially outside the 24-hour window? If unknown → use a template.

2.7 Test the connection

The quickest end-to-end smoke test from inside Appmixer:

  1. In the Designer, click Connect WhatsApp on any WhatsApp component → complete OAuth. WABA ID is auto-discovered onto your account.

  2. Add an Ensure Sender Phone Number Registered component, fill phoneNumberId and pin, run it once. (Idempotent — safe to re-run.)

  3. Drop a Send Template Message component (the safest first message — see section 2.4 above for why). Use:

    • Sender Phone Number — leave the WABA field blank, the dropdown auto-loads

    • to = a verified recipient in E.164 format (e.g. +420777123456)

    • templateName = hello_world (Meta's always-approved default template)

    • languageCode = en_US

  4. Run the flow. A message should arrive on the recipient's WhatsApp within seconds.

  5. Only after the recipient writes back from WhatsApp do you have a 24-hour window in which Send Text Message will actually deliver.

  6. (Optional) Add a New Message trigger to a separate flow, run it, then send a reply from your phone to the test number — the trigger should fire within seconds.

Troubleshooting

Symptom
Cause / Fix

Invalid Scopes: business_management during OAuth

The Meta App doesn't have business_management whitelisted. The connector only requires the two whatsapp_* scopes — make sure your published connector matches and re-run OAuth.

OAuth shows plain "Continue as X" instead of asset picker

configId is missing in Backoffice → appmixer:whatsapp, OR the Login Configuration was deleted in Meta App. Create one in Meta App → Facebook Login for Business → Configurations (see Part 1, section 1.3.1) and paste the ID into Backoffice.

Asset picker says "No WhatsApp Business Accounts available"

The customer's logged-in Facebook account doesn't own / co-manage any WABA. They must create one in Meta Business Manager first (see Part 2, section 2.0).

Auth fails with "No WhatsApp Business Account selected during authentication"

Customer reached the asset picker but clicked Continue without selecting a WABA, OR their Meta account has zero WABAs. Add a WABA in Meta Business Manager and reconnect; explicitly tick a WABA in the asset picker. See Part 2, section 2.1.

133010 — Account not registered

The phone number was not registered on the Cloud API. Run Ensure Sender Phone Number Registered once.

Security PIN Mismatch: Wrong PIN used (during register)

The PIN you supplied does not match the phone number's two-step verification PIN. Reset it: Meta Business Manager → WhatsApp Manager → phone number → Two-step verification PIN. Then re-run Register with the new PIN.

Flow succeeds with valid messageId but recipient never receives the message

You sent a free-form (text / media / location) message outside the 24-hour customer service window. Meta accepts the request and returns HTTP 200 but silently drops delivery. Fix: use Send Template Message with hello_world for the first contact, then wait for the user to reply before sending text. See section 2.4.

131030 — Recipient phone number not in allowed list

Meta App is in Development mode and the recipient isn't in the verified list. Add the recipient under WhatsApp → API Setup → Manage phone number list, or move to Live mode (Part 1, section 1.7).

Test works in Meta App Dashboard "Send Message" but not in Appmixer

The dashboard's built-in send button uses hello_world (a template) by default. Your Appmixer flow is probably sending text outside the 24-hour window — switch to Send Template Message for the first contact.

132000 — Number of parameters does not match (templates)

Template components array doesn't match the template's required parameters. Inspect the template structure in WhatsApp → Message Templates and adjust the JSON.

NewMessage trigger never fires (but MessageStatusUpdated works)

Most often: no inbound message has been sent to your business number yet. Outbound sends generate statuses[] but not messages[]. From a verified recipient phone, write a message TO your test number — then the trigger fires.

Both triggers silent

messages field is not subscribed in Meta App webhook configuration (Part 1, section 1.6), or the per-WABA subscription failed. Check Meta App Dashboard → WhatsApp → Configuration → Webhooks → messages shows "Subscribed". The customer's flow must be in Running state — start() calls POST /{wabaId}/subscribed_apps.

Webhook verify fails (Meta returns "Couldn't validate the callback URL")

The verify token in Meta App Dashboard must match verifyToken configured in Backoffice → appmixer:whatsapp (Part 1, section 1.4). Re-check both and re-save. The plugin endpoint must also be reachable (HTTPS, 200 on GET /plugins/appmixer/whatsapp/events handshake).

Token expires after ~60 days

Long-lived tokens are issued via fb_exchange_token and need periodic refresh. Appmixer refreshes them automatically; if a customer's account stops working, ask them to reconnect via the Designer.

References

PreviousSave FileNextXero

Last updated

Was this helpful?