WhatsApp — how to connect

Before you start

• A Meta Business Manager account with a WhatsApp Business Platform (Cloud API) app set up, including at least one registered/verified business phone number (not a personal WhatsApp/WhatsApp Business app number)
• A System User created in Meta Business Manager with admin access to the WhatsApp app, used to generate a permanent (non-expiring) access token — temporary user access tokens expire in hours and will break the connection
• The Phone Number ID for that WhatsApp number (found in the app's WhatsApp > API Setup page), not the phone number itself or the WhatsApp Business Account ID
• A default recipient phone number in E.164 format who has either messaged your business number within the last 24 hours, or is a number added to your test/allowed recipient list while the app is in development mode — WhatsApp will not deliver free-form text to anyone outside that window

Step by step

1. 1
   Create a Meta app

   In the Meta App Dashboard, click Create App, choose the "Connect with customers through WhatsApp" use case, and attach or create a Business Portfolio.

   Open
2. 2
   Add WhatsApp and copy the phone number ID

   In the app's WhatsApp > API Setup panel, copy the phone number ID shown for the number you'll send from (a free test number works during development) — this is the Phone number ID field.

   Open
3. 3
   Create a System User in Business Settings

   Go to Business Settings > Users > System Users, add a new system user, then Assign Assets to give it Full Control over the app and the WhatsApp Business Account.

   Open
4. 4
   Generate the permanent access token

   On that system user, click Generate New Token, select the app, and include the business_management, whatsapp_business_messaging, and whatsapp_business_management permissions — this token never expires and is the Permanent access token (System User) field.

   Open
5. 5
   Pick the default recipient number

   Choose the number you'll message and enter it in E.164 digits only, no plus sign (e.g. 38640123456), for the Default recipient field.

6. 6
   Paste all three values into the app

   Enter the access token, phone number ID, and recipient number into this app's WhatsApp connect form to finish setup.

Paste when you connect

• Permanent access token (System User)secret

  Business Settings → Users → System Users → Generate token with business_management + whatsapp_business_messaging + whatsapp_business_management. Permanent (non-expiring) — a temporary user token expires in hours.

• Phone number ID

  App → WhatsApp → API Setup → "Phone number ID". This is the numeric ID, NOT the phone number itself and NOT the WhatsApp Business Account ID.

• Default recipient (E.164, e.g. 38640123456)

  Digits only, no "+" or spaces. Free-form text only reaches someone who messaged you in the last 24h, or a number on your test allow-list.

Troubleshooting

Connecting the account fails immediately with a 401/190 error on the phone-number lookup

The pasted token is a short-lived User Access Token (expires in hours) rather than a permanent System User token, or the System User lacks admin/whatsapp_business_messaging permission on this app. Generate a new permanent token from the System User in Business Manager and verify it in Meta's Access Token Debugger before pasting it in.

Publish succeeds in testing but later fails in production with error 131047 (re-engagement / 24-hour window)

Free-form text messages can only be delivered if the recipient messaged your business number within the last 24 hours. Since this integration sends plain text only (no templates), have the recipient send any message first to reopen the window, or switch that recipient to a template-based flow outside this tool.

Connect succeeds but every publish attempt returns an error about the recipient or an invalid E.164 number

The recipient field must be digits only in E.164 format (country code + number, no '+', spaces, or leading zeros) — e.g. 38640123456. Also confirm the number is not on the developer allow-list restriction that applies while the app/WABA is still in development/unverified mode.

Connect fails with a message-limit or rate-limit style error even though the account was just created

New/unverified WhatsApp Business Accounts start in a restricted messaging tier (limited unique conversations per 24h) until Meta completes business verification; submit business verification in Meta Business Manager to raise the tier, or wait for the existing quota window to reset.