Documentation Communication channels WhatsApp

Channels integration

WhatsApp

WhatsApp integration overview
  • CategoryChannels
  • AuthOAuth

Walk through the Add WhatsApp wizard from account-type picker to the Meta signup popup.

Overview

Your Business number on WhatsApp, answered 24/7 by the same AI you have on every other channel. The Add WhatsApp wizard walks you through picking your current account type (Personal, Business App, or Business API), choosing a connection mode (Coexistence to keep the WhatsApp Business App alongside MessageMind, or Migrate to move the number across), signing in to Facebook, and verifying the number. You then add a payment method on Facebook Business and the AI is live.

What MessageMind can do with it

  • Receive and reply to WhatsApp conversations on your Business number through Meta's WhatsApp Business Platform (Cloud API).
  • Keep one contact per customer across WhatsApp, Instagram, Messenger, SMS and email, so the AI resumes threads instead of starting over.
  • Pick Coexistence Mode (recommended) to keep the WhatsApp Business App on your phone AND run MessageMind on the same number, or Migrate to move the number fully onto MessageMind.
  • Broadcast approved Marketing, Utility and Authentication template messages (the WhatsApp Business App does not expose this; the API does).
  • Add multiple WhatsApp Business accounts and numbers to one MessageMind tenant, each with its own disconnect scope.

Requirements

  • A MessageMind account with permission to connect the WhatsApp channel.
  • A Meta Business Manager (MBM). You can create one in Meta's popup if you do not have one yet; make sure the business details and website on the MBM are valid.
  • A phone number that can receive SMS or a voice call for OTP verification. If you do not have one yet, the wizard links out to Twilio to buy one.
  • If the number is already on the WhatsApp Business App and you pick Migrate, you will need to delete the account on the device during the wizard (Open WhatsApp, Settings, Account, Delete My Account, enter the number, confirm).
  • Your business adheres to Meta's WhatsApp Business Messaging Policy.
  • The number is not from a Meta-restricted country: Crimea (+7978), Cuba (+53), Iran (+98), North Korea (+850), Syria (+963).
  • After Meta's signup completes, you must log in to Facebook Business and add a valid payment method at business.facebook.com/billing_hub/accounts/details/ (otherwise sending will fail).

How to connect

  1. In MessageMind, open /channels/whatsapp and click Add WhatsApp (or go directly to /channels/whatsapp/add).
  2. Step 1: enter the phone number you want to connect. The wizard links out to Twilio if you need to buy a number first.
  3. Step 2: pick your current account type. Personal (number on the normal WhatsApp app), Business Account (number on the WhatsApp Business App) or Business API / BSP (number already on an API or a third-party BSP).
  4. Step 3 (Personal or Business App only): pick a Connection Mode. Coexistence Mode (recommended) keeps your WhatsApp Business App alongside MessageMind; Migrate Account removes the app and gives MessageMind full official control of the number.
  5. Step 4 (Migrate only): follow the on-screen Delete Account instructions on your phone so Meta releases the number (Open WhatsApp, Settings, Account, Delete My Account, enter the number, confirm).
  6. Step 5: click Continue with Facebook (or Continue with Facebook (Coexistence) on the Coexistence path). Select the Meta Business Account, create or select a WhatsApp Business profile, verify the number with the SMS or voice-call code and grant the requested permissions.
  7. After the Success screen, log in to Facebook Business and add a valid payment method at business.facebook.com/billing_hub/accounts/details/ so Meta can bill conversations.
  8. Back in MessageMind, send a test message from https://wa.me/{phoneNumber} and confirm it lands in the Inbox.

Authentication and permissions

Mechanism
Meta's embedded signup OAuth. MessageMind receives a system user access token for the WhatsApp Business account you selected and uses it to send and receive messages against the WhatsApp Business Platform (Cloud API).
Credentials
The system user access token Meta issues for the connected WhatsApp Business account, stored on your MessageMind tenant. Page-level and WABA-level identifiers are stored alongside the token; nothing is pasted or managed by you.

Available data and actions

Reads

  • Inbound WhatsApp messages sent to the connected Business number (text, media, interactive replies).
  • Message status callbacks from Meta (sent, delivered, read, failed).
  • The WhatsApp Business account profile (display name, about, business category) so the AI can greet in the right identity.

Writes

  • Outbound WhatsApp replies posted into the same thread as the inbound message, under the Business account's identity.
  • WhatsApp template messages for marketing, utility and authentication conversations, submitted to Meta for review and sent when approved.

AI agent use cases

  • Answer WhatsApp enquiries 24/7 with the same AI (and the same knowledge base) that answers on Instagram, Messenger, SMS, email and the website chat.
  • Follow up on Instagram or Lead Ads leads directly on WhatsApp, keeping one contact per customer across channels.
  • Broadcast template-based updates (orders, bookings, promos, two-factor auth) to opted-in customers.
  • Hand the chat to a human on your team when the AI detects it is out of scope, with the full WhatsApp history attached.

Configuration

  • Meta charges per conversation, not per message. A conversation is a 24-hour window between you and a customer; a new window opens when a new template of a different category is sent, or when the previous window ends and a fresh message starts a new one.
  • Conversation categories: Marketing (promos, invites, campaigns), Utility (order/booking/transaction confirmations) and Authentication (OTPs, logins). Meta prices each category separately per country, and prices are reviewed by Meta from time to time; always check Meta's live pricing page for the current numbers.
  • Customer service window: when a customer messages your Business number, a 24-hour window opens in which you can reply with free-form (non-template) messages. After 24 hours, only approved template messages are allowed.
  • Free tier: every month Meta grants 1,000 free service conversations per WhatsApp Business account, reset at the start of each calendar month.
  • Free entry-point conversations: when a customer taps a Click-to-WhatsApp Ad or a Facebook Page call-to-action button, a 72-hour conversation opens that is free regardless of category.

