Skip to main content

WhatsApp

Connect WhatsApp Business Platform to BotDojo so inbound WhatsApp messages can trigger a flow and BotDojo can send replies or approved template messages.

Where to configure WhatsApp​

  • BotDojo Integrations: connect or reconnect WhatsApp, copy the BotDojo webhook URL, copy the verify token, and update saved credentials.
  • Meta app dashboard: manage the Meta app, app secret, app review, permissions, Embedded Signup configuration, and webhook callback settings.
  • WhatsApp Manager: manage WhatsApp Business Accounts, phone numbers, display names, quality rating, messaging limits, and message templates.
  • Meta Business Settings: manage users, system users, asset access, and manual access-token permissions.

Useful Meta entry points:

Meta setup checklist​

Use this checklist when you need to create or repair the Meta-side configuration.

1. Set up the Meta app​

  1. Open Meta app dashboard.
  2. Select the production Meta app, or create a new app that supports business messaging/WhatsApp.
  3. Add the WhatsApp product if it is not already present.
  4. In the app's basic settings, copy the App ID and App Secret for the BotDojo environment administrator.
  5. Confirm the app mode and review state:
    • Development mode is only appropriate for app admins, developers, and testers.
    • Production use requires the Meta app, permissions, and business setup to be ready for the users who will connect WhatsApp accounts.

2. Set up Embedded Signup​

Embedded Signup is the recommended connection path.

  1. In the Meta app dashboard, open the Facebook Login for Business or WhatsApp Embedded Signup configuration area.
  2. Create or select the configuration for WhatsApp Embedded Signup.
  3. Make sure the configuration includes the WhatsApp Business capabilities needed to manage WABAs, read phone numbers/templates, and send messages.
  4. Copy the configuration ID for the BotDojo environment administrator.
  5. Confirm the public BotDojo app URL is configured for the environment that will launch Embedded Signup.

After this is configured, BotDojo can launch Meta's signup flow from the WhatsApp integration panel. Meta returns the authorization code and WhatsApp Business Account context to BotDojo, and BotDojo stores the resulting token securely on the integration.

3. Configure webhooks​

  1. In BotDojo, open Hub > Integrations > WhatsApp.
  2. Copy the displayed Webhook URL and Webhook Verify Token.
  3. In the Meta app dashboard, open WhatsApp > Configuration or the app's WhatsApp webhook settings.
  4. Edit the callback URL and verify token.
  5. Paste the exact BotDojo values.
  6. Save/verify the callback. Meta verifies by sending a challenge request to the BotDojo URL.
  7. Manage webhook fields and subscribe to the WhatsApp messages field.

The BotDojo Webhook URL includes the integration ID. Do not reuse a webhook URL from another WhatsApp integration.

4. Prepare the WhatsApp Business Account and phone numbers​

  1. Open WhatsApp Manager.
  2. Choose the correct business portfolio and WhatsApp Business Account.
  3. Add or verify the phone number that BotDojo should use.
  4. Check the phone number's display name, approval status, quality rating, account mode, and messaging limit.
  5. Confirm the phone number is enabled for Cloud API use.

If BotDojo can connect but outbound messages fail with a number or display-name approval error, fix the phone number state in WhatsApp Manager first.

5. Create message templates​

  1. In WhatsApp Manager, open the WABA's message templates.
  2. Create the template, category, language, content, buttons, and placeholder examples.
  3. Submit the template for Meta review.
  4. Wait for approval.
  5. In BotDojo, use Send WhatsApp Template Message and choose an approved template from the connected WABA.

BotDojo only lists templates that Meta returns for the connected WhatsApp Business Account.

6. Manual access token setup​

Use manual access-token setup only when Embedded Signup is unavailable.

  1. Open Meta Business Settings.
  2. Create or choose a user/system user with access to the Meta app and WhatsApp Business Account.
  3. Generate an access token with WhatsApp Business messaging/management permissions.
  4. In BotDojo's WhatsApp integration panel, click Connect with Access Token.
  5. Enter:
    • Access Token
    • WhatsApp Business Account ID
    • App Secret
  6. Save the integration and confirm the connection test succeeds.
  7. Configure the Meta webhook using the BotDojo Webhook URL and Verify Token.
  8. Track token expiration and rotate the token before it expires.

Ongoing Meta management​

  • App mode, app review, permissions: manage these in the Meta app dashboard.
  • Phone numbers, display names, quality, messaging limits: manage these in WhatsApp Manager.
  • Message templates: create, submit, and monitor templates in WhatsApp Manager.
  • User/system-user access and manual tokens: manage these in Meta Business Settings.
  • Billing, payment, and business verification: complete these in Meta when Meta requires them for production messaging, higher limits, or account review.

Connect in BotDojo​

  1. In BotDojo, open Hub > Integrations.
  2. Select WhatsApp.
  3. Click Connect via Embedded Signup.
  4. Complete the Meta-hosted signup flow.
  5. Confirm BotDojo shows the connected WhatsApp Business Account.

Embedded Signup is the recommended setup path. It returns the authorization code, WhatsApp Business Account, and phone number context directly to BotDojo. BotDojo exchanges the code, stores the token securely, resolves the phone numbers, and subscribes the WABA for inbound webhook delivery.

Manual connection fallback​

Use Connect with Access Token only when Embedded Signup is not available.

  1. In Meta Business Settings, create or choose a system user with access to the Meta app and the WhatsApp Business Account.
  2. Generate an access token with WhatsApp Business Platform permissions.
  3. In BotDojo's WhatsApp integration panel, enter:
    • Access Token
    • WhatsApp Business Account ID
    • App Secret
  4. Save the integration.
  5. Copy the BotDojo Webhook URL and Webhook Verify Token from the integration panel.
  6. In the Meta app dashboard, configure the WhatsApp webhook callback URL and verify token with those exact values.

Configure a flow trigger​

  1. Open the flow that should receive WhatsApp messages.
  2. On the Start Node, click Add Trigger.
  3. Choose an integration trigger for WhatsApp.
  4. Select WhatsApp Message.
  5. Choose the phone number ID that should route messages to this flow.
  6. Leave Auto-reply from end node enabled if the flow's final output should be sent back as the WhatsApp reply.
  7. Save or deploy the flow as appropriate for your workspace.

Send WhatsApp messages from a flow​

The WhatsApp integration exposes two tools:

  • Send WhatsApp Message sends free-form text or image messages from a connected phone number ID.
  • Send WhatsApp Template Message sends approved templates from the connected WhatsApp Business Account.

Create and submit templates in WhatsApp Manager. BotDojo lists approved templates from the connected WABA for the template-message tool.

Troubleshooting​

  • Webhook verification fails: make sure the Meta callback URL exactly matches the Webhook URL shown in BotDojo and includes the integration ID. Use the verify token from the same BotDojo integration.
  • Inbound messages reach BotDojo but no flow runs: check the flow's WhatsApp Message trigger, selected phone number ID, and whether the saved flow still points at the active WhatsApp integration.
  • Outbound sends fail with a display-name or phone-number approval error: check the phone number's display name, approval state, and quality status in WhatsApp Manager.
  • Template messages are unavailable or rejected: confirm the template is approved in WhatsApp Manager for the language and category selected in BotDojo.
  • Embedded Signup does not open: ask an admin to verify the running BotDojo environment has the Meta app ID, app secret, Embedded Signup configuration ID, and public BotDojo app URL configured.