Important Requirements:
- You must have an Instagram Business or Instagram Creator account (personal accounts are not supported)
- The Instagram account must be linked to a Facebook Page
- Your Meta App must have Instagram Messaging product enabled
đ˘ Table of Contents
- Convert to Instagram Business Account
- Link Instagram to Facebook Page
- Create a Meta App and Enable Instagram
- Generate a Page Access Token
- Get Your Instagram Account ID
- Configure Webhooks
- Connect to ZappWay
- Final Checks and Monitoring
1. Convert to Instagram Business Account
If you already have an Instagram Business or Creator account, skip to Step 2.1.1 Convert Personal to Business Account
- Open the Instagram mobile app.
- Go to your profile and tap the menu (â°).
- Tap Settings and privacy â Account type and tools â Switch to professional account.
- Choose Business or Creator (Business is recommended for most use cases).
- Select a category that best describes your account.
- Add contact details (email, phone, address) as needed.
- Complete the setup process.
Note: You can also convert via Settings â Account â Switch to Professional Account on some versions of Instagram.
2. Link Instagram to Facebook Page
Your Instagram Business account must be connected to a Facebook Page to use the API.2.1 Connect via Instagram App
- Go to your Instagram profile.
- Tap the menu (â°) â Settings and privacy.
- Tap Business (or Account Center).
- Tap Page (or Connected accounts).
- Tap Connect Facebook Page.
- Select the Facebook Page you want to connect, or create a new one.
- Confirm the connection.
2.2 Verify Connection
- In your Instagram profile, go to Settings â Account â Linked accounts.
- You should see your Facebook Page listed.
- Ensure the connection shows as âActive.â
Important: The Facebook Page you connect will be used to generate the access token in Step 4.
3. Create a Meta App and Enable Instagram
3.1 Create Meta Business Account
- Navigate to https://business.facebook.com.
- Create or log in to your Business Manager account.
- Complete business verification if required (submit documents like company registration).
3.2 Create a Meta App
- Go to https://developers.facebook.com/apps.
- Click âCreate App.â
- Select âOtherâ when asked what your app should do.
- Choose âBusinessâ as your app type.
- Fill in the app details:
- App Name: âZappWay Instagram Botâ (or similar)
- Contact Email: Your business email
- Business Account: Select your Business Manager
- Click âCreate App.â
3.3 Add Instagram Product
- In your App dashboard, go to âProductsâ in the left sidebar.
- Find âInstagramâ and click âSet Up.â
- Wait for the Instagram product to be added (this may take a few moments).
Note: If Instagram product is not available, ensure:
- Your Meta App is in Business type
- You have completed business verification
- Instagram Messaging API is available in your region
4. Generate a Page Access Token
The Page Access Token authenticates your integration and allows ZappWay to send and receive messages through your Instagram account.4.1 Generate Token
- In your Meta App, navigate to Instagram â Settings (or Instagram Basic Display â Settings).
- Scroll to âAccess Tokensâ section.
- Youâll see a list of Facebook Pages. Find the Page connected to your Instagram account.
- Click âGenerate Tokenâ next to that Page.
- Accept the permission requests.
- Copy the generated Page Access Token and store it securely.
CRITICAL: Token Expiration
- Page Access Tokens expire after 60 days by default.
- For production use, create a System User in Business Manager:
- Go to Business Manager â Settings â System Users
- Create a new System User with Admin role
- Assign the App to the System User with âManage Appâ permission
- Generate a token from System User settings with âNever Expireâ option
- Select required permissions: pages_messaging, instagram_basic, instagram_manage_messages
4.2 Verify Token Permissions
Required permissions for Instagram messaging:- â instagram_basic - Basic Instagram account info
- â instagram_manage_messages - Send and receive messages
- â pages_messaging - Message through Facebook Page
- â pages_show_list - Access list of pages
https://developers.facebook.com/tools/debug/accesstoken/
5. Get Your Instagram Account ID
You need the Instagram Account ID (not the username) to configure the integration.5.1 Find Instagram Account ID in Meta App
- In your Meta App dashboard, go to Instagram â Settings.
- Scroll to find your connected Instagram accounts.
- Youâll see the Instagram Account ID displayed as a long numeric string (e.g.,
17841401234567890). - Copy this ID - youâll need it for ZappWay configuration.
5.2 Alternative Method via Graph API
You can also get the ID using Graph API:instagram_business_account.id field.
6. Configure Webhooks
Webhooks enable Meta to send incoming Instagram DMs to ZappWay in real-time.6.1 Set Up Webhook URL
- In your Meta App, go to Instagram â Settings.
- Locate the âWebhooksâ section.
- Click âAdd Callback URLâ.
- Youâll configure this in Step 7 after creating the integration in ZappWay.
6.2 Webhook Fields to Subscribe
Subscribe to these webhook fields:- â messages - Receive incoming direct messages
- â messaging_postbacks - Receive button clicks
- â messaging_optins - Receive opt-in events
- â message_deliveries - Track delivery status
- â message_reads - Track read receipts
7. Connect to ZappWay
Step 1: Requirements
- Log in to your ZappWay dashboard.
- Navigate to Integrations â Instagram.
- Click âAdd Instagram Integration.â
- Review the requirements and click âContinue.â
Step 2: Page Access Token
- Paste the Page Access Token you generated in Step 4.
- Click âContinue.â
- ZappWay will validate the token and retrieve your connected Facebook Page.
- The system will verify that an Instagram Business account is linked to this Page.
Step 3: Instagram Account ID
- Paste the Instagram Account ID you obtained in Step 5.
- Click âContinue.â
- ZappWay will validate the account ID using your token.
- The system will retrieve your Instagram username and profile information.
- If validation succeeds, ZappWay will create the integration.
Step 4: Webhook Configuration
ZappWay will display webhook configuration details: Callback URL:- Copy both values.
- Return to your Meta App â Instagram â Settings â Webhooks.
- Paste the Callback URL.
- Paste the Verify Token.
- Click âVerify and Save.â
- Subscribe to webhook fields: messages, messaging_postbacks, messaging_optins, message_deliveries, message_reads.
- Return to ZappWay and click âFinish.â
8. Final Checks and Monitoring
8.1 Verify Connection Status
- In ZappWayâs Integrations page, verify the Instagram integration shows âConnectedâ.
- Your Instagram username should be displayed.
8.2 Test Message Flow
- Send a Direct Message to your Instagram Business account from another account.
- Verify the message appears in ZappWayâs Inbox.
- Check that your AI Employee responds according to configured rules.
If Messages Donât Arrive:
- Verify webhook callback URL matches exactly in Meta App
- Check webhook subscriptions are active for âmessagesâ
- Review webhook delivery logs in Meta App dashboard
- Ensure your Page Access Token is valid and hasnât expired
- Confirm Instagram account is properly linked to Facebook Page
8.3 Common Issues and Solutions
âInstagram account not foundâ:- Verify the Instagram account is set to Business or Creator type
- Ensure Instagram is linked to the correct Facebook Page
- Check that the Page Access Token has instagram_basic permission
- Double-check Callback URL and Verify Token match exactly
- Ensure ZappWay servers are accessible from Metaâs IPs
- Review Meta App webhook logs for specific error messages
- Verify token has instagram_manage_messages permission
- Check Instagram messaging is enabled in Instagram app settings
- Review rate limits in Meta App dashboard
- Regenerate Page Access Token with all required permissions
- Verify token is generated for the correct Facebook Page
- Check that System User (if used) has proper App permissions
8.4 Rate Limits and Restrictions
Instagram Messaging API Limits:- Standard rate limit: 200 API calls per hour
- Message recipients limited by your app verification level
- Higher limits available after app review and verification
- You can only respond to users within 24 hours of their last message
- After 24 hours, you need user consent to send a new message
- Use Message Tags for specific use cases outside the 24-hour window
- Follow Instagramâs Community Guidelines
- Avoid spam, promotional content, or misleading messages
- Donât send unsolicited messages
â Best Practices
Security
- Store Page Access Tokens securely (environment variables, secrets manager)
- Use System User tokens for production (never-expiring)
- Rotate tokens regularly (at least every 60 days)
- Monitor token usage and expiration dates
Compliance
- Follow Instagram Platform Policy and Meta Platform Terms
- Obtain user consent before messaging
- Provide clear opt-out instructions
- Respect user privacy and data protection laws
User Experience
- Respond quickly (under 3 seconds when possible)
- Use rich media (images, quick replies) for engagement
- Implement typing indicators for longer responses
- Provide helpful, contextual information
Monitoring
- Set up alerts for webhook delivery failures
- Track message delivery and read rates
- Monitor API error rates
- Review user engagement metrics
đ Useful Links
- Instagram Messaging API: https://developers.facebook.com/docs/messenger-platform/instagram
- Instagram Graph API: https://developers.facebook.com/docs/instagram-api
- Webhooks for Instagram: https://developers.facebook.com/docs/messenger-platform/instagram/features/webhook
- Platform Policy: https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/overview#instagram-platform-policy
- Community Guidelines: https://help.instagram.com/477434105621119
Need Help? If you encounter issues during setup, contact ZappWay support or visit our documentation at docs.zappway.ai

