Connect WhatsApp (WhatsApp Business API)

In the panel: Settings → WhatsApp Business API card. The guide inside the card has these same steps, with copy buttons, direct links to your own app's pages and automatic ticks for the steps the app checks by itself. At the top of the card a three-state strip “Keys valid → Webhook verified → First message received” shows where you are, and writes the reason in red when something is stuck.

There are two ways, and the card shows the right one by itself from the number: Meta's test number to try it in 10 minutes, or the business's real number for customers.

A) Meta's test number

1. Fill the “Meta app” box (the app's address + the main App secret from App settings → Basic). A new app: use case “Connect with customers through WhatsApp”; or the same app as Instagram.What you see: A green “Meta app” box.⚠️ Common mistake: Don't paste the Instagram app secret here; WhatsApp signs with the main App secret.
2. Use case “Connect with customers through WhatsApp” → Step 1 Try it out → Continue (accepts the terms). Paste the “Phone Number ID”, “WhatsApp Business Account ID” and the Generate token token into this card and “Save & test”.What you see: The test number +1 555…, two IDs and the Generate token button.⚠️ Common mistake: The Generate token token works for 24 hours only; don't forget the “permanent token” step.
3. On the same page “Recipient” → Manage phone number list → add your own mobile number and enter the 5-digit code that arrives on WhatsApp.What you see: The recipient list (up to 5 numbers).⚠️ Common mistake: A number that is not on this list exchanges no messages with the test number.
4. The app does this step itself (with the “Meta app” box): Callback URL, Verify token and the messages field. Only if it reports an error: Step 2 Production setup → “Configure Webhooks”: paste the rows below, “Verify and save”, then in the Webhook fields table the messages row → Subscribe.What you see: “Callback URL”, “Verify token”, “Verify and save” and the “Webhook fields” table.⚠️ Common mistake: Not subscribing messages: the webhook is verified but no message arrives.
5. On the Try it out page click Send message (to your own number), then reply to that message from your phone and click “I sent a test message”.What you see: The “hello_world” message from the test number in your phone's WhatsApp; then the bot's reply.⚠️ Common mistake: Messaging the test number first (“this number isn't on WhatsApp”): Meta sends first, then you reply.
6. Permanent token: business.facebook.com → Settings → System users → Add (Admin) → Assign assets: the app (Full control) and the WhatsApp account (Full control) → Generate token: Never, with whatsapp_business_messaging and whatsapp_business_management. Paste it over this card's token and “Save & test”.What you see: The Generate token window with the expiry choice (Never) and the permission list.⚠️ Common mistake: Not assigning the WhatsApp account to the system user: it gives “permission” errors.

B) The business's real number

1. Fill the “Meta app” box (the app's address + the main App secret from App settings → Basic). A new app: use case “Connect with customers through WhatsApp”; or the same app as Instagram.What you see: A green “Meta app” box.⚠️ Common mistake: Don't paste the Instagram app secret here; WhatsApp signs with the main App secret.
2. Prepare a number that is not active in the normal WhatsApp app: if it is, on that phone WhatsApp → Settings → Account → Delete account.What you see: A number with its country code that can receive a text or a call.⚠️ Common mistake: A number still in the WhatsApp app cannot be added; that app's chat history does not move over.
3. Step 2 Production setup → Register your WhatsApp phone number → Add phone number: the display name, the text/call code and a 6-digit PIN (two-step verification).What you see: The Add phone number window; then the “Display name” under review (Pending).⚠️ Common mistake: A display name that doesn't match the brand is rejected; write the PIN down (it is needed to register again).
4. Permanent token: business.facebook.com → Settings → System users → Add (Admin) → Assign assets: the app (Full control) and the WhatsApp account (Full control) → Generate token: Never, with whatsapp_business_messaging and whatsapp_business_management. Paste it over this card's token and “Save & test”.What you see: The Generate token window with the expiry choice (Never) and the permission list.⚠️ Common mistake: Not assigning the WhatsApp account to the system user: it gives “permission” errors.
5. On the app's WhatsApp page pick the real number under “From”, paste its new “Phone Number ID” over the old one in this card and “Save & test”.What you see: A different Phone Number ID for the real number.⚠️ Common mistake: Leaving the test number's ID in the card.
6. The app does this step itself (with the “Meta app” box): Callback URL, Verify token and the messages field. Only if it reports an error: Step 2 Production setup → “Configure Webhooks”: paste the rows below, “Verify and save”, then in the Webhook fields table the messages row → Subscribe.What you see: “Callback URL”, “Verify token”, “Verify and save” and the “Webhook fields” table.⚠️ Common mistake: Not subscribing messages: the webhook is verified but no message arrives.
7. Production setup → Add payment: only needed for templates (a message after 24 hours); answering a customer within 24 hours is free.What you see: The add-payment-method form in WhatsApp Manager.⚠️ Common mistake: Expecting to send a free message after 24 hours: WhatsApp's own rule allows only an approved template.
8. Send the real number a message from another phone and click “I sent a test message”.What you see: The bot's reply on WhatsApp and the chat on the Conversations page.⚠️ Common mistake: The bot cannot write first; the customer must start (then there are 24 hours to answer).
9. Later (optional): Step 3 Business verification for a higher message limit (from 250 to 2,000 customers a day) and more numbers.What you see: The business documents form in Meta's business settings.⚠️ Common mistake: Not needed to answer customers; only for bulk messages.

📲 Alerts on my own WhatsApp (optional)

If you use WhatsApp rather than Telegram, the app can tell your personal WhatsApp when a customer is waiting for the team (also after a flow's “Notify the team” step), with one reminder if nobody replies. It stays off until you set it up on the Tasks & follow-up page, in the box “Alerts on your personal WhatsApp”:

1. Connect the WhatsApp card above: the alert comes from the bot's number.
2. Enter your own WhatsApp number with the country code (not the bot's number). With Meta's test number, yours must be on its recipient list.
3. Click “Submit the alert template to Meta” and wait until the status shows “approved” (usually minutes to a day).
4. Click “Send a test alert”, then switch the alerts on. The switch refuses until Meta has approved the template.

Meta bills every alert at your country's Utility template rate. If an alert cannot be sent (the template rejected, your number not on the test list, Meta billing not active), the box shows it in red with Meta's reason. The bell in the panel always has every alert.