Example workflows

Coexistence Mode (keep the WhatsApp Business App AND run MessageMind)

  1. In the Add WhatsApp wizard, pick WhatsApp Business Account on the account-type step (your number is on the WhatsApp Business App today).
  2. On the Connection Mode step, pick Coexistence Mode. The card is marked Recommended but carries a Meta-side warning: it is not recommended for outreach or automated campaigns.
  3. On the Facebook step, click Continue with Facebook (Coexistence). Select the special Coexistence-enabled Meta app when prompted.
  4. Link your WhatsApp Business App number to the secondary routing profile and wait for the handshake to finish so dual-routing is live.
  5. Chats keep arriving in the WhatsApp Business App on your phone AND in MessageMind. Note the Coexistence pill in the UI; the WhatsApp Business profile is still edited only from the app, not from MessageMind.

Migrate an existing WhatsApp Business App number onto MessageMind

  1. In the wizard, pick WhatsApp Business Account on the account-type step, then Migrate Account on the Connection Mode step.
  2. The Delete Account step shows up: open WhatsApp on the device, open Settings, Account, Delete My Account, enter the phone number and confirm. Meta needs the number released before it can be re-registered.
  3. On the Facebook step, click Continue with Facebook. Select the Meta Business Account linked to your WhatsApp Business App, choose Connect your existing WhatsApp Business app and grant the permissions.
  4. On the Success screen, open business.facebook.com/billing_hub/accounts/details/ and add a valid payment method before the first send.
  5. Send a test message from https://wa.me/{phoneNumber} and confirm it lands in the Inbox.

Limitations

  • The WhatsApp Business Platform (Cloud API) requires Meta's embedded signup; you cannot connect through a pasted API key alone.
  • A payment method on Facebook Business billing is required before Meta will deliver outbound messages. Add it at business.facebook.com/billing_hub/accounts/details/ right after the Success screen.
  • Coexistence Mode carries Meta-side limitations and is explicitly not recommended for outreach or automated campaigns; Migrate Account is the path for broadcast-heavy use.
  • In Coexistence Mode the WhatsApp Business profile (display name, about, business category) can only be edited from the WhatsApp Business App on the phone, not from MessageMind.
  • You cannot delete a phone number from MessageMind. Meta's policy requires removing phone numbers from Facebook Business Suite under WhatsApp, Phone numbers.
  • Numbers from the Meta-restricted countries listed under Requirements are refused by Meta: Crimea (+7978), Cuba (+53), Iran (+98), North Korea (+850), Syria (+963).
  • Outside the 24-hour customer service window, only approved template messages can be sent to a customer. Template approval is handled by Meta and can take a few minutes to a few hours depending on category.
  • Conversation pricing is set by Meta per country and category and is reviewed from time to time; always check Meta's live pricing page rather than cached numbers.
  • Changing the WhatsApp Business display name re-opens Meta review and the name goes back to Pending until Meta re-approves it.

Troubleshooting

Meta couldn't add this number through the API.

Fall back to adding the number manually: in Facebook Business Suite open WhatsApp, Phone numbers, add the number there, then come back to /channels/whatsapp and the number will sync.

Registration with Meta failed. Check your two-step PIN or try again later.

The number has a two-step verification PIN set that Meta cannot bypass. Open the WhatsApp Business App on the device, remove or confirm the two-step PIN, then retry the Add WhatsApp wizard.

Authorization was canceled or closed.

You closed the Facebook popup or Meta cancelled the handshake. Re-open the wizard and click Continue with Facebook again; the browser must allow popups from the MessageMind dashboard.

Outbound messages are refused even though the number is connected.

A valid payment method has not been added yet on Facebook Business billing. Open business.facebook.com/billing_hub/accounts/details/ and add one; Meta will not deliver outbound messages without it.

The connection completes but no inbound messages arrive.

Confirm the correct phone number was selected on the Meta popup and the WhatsApp Business account is tied to it. Send a test message to https://wa.me/{phoneNumber} to force a webhook; if nothing arrives, open the Disconnect modal and reconnect from /channels/whatsapp/add.

A template message was rejected by Meta.

Meta reviews every template against its Business Messaging Policy and category rules. Edit the template to remove any promotional content from Utility or Authentication templates, then resubmit.

Outbound messages fail with a 'session window expired' error.

The 24-hour customer service window has closed since the customer's last inbound message. Send an approved template message (Marketing, Utility or Authentication) to reopen a conversation window.

The display name on the number stays Pending.

Meta reviews display names. The 'Pending' pill clears once Meta approves. If it is marked Declined, pick a name that matches your real business or brand (avoid generic, misleading or unofficial names) and resubmit from the number card.

Disconnect and reconnect

  • On /channels/whatsapp, click Disconnect this account on the connected number. The confirmation modal explains the two scopes.
  • Account scope (one Business account only): 'Only this WhatsApp Business account and its numbers will be disconnected from MessageMind. Its authorization will be revoked and its data removed from our system. Your other connected WhatsApp accounts stay untouched.'
  • Full scope (every connected WhatsApp account): 'all your data will be permanently deleted from MessageMind, including any associated messages and information stored in our system. Additionally, we will revoke the authorization you have granted us from WhatsApp.'
  • You cannot delete an individual phone number from MessageMind. To remove a number on Meta's side, use the Delete on Facebook link on the number card; it opens Facebook Business Suite under WhatsApp, Phone numbers where Meta allows the deletion.
  • To reconnect, run the Add WhatsApp wizard again at /channels/whatsapp/add. The Meta Business account and WhatsApp Business account are reused if they still exist on Meta's side.