​
📌 Overview

The WhatsApp integration allows you to connect an AI Employee (Agent) to your WhatsApp Business account via Meta’s Cloud API. Once configured, the AI will automatically respond to incoming messages according to your settings. You can also intervene manually at any time through ZappWay’s Inbox interface.

Important: After migrating a phone number to the WhatsApp Business Platform, that number cannot be used simultaneously in the standard WhatsApp Business App. It must be dedicated exclusively to one platform.

​
🔢 Table of Contents

  1. Create a Meta Business Account
  2. Create a Meta App and Enable WhatsApp
  3. Create a System User in Business Manager
  4. Generate a System User Access Token
  5. Register and Verify Your Phone Number
  6. Configure Webhooks in the Meta App
  7. Connect Your Meta App to ZappWay
  8. Scan the QR Code to Pair Your Number
  9. Final Checks and Monitoring

​
1. Create a Meta Business Account

  1. Navigate to https://business.facebook.com.

  2. Click “Create Account.”

  3. Fill out the required information:

    • Business Name
    • Your Full Name
    • Work Email

  4. Continue through the prompts to finalize setup. When prompted:

    • Add a Facebook Page (it can be a temporary or test page).
    • Add a Payment Method if requested.
    • Complete Business Verification by submitting the necessary documents (e.g., company registration, proof of address).

Tip: Meta may limit certain features on new accounts until you complete the verification process. Follow all on-screen instructions and provide any additional documents requested.

​
2. Create a Meta App and Enable WhatsApp

  1. Go to https://developers.facebook.com/apps.

  2. Click “Create App.”

  3. When prompted “What do you want your app to do?”, select “Other.”

  4. Choose “Business” as your app type.

  5. Complete the form by providing:

    • App Name (for example, “ZappWay WhatsApp Integration”)
    • Contact Email
    • Link to the Meta Business Account you created in Step 1.

  6. Click “Create App.”

  7. Inside your newly created App’s dashboard, locate the “Products” section.

  8. Select “+ Add Product.”

  9. Find “WhatsApp” in the list, and click “Set Up.”

Note:

  • If Meta requests additional business verification at this stage, complete that process before proceeding.
  • If you do not see WhatsApp listed, ensure you are working under the correct Business Manager account.

​
3. Create a System User in Business Manager

To manage long-lived tokens and assign the necessary permissions, you must create a System User inside Business Manager.

  1. In Business Manager, navigate to Business Settings → Users → System Users.

  2. Click “Add” (or “Add System User”).

  3. Enter a descriptive name (for example, “ZappWay WhatsApp Bot”) and choose “Admin” as the role.

  4. Confirm by clicking “Create.”

  5. Select the newly created System User from the list.

  6. Click “Add Assets.”

    • For Asset Type, choose “Apps.”
    • Select the WhatsApp App you created in Step 2.
    • Grant “Manage App” permission.

  7. Click “Assign.”

Verify:

  • The System User should now have “Manage App” listed under its App permissions.
  • This ensures the user can generate tokens and configure the WhatsApp product.

​
4. Generate a System User Access Token

This token will be used to authenticate your integration from ZappWay.

  1. Still in Business Settings → System Users, select the System User you created.

  2. Click “Generate New Token.”

  3. Choose the WhatsApp App you linked in Step 3.

  4. Select all of the following permissions:

    • whatsapp_business_messaging
    • whatsapp_business_management
    • business_management

  5. Click “Generate Token.”

  6. Copy the token that appears and store it securely (for example, in a password manager or environment variable).

    • If you only generated a short-lived token, you can extend it by clicking “Generate Long-Lived Token.”
    • Long-lived tokens last up to 60 days before they must be renewed.

Security Tip:

  • Never hardcode this token into your code repository.
  • Use environment variables or a secrets manager in production.

​
5. Register and Verify Your Phone Number

To send and receive messages through the API, you need an active and verified phone number.

  1. In your Meta App’s WhatsApp dashboard (navigate to developers.facebook.com/apps/<YOUR_APP_ID>/whatsapp-business/wa-dev-console), find the “Numbers” section.

  2. Click “Add Phone Number.”

  3. You have two options:

    • Use a Test Number provided by Meta (for development only).
    • Register Your Real Number by entering its digits (including country code, e.g., +5511987654321).

  4. Click “Register.”

  5. Meta will send a verification code via SMS or voice call to that number.

  6. Enter the verification code in the prompt to confirm and activate the number.

  7. Once verified, your number will appear as “Active” and you will see:

    • Phone Number ID: a unique identifier for that number.
    • WhatsApp Business Account ID: identifies which business account controls this number.

Keep a Note Of:

  • Phone Number ID format: typically a long numeric string.
  • Business Account ID: also a numeric string you may need later.

​
6. Configure Webhooks in the Meta App

To allow ZappWay to receive incoming message events, you must configure a webhook.

  1. In your Meta App’s WhatsApp settings (go to developers.facebook.com/apps/<YOUR_APP_ID>/whatsapp-business/wa-settings), locate the “Webhooks” section.

  2. In “Callback URL,” enter the URL provided by ZappWay, which will look like:

    https://app.zappway.ai/api/integrations/whatsapp/webhook?service_provider_id=<SERVICE_PROVIDER_ID>
    • <SERVICE_PROVIDER_ID>: the unique ID generated by ZappWay when you create the integration (you will obtain this in Step 7).

  3. In “Verify Token,” enter the verification token that ZappWay creates for you. This token will be visible in the ZappWay interface during integration setup.

  4. Under “Webhook Fields,” make sure to select at least “messages.” This allows ZappWay to receive incoming text messages.

  5. Click “Save” or “Continue.” Once saved, Meta will send a challenge to your callback URL to verify it. If ZappWay is properly configured, it will automatically respond with the expected challenge value.

