WhatsApp

Messages go out from your number, through your Meta account. Without the integration, the app sends nothing over WhatsApp: the screen may have the button, but the send is refused with the notice that WhatsApp is not configured in this app.

Before you start

• Plan: Builder. The plan is checked on every send: if the account leaves Builder, the app stops sending;
• A Meta for Developers account and, for production, a Meta business account with a phone number of its own for WhatsApp;
• Cost: Meta charges for messages according to its price list, on your account. On top of that, each message sent by the app consumes the platform's integration credits, and only when Meta accepts the send.

What the app does with the integration

• send a text message to a number;
• send a template message approved by Meta, in the template's language;
• receive messages and trigger automations when someone writes to the number. That is what the card's last two fields are for (see the end of this guide).

Numbers go in international format, with the country code: +5511999999999.

Step by step

Card fields: Phone Number ID, Access Token, Verify Token (webhook) and App Secret (webhook signature).

1. at developers.facebook.com, create an app of the Business type;
2. add the WhatsApp product to the app. Meta already provides a test number;
3. under WhatsApp → API Setup, copy the Phone number ID and the access token;
4. under Settings → Basic, reveal and copy the App Secret;
5. make up a Verify Token: any secret text, which you will use again in the Meta dashboard if you are going to receive messages;
6. in the app's editor, Integrations tab, Notifications category, open the WhatsApp card;
7. fill in the four fields and click Save and activate.

Test token and permanent token

The token shown under API Setup is temporary and expires in about 24 hours. It is good for the first test and nothing more. For the app in use, generate a permanent token with a system user, under Business settings → System users, giving it access to the app and to WhatsApp. Then open the card, paste the new token into its field and save. The other fields can stay blank: the saved value is kept.

Destination numbers in test mode

While the Meta app is in test mode, it only sends to numbers registered as allowed recipients in API Setup itself, and Meta limits that list to a few numbers. Register yours to test.

Message templates

The rule is Meta's, not the platform's: a business can only send free text to someone who wrote to the number in the last 24 hours. Outside that window, the first message has to be an approved template.

In practice, reminders and notifications the app sends on its own (an appointment reminder, an order confirmation) almost always need a template. The path:

1. in your business account's WhatsApp Manager, create the template, with the text and the variables;
2. submit it for approval and wait for Meta to approve it;
3. ask in the chat for the app to use that template, giving the template's exact name and the language. If no language is given, the app uses pt_BR.

How to know it worked

The WhatsApp card does not test the credential on save: Connected means the fields were saved, not that the token is valid. The proof is a real send:

1. ask in the chat for a test button that sends a message to your number (that costs AI credits, like any building);
2. use the button and check whether the message arrived;
3. if it did not, the error that appears carries Meta's own message.

Receiving messages

The Verify Token (webhook) and App Secret (webhook signature) fields exist so the app can receive messages: the Verify Token confirms to Meta that the address is yours, and the App Secret proves that each message received really came from Meta. Without the App Secret, every incoming message is refused.

The callback address Meta asks you to register in that step does not appear on the card today. If your app needs to receive messages, contact support to get your project's address.

Common problems

• It worked yesterday and today it does not send. It is the temporary token, which expired. Generate the permanent one (see above);
• Error about a recipient that is not allowed. The Meta app is in test mode and the destination number is not on the allowed list;
• The reminder does not arrive, but the reply to a customer does. It is the 24-hour window: outside it, only an approved template;
• Error about the template. The name or the language does not match the approved template, or it has not been approved yet;
• The send is refused for lack of credits. The integration credit balance ran out. Check the panel, under Billing.