Skip to main content
Important: You must have a Facebook Page to use Messenger integration. The Page will be the identity through which your AI responds to users.

🔢 Table of Contents

  1. Create a Meta Business Account
  2. Create a Meta App and Enable Messenger
  3. Generate a Page Access Token
  4. Configure Webhooks in the Meta App
  5. Connect Your Meta App to ZappWay
  6. 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 (you can use an existing page or create a new one).
    • 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 Messenger

  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 Messenger Bot”)
    • 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 “Messenger” in the list, and click “Set Up.”
Note:
  • If Meta requests additional business verification at this stage, complete that process before proceeding.
  • Ensure you are working under the correct Business Manager account.

3. Generate a Page Access Token

The Page Access Token authenticates your integration and allows ZappWay to send and receive messages on behalf of your Facebook Page.

3.1 Generate Token in Meta App Dashboard

  1. In your Meta App, navigate to Messenger → Settings.
  2. Under “Access Tokens” section, you’ll see your connected Facebook Pages.
  3. Select the Page you want to use for this integration.
  4. Click “Generate Token”.
  5. A modal will appear asking for permissions - accept all required permissions.
  6. Copy the generated Page Access Token immediately and store it securely.
CRITICAL: Token Expiration
  • By default, Page Access Tokens expire after 60 days.
  • To create a never-expiring token, you must:
    1. Create a System User in Business Manager
    2. Assign the System User to your App with “Manage App” permission
    3. Generate a token from the System User (select “Never” for expiration)
  • We recommend using never-expiring tokens for production use.

3.2 Verify Token Permissions

Your token must have these permissions:
  • pages_messaging - Send and receive messages
  • pages_manage_metadata - Manage page metadata
  • pages_read_engagement - Read page engagement data
  • pages_show_list - Access list of pages
You can verify permissions at: https://developers.facebook.com/tools/debug/accesstoken/

4. Configure Webhooks in the Meta App

Webhooks allow Meta to send incoming messages to ZappWay in real-time.

4.1 Set Up Webhook URL

  1. In your Meta App’s Messenger settings, locate the “Webhooks” section.
  2. Click “Add Callback URL” (or “Edit Callback URL” if one exists).
  3. You’ll need two pieces of information from ZappWay (obtained in Step 5):
    • Callback URL: https://app.zappway.ai/api/integrations/messenger/webhook?service_provider_id=<SERVICE_PROVIDER_ID>
    • Verify Token: A unique string generated by ZappWay
Note: You’ll get these values after creating the integration in ZappWay (Step 5), so you may need to come back to this step.

4.2 Subscribe to Webhook Fields

After verifying the callback URL, subscribe to these webhook fields:
  • ✅ messages - Receive incoming messages
  • ✅ messaging_postbacks - Receive button clicks and postbacks
  • ✅ messaging_optins - Receive opt-in events
  • ✅ message_deliveries - Track message delivery status
  • ✅ message_reads - Track when messages are read
Click “Subscribe” to activate webhook subscriptions.

5. Connect Your Meta App to ZappWay

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

Step 1: Requirements

  1. Log in to your ZappWay dashboard.
  2. Navigate to Integrations → Messenger.
  3. Click “Add Messenger Integration.”
  4. Review the requirements and click “Continue.”

Step 2: Page Access Token

  1. Paste the Page Access Token you generated in Step 3.
  2. Click “Continue.”
    • ZappWay will validate the token by making a request to Meta’s Graph API.
    • The system will automatically detect your Page ID and Page Name.
    • If validation fails, verify that your token is valid and has the required permissions.

Step 3: Page Selection

  1. ZappWay will display the detected Page Name and Page ID.
  2. If this is correct, click “Continue.”
  3. If you need to use a different page:
    • Generate a new token for that page in the Meta App dashboard
    • Return to Step 2 with the new token

Step 4: Webhook Configuration

ZappWay will display two values you need to configure in Meta:
  1. Callback URL (example: https://app.zappway.ai/api/integrations/messenger/webhook?service_provider_id=abc123)
  2. Verify Token (a unique string generated by ZappWay)
Action Required:
  1. Copy these values.
  2. Return to your Meta App’s Messenger settings (Step 4).
  3. Paste the Callback URL and Verify Token.
  4. Click “Verify and Save” in the Meta dashboard.
  5. Ensure all webhook fields are subscribed (messages, messaging_postbacks, etc.).
  6. Return to ZappWay and click “Finish.”

6. Final Checks and Monitoring

6.1 Verify Connection Status

  • In ZappWay’s Integrations page, the Messenger integration should show “Connected” status.
  • The Page Name should be displayed correctly.

6.2 Test Message Flow

  1. Open Messenger and send a test message to your Facebook Page.
  2. Verify that the message appears in ZappWay’s Inbox.
  3. Check that your AI Employee responds according to configured rules.
If Messages Don’t Arrive:
  • Verify the webhook callback URL is correctly configured in Meta
  • Check that webhook fields are subscribed (especially “messages”)
  • Review webhook logs in Meta App dashboard for delivery errors
  • Ensure your Page Access Token hasn’t expired

6.3 Monitor for Common Issues

Token Expiration (401 Unauthorized):
  • Page Access Tokens can expire after 60 days
  • Use a System User token for never-expiring access
  • Update the token in ZappWay before expiration
Webhook Verification Failures:
  • Verify that Callback URL and Verify Token match exactly
  • Check that ZappWay’s servers are accessible from Meta’s IPs
  • Review Meta App dashboard webhook logs for error details
Messages Not Sending:
  • Verify Page Access Token permissions
  • Check rate limits in Meta App dashboard
  • Review ZappWay logs for API errors
Spam Detection:
  • Meta may flag your Page if too many users block or report it
  • Ensure your AI responses are helpful and appropriate
  • Avoid sending unsolicited messages

6.4 Rate Limits

  • Messenger has rate limits based on your app’s verification level
  • Standard rate limit: 200 API calls per hour per user
  • Higher limits available after app verification
  • Monitor usage in Meta App dashboard

✅ Best Practices

Security

  • Never share your Page Access Token publicly
  • Store tokens in environment variables or secrets manager
  • Rotate tokens periodically (every 60 days minimum)
  • Use System User tokens for production environments

Compliance

  • Follow Meta’s Platform Policies and Messenger Platform Policy
  • Obtain user consent before sending messages
  • Provide clear opt-out mechanisms
  • Respect user preferences and privacy

User Experience

  • Keep response times under 3 seconds
  • Provide helpful, contextual responses
  • Use quick replies for common actions
  • Implement typing indicators for longer responses

Monitoring

  • Set up alerts for webhook failures
  • Monitor message delivery rates
  • Track user engagement metrics
  • Review error logs regularly

🔗 Useful Links

Need Help? If you encounter issues during setup, contact ZappWay support or visit our documentation at docs.zappway.ai