Validation Checklist:

  • Confirm that messages is checked under Webhook Fields.
  • If Meta returns a challenge error (HTTP 403 or 404), double-check that your callback URL and verification token match exactly what ZappWay provided.

​
7. Connect Your Meta App to ZappWay

Follow these steps within the ZappWay dashboard to complete the integration.

  1. Log in to your ZappWay dashboard.
  2. In the sidebar, navigate to Integrations → WhatsApp.
  3. Click “Add WhatsApp Integration.” This will open a guided four-step setup wizard.

​
Step 1: Requirements

  • You will see a brief overview and a link to the full ZappWay integration documentation.
  • Click “Continue” to move to the next step.

​
Step 2: System User Access Token

  • Copy the long-lived access token you generated in Step 4.

  • Paste it into the “System User Token” field.

  • Click “Continue.”

    • ZappWay will validate your token by making a request to Meta’s token‐debug endpoint.
    • If the token is expired or missing required permissions, you will see an error and must generate a new token.

​
Step 3: Phone Number ID

  • Enter the Phone Number ID you obtained in Step 5.

  • Click “Continue.”

    • ZappWay will call Meta’s Graph API to verify that the phone number ID belongs to the token.
    • If valid, ZappWay will automatically record the formatted phone number and finalize this step.

​
Step 4: Webhook Configuration

  • ZappWay will display two read-only fields:

    1. Callback URL (e.g., https://app.zappway.ai/api/integrations/whatsapp/webhook?service_provider_id=abcdef123456)
    2. Verification Token (a unique string generated by ZappWay)

  • Copy each of these values. You will enter them in your Meta App’s Webhook settings (refer back to Step 6).

  • Confirm that you have selected “messages” under Webhook Fields in the Meta dashboard.

  • Click “Save.”

Once you click “Save,” ZappWay considers the integration configured. It will wait for Meta to deliver webhook events to the callback URL you provided.

​
8. Scan the QR Code to Pair Your Number

Now that the backend integration is set up, you must link (pair) your WhatsApp Business number with ZappWay by scanning a QR code.

  1. In the ZappWay dashboard under Integrations → WhatsApp, locate your newly created integration entry.
  2. If it is not already connected, you will see a button labeled “Scan QR Code.” Click it to display the QR code.
  3. On your mobile device, open the WhatsApp Business App.
  4. Tap the three‐dot menu (⋮) in the top right → “Linked Devices” (or “Linked Devices”).
  5. Tap “Link a Device” (or “Pair a Device”).
  6. Use your phone’s camera to scan the QR code shown in ZappWay.
  7. After successfully scanning, you will see a confirmation message in the phone app, and ZappWay will update its status to “Connected.”

Troubleshooting Tips:

  • If the QR code does not appear, ensure your browser is not blocking pop-ups or that your session in ZappWay has not timed out.
  • If pairing fails repeatedly, verify that no other active sessions exist for the same number. You may need to log out from other linked devices first.

​
9. Final Checks and Monitoring

After pairing, perform these final verifications to ensure your integration is fully functional.

​
9.1 Verify Connection Status

  • In ZappWay, the integration should now display a “Connected” status indicator (typically green).
  • If it shows “Error” or “Disconnected,” click “Disconnect” to clear the existing session, then repeat Step 8 to scan the QR code again.

​
9.2 Test Message Flow

  1. Send a test message from any WhatsApp account to your newly integrated WhatsApp Business number.
  2. Confirm that the message appears in ZappWay’s Inbox interface.
  3. If you have configured any auto-response rules or AI workflows, verify that the AI Employee replies as expected.

If Messages Do Not Arrive:

  • Confirm that the webhook callback URL is reachable (no firewall blocking, valid SSL certificate).
  • Check ZappWay’s webhook logs to see if Meta is delivering the events.
  • Ensure “messages” remains selected under Webhook Fields in your Meta App settings.

​
9.3 Monitor for Common Errors

  • Access Token Expired (401 Unauthorized):

    • If your System User token expires, ZappWay will show authorization errors in the logs.
    • Generate a new long-lived token in Business Manager and paste it into the “System User Token” field again.

  • Webhook Verification Failures (403/404):

    • Indicates that Meta’s challenge request did not receive the expected verification token.
    • Double-check that the callback URL and verify token you entered in Meta match exactly what ZappWay provided.

  • Session Failure (stream:error 515):

    • Means the WhatsApp session could not be persisted.
    • Confirm that no other WhatsApp session is logged in on the same number and that your server has a stable network connection.
    • If needed, use ZappWay’s “Disconnect” function to clear the session and try scanning the QR code again.

​
9.4 Token Renewal Schedule

  • Long-lived tokens are valid for up to 60 days.
  • Before a token expires, repeat Step 4 to generate a new token and then return to Integrations → WhatsApp in ZappWay to replace the old token with the new one.

​
✅ Final Notes

  • Business Account Verification: A fully verified Meta Business Account unlocks higher messaging limits and ensures uninterrupted API access.
  • Message Limits: New WhatsApp Business accounts often start with lower messaging quotas. Engage actively and follow Meta’s guidelines to gradually increase your limit.
  • Webhook Reliability: Make sure your server’s webhook endpoint is always online and can respond to incoming requests within a timely manner.
  • Security Best Practices: Store tokens in secure vaults or environment variables. Rotate them periodically to maintain security.

By following these steps carefully, you will have a robust, fully functional WhatsApp integration in ZappWay, enabling your AI Employee to handle customer interactions seamlessly.

Useful Links:

Follows these instructions exactly, and your integration will be set up successfully.