Connect Maxbot to WhatsApp Cloud API.

Maxbot WhatsApp Integration is an add-on. It extends an installed and authorized Maxbot Core plugin; it does not replace the core builder.

Core owns agents, topics, entities, conversation blocks, Flow Editor logic, Users Data, training, and the project model. The add-on receives Meta webhook events, resolves the linked WhatsApp project and assigned flow, passes the message into Maxbot, and sends the resulting response through WhatsApp Cloud API.

• An installed, active, and authorized Maxbot Core plugin.
• A complete Maxbot topic/flow that already passes Test Flow.
• The installable Maxbot WhatsApp Integration add-on ZIP.
• A Meta developer account and a Business Portfolio.
• A Meta app using the WhatsApp Business use case.
• A public HTTPS WordPress site that Meta can reach.
• Administrator access to WordPress and appropriate control of the Meta business assets.

1. Confirm Maxbot Core is installed, active, authorized, and functioning.
2. Open Plugins → Add New Plugin → Upload Plugin.
3. Choose the installable WhatsApp add-on ZIP and select Install Now.
4. Activate the add-on.
5. Open Maxbot → WhatsApp Integration and confirm Settings, Templates, Dashboard/Logs, and Troubleshooting are available.

1. Create the Meta app and select the WhatsApp Business use case.
2. Validate Meta’s test phone assets.
3. Copy development credentials into Maxbot.
4. Configure the callback URL, verify token, and messages subscription.
5. Create and link a WhatsApp project to a tested Maxbot flow.
6. Add the real business number and permanent system-user token.
7. Run a two-way production test and inspect logs.
8. Complete business verification and template approval when required.

1. Open Meta for Developers and select My Apps → Create App.
2. Enter an app name and contact email.
3. Choose the WhatsApp Business use case.
4. Select the Business Portfolio that should own the WhatsApp Business Account.
5. Review the selection, create the app, and complete any confirmation Meta requests.
6. On the app dashboard, add or customize the WhatsApp product and open its API Setup.

1. Open the WhatsApp product’s API Setup or Try it out area.
2. Select Meta’s test sender number.
3. Add a recipient number that you control and verify it when Meta requires confirmation.
4. Send Meta’s sample message.
5. Confirm it arrives before adding Maxbot to the path.
6. Record the App ID, WABA ID, test Phone Number ID, and temporary access token shown for the development assets.

1. Open Maxbot → WhatsApp Integration → Settings.
2. Copy the App ID from the Meta app dashboard.
3. Reveal and copy the App Secret from Meta’s basic app settings.
4. Copy the WABA ID, development Phone Number ID, and temporary access token from WhatsApp API Setup.
5. Paste each value into the matching Maxbot field without surrounding spaces or labels.
6. Create a strong verify token that is not the App Secret or access token.
7. Save the settings before configuring the webhook in Meta.

1. In Maxbot WhatsApp settings, confirm the verify token and credentials are saved.
2. Copy the callback URL generated by Maxbot.
3. In Meta, open WhatsApp → Configuration and choose to configure the webhook.
4. Paste the callback URL into Meta’s Callback URL field.
5. Paste the exact same verify token.
6. Select Verify and Save.
7. In the webhook fields list, subscribe to messages.

1. Open WhatsApp Integration → Troubleshooting.
2. Select Test Connection.
3. If webhook delivery is disabled, enable it, save, and retest.
4. Confirm the app, WABA, phone assets, callback, and subscription are detected.
5. Confirm the WABA is subscribed to the app and the messages field is active.
6. Send a Meta test message and reply from the recipient phone.
7. Verify the incoming event appears in Maxbot’s logs.

1. In Maxbot Core, create and fully test the topic/flow that should answer WhatsApp messages.
2. Open Projects and select Add New Project.
3. Enter a project name and select the WhatsApp project/channel type.
4. Assign the correct agent and conversation flow.
5. Choose whether any incoming message or only specific messages can start the flow.
6. For a specific-message trigger, enter keywords or phrases and choose Exact, Contains, or Starts with.
7. Enable “only trigger if no active conversation exists” when a new trigger should not restart an ongoing session.
8. Optionally configure a website WhatsApp launcher and prefilled message.
9. Save and enable the project.

1. Open WhatsApp Integration settings.
2. Locate Linked WhatsApp Project.
3. Select the WhatsApp project created for this integration.
4. Save the settings.
5. Return to Troubleshooting and run the connection test again.
6. Confirm the result identifies the linked project and assigned flow.

1. In WhatsApp API Setup, select Add phone number.
2. Enter the public display name, business category, and business description.
3. Enter the real phone number.
4. Complete Meta’s verification method for that number.
5. Select the new number in API Setup.
6. Copy its Phone Number ID and confirm the WABA ID belongs to the same business account.

1. Open Meta Business Settings.
2. Create or select a system user controlled by the business.
3. Assign the Meta app and WhatsApp Business Account assets.
4. Grant only the WhatsApp permissions required to manage and send messages.
5. Generate a system-user token for the app.
6. Copy the token immediately and store it in the business’s approved secret manager.

1. Open Maxbot WhatsApp settings.
2. Replace the temporary token with the system-user token.
3. Replace the test Phone Number ID with the production Phone Number ID.
4. Confirm the App ID, App Secret, and WABA ID match the production number’s assets.
5. Enter the public business number in international format.
6. Save the settings.
7. Run Test Connection and confirm the detected number, WABA subscription, webhook, linked project, and assigned flow.

1. Open WhatsApp Integration Troubleshooting and confirm every connection check passes.
2. Enter a recipient number using digits in international format.
3. Select an approved template and send the test message.
4. Confirm the message arrives on the recipient phone.
5. Reply with text that matches the configured project trigger.
6. Confirm the linked project starts its assigned Maxbot flow.
7. Complete quick replies, keyword routes, validation, media, joins, and the final action that the flow uses.
8. Verify webhook-received, sent, delivered, and read events in Dashboard or Message Logs where available.
9. Repeat from a second WhatsApp account and after any credential, webhook, template, project, or flow change.

Meta may require Business Verification before production access or higher messaging limits are available.

1. Open Meta Business Settings or Security Center and start verification.
2. Enter the legal business name, address, phone, website, business type, and category exactly as official records show them.
3. Add a trading name only when the business genuinely uses it.
4. Choose an available verification method.
5. Upload a current, readable file of the exact document type Meta requests.
6. Review and submit the information.
7. Monitor the verification status and account email for follow-up requests.
8. After approval, confirm the app, WABA, production number, display name, and system-user assets still match.

WhatsApp message templates are created for defined business-initiated messages and reviewed by Meta. A template has a unique name, language, content, components, samples, and a status.

• Use clear content that matches the real business purpose.
• Provide realistic samples for variables and media.
• Use only publicly accessible HTTPS sample media.
• Do not place a Pending or Rejected template in a production flow.
• Keep the live payload compatible with the approved structure.

Complete the production WhatsApp setup before creating carousel templates.

1. Open WhatsApp Integration → Templates.
2. Select Quick Reply Carousel or Link Carousel.
3. Enter a unique lowercase template name in Meta’s accepted format and choose the language.
4. Write the shared message body that introduces the cards.
5. Select the card body format and choose between 2 and 10 sample cards.
6. Add a publicly accessible HTTPS sample image, realistic title, and description for every card.
7. For a Quick Reply Carousel, enter the reply label returned by each card.
8. For a Link Carousel, configure the shared base URL and enter only each card’s URL suffix.
9. Review the content and select Create Template.

1. After submission, confirm the template appears in Maxbot with Pending status.
2. Open Meta Message Templates and locate the same name and language.
3. Wait for Meta’s review; do not create duplicate copies while the template is pending.
4. When review finishes, return to Maxbot and select Refresh Template Statuses.
5. Use the template only after Maxbot reports Approved.
6. If it is Rejected, inspect Meta’s reason, correct the content or samples, and submit a revised template.

1. Create a topic for the carousel journey and open its Flow Editor.
2. Add a welcome prompt and quick replies that select the desired carousel path.
3. Give every quick reply a defined child-block action.
4. In the child block, enable the card/carousel response and select the approved template.
5. Add the same number of production cards used in the approved template.
6. Provide each production image, title, description, and required action value.
7. For Quick Reply cards, make the returned label match the branch logic.
8. For Link cards, provide only the suffix when the template already defines the base URL.
9. Save, link the flow to the WhatsApp project, and test every card action on a real WhatsApp account.

Use Dashboard and Message Logs to reconstruct the message path:

• Whether Meta delivered the incoming webhook.
• Which sender and phone-number asset produced the event.
• Whether Maxbot resolved the linked project and active conversation.
• Which flow and block handled the input.
• Whether the outgoing request reached sent, delivered, read, or failed status.
• Any sanitized error code and timestamp needed for troubleshooting.

• Use HTTPS for WordPress and the webhook endpoint.
• Keep the App Secret and access token private.
• Validate Meta’s App Secret signature on incoming webhook requests.
• Use a strong, unique verify token.
• Use a system-user token with only the required assets and permissions.
• Restrict WordPress administrator and Meta Business access.
• Rotate credentials after staff, ownership, permission, or exposure changes.
• Keep WordPress, Maxbot Core, the add-on, and server dependencies updated.

• Maxbot Core and the WhatsApp add-on are active, authorized, and current.
• The core flow passes all expected, fallback, validation, join, and ending tests.
• The production phone number is registered and its display name is approved.
• The App ID, App Secret, WABA ID, Phone Number ID, public number, and system-user token belong to matching production assets.
• The callback uses HTTPS, App Secret signature validation is enabled, and the verify token remains private.
• The messages subscription and WABA app subscription are active.
• The WhatsApp project is enabled, linked, and assigned to the intended flow.
• Every live template reports Approved and its payload matches the approved structure.
• Two-way tests from at least two recipient accounts succeed and appear in logs.
• Token storage, staff access, privacy, logging, and escalation procedures are documented.

1. Back up relevant project, template, and message-log information according to the business’s retention policy.
2. Disable the linked WhatsApp project so it stops starting new conversations.
3. Remove or disable Meta webhook subscriptions when the integration is permanently retired.
4. Revoke the system-user token and remove unnecessary app/business asset assignments.
5. Review the add-on cleanup setting, then deactivate and remove the add-on.
6. Keep Maxbot Core installed when other web or channel projects still use it.