Connect a WhatsApp Business number through Meta Cloud API credentials and signed webhooks.
Connect a WhatsApp Business number through Meta Cloud API credentials and signed webhooks.
Prepare the Meta app and number#
Use Meta's official WhatsApp Cloud API getting-started guide to create or select a Meta app, add the WhatsApp product, and associate a WhatsApp Business Account and phone number.
Collect these three values from the same app and number:
| Make Agent Fast field | Provider value | Notes |
|---|---|---|
| Phone number ID | Numeric Phone Number ID | This is not the visible + phone number or WABA ID |
| Access token | Cloud API access token | Temporary dashboard tokens expire; use an appropriate long-lived system-user token for production |
| App secret | Meta app secret | A 32-character hexadecimal secret used for webhook signature verification |
Grant only the permissions needed for the number and messaging workflow. Keep development/test assets separate from the production number.
Save and validate credentials#
Open the site's Connectors page, select WhatsApp, enter all three values, choose Reply with voice if required, and select Connect.
Make Agent Fast validates the number through the Graph API using the access token plus appsecret_proof; this catches a wrong number, token, or app secret before webhook traffic starts. The connector card then reveals a unique Webhook URL and Verify token.
Configure the Meta webhook#
In the same Meta app:
- Open the WhatsApp webhook configuration.
- Paste the connector Webhook URL as the callback URL.
- Paste the connector Verify token exactly; it is case-sensitive.
- Complete verification.
- Subscribe the WhatsApp Business Account/number to the
messageswebhook field. - Confirm the app and business assets are available to the intended test or production users.
The verify token proves ownership during the GET verification challenge. Runtime POST requests are separately authenticated with the Meta app-secret signature; do not substitute one for the other.
Test text and voice#
Send a message from an allowed test number first. During Meta development mode, unregistered users may not be able to reach the app. Confirm the thread and channel in Conversations and watch Last message on the connector card.
Inbound text and voice are supported. With Reply with voice enabled and speech configured, Make Agent Fast uploads generated audio through the Cloud API and sends it alongside the text response. Images, locations, contacts, and other unsupported message types are ignored.
Production readiness#
Before advertising the number, complete the Meta business verification, app review, display-name, template, and messaging-policy steps required for your use case. Those requirements are controlled by Meta and can change independently of Make Agent Fast.
Use a production credential with an intentional owner and expiry/rotation procedure. Record which Meta app, system user, WABA, and Phone Number ID belong to this connector so an operator can rotate it without guessing.
Rotate or disconnect#
Create a replacement token with the same asset access, update the connector, send a test message, and only then revoke the old token. If the app secret changes, update it in Make Agent Fast immediately or every signed inbound webhook will fail.
Disabling or removing the connector does not unsubscribe or delete the Meta webhook configuration. Remove the provider subscription too when permanently decommissioning the number.
Troubleshooting#
| Symptom | Fix |
|---|---|
| Credentials rejected | Confirm the token can read the exact Phone Number ID and the app secret is from the same app |
| Meta cannot verify the callback | Use the copied HTTPS URL and exact verify token; ensure the connector is still present |
| Verification succeeds but no messages arrive | Subscribe messages, check WABA/number association, app mode, test-user access, and provider delivery logs |
| Webhooks return unauthorized | Re-enter the correct app secret; Meta POST signatures do not use the verify token |
| Outbound replies fail | Check token expiry, number permissions, recipient policy/window, and Graph API errors |
| Text works but audio fails | Check transcription/speech provider keys and the token's media upload/download access |
Never expose the access token or app secret in browser code. Use the Public API only from a trusted server when automating connector creation.