Instagram

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

1. Convert to Instagram Business Account
2. Link Instagram to Facebook Page
3. Create a Meta App and Enable Instagram
4. Generate a Page Access Token
5. Get Your Instagram Account ID
6. Configure Webhooks
7. Connect to ZappWay
8. Final Checks and Monitoring

​

1. Convert to Instagram Business Account

​

1.1 Convert Personal to Business Account

1. Open the Instagram mobile app.
2. Go to your profile and tap the menu (☰).
3. Tap Settings and privacy → Account type and tools → Switch to professional account.
4. Choose Business or Creator (Business is recommended for most use cases).
5. Select a category that best describes your account.
6. Add contact details (email, phone, address) as needed.
7. 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

​

2.1 Connect via Instagram App

1. Go to your Instagram profile.
2. Tap the menu (☰) → Settings and privacy.
3. Tap Business (or Account Center).
4. Tap Page (or Connected accounts).
5. Tap Connect Facebook Page.
6. Select the Facebook Page you want to connect, or create a new one.
7. Confirm the connection.

​

2.2 Verify Connection

1. In your Instagram profile, go to Settings → Account → Linked accounts.
2. You should see your Facebook Page listed.
3. 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

1. Navigate to https://business.facebook.com.
2. Create or log in to your Business Manager account.
3. Complete business verification if required (submit documents like company registration).

​

3.2 Create a Meta App

1. Go to https://developers.facebook.com/apps.
2. Click “Create App.”
3. Select “Other” when asked what your app should do.
4. Choose “Business” as your app type.
5. Fill in the app details:
   • App Name: “ZappWay Instagram Bot” (or similar)
   • Contact Email: Your business email
   • Business Account: Select your Business Manager
6. Click “Create App.”

​

3.3 Add Instagram Product

1. In your App dashboard, go to “Products” in the left sidebar.
2. Find “Instagram” and click “Set Up.”
3. 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

​

4.1 Generate Token

1. In your Meta App, navigate to Instagram → Settings (or Instagram Basic Display → Settings).
2. Scroll to “Access Tokens” section.
3. You’ll see a list of Facebook Pages. Find the Page connected to your Instagram account.
4. Click “Generate Token” next to that Page.
5. Accept the permission requests.
6. 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:
  1. Go to Business Manager → Settings → System Users
  2. Create a new System User with Admin role
  3. Assign the App to the System User with “Manage App” permission
  4. Generate a token from System User settings with “Never Expire” option
  5. Select required permissions: pages_messaging, instagram_basic, instagram_manage_messages

​

4.2 Verify Token Permissions

• ✅ 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

​

5. Get Your Instagram Account ID

​

5.1 Find Instagram Account ID in Meta App

1. In your Meta App dashboard, go to Instagram → Settings.
2. Scroll to find your connected Instagram accounts.
3. You’ll see the Instagram Account ID displayed as a long numeric string (e.g., 17841401234567890).
4. Copy this ID - you’ll need it for ZappWay configuration.

​

5.2 Alternative Method via Graph API

curl -X GET "https://graph.facebook.com/v21.0/me/accounts?access_token=YOUR_PAGE_ACCESS_TOKEN"

curl -X GET "https://graph.facebook.com/v21.0/PAGE_ID?fields=instagram_business_account&access_token=YOUR_PAGE_ACCESS_TOKEN"

​

6. Configure Webhooks

​

6.1 Set Up Webhook URL

1. In your Meta App, go to Instagram → Settings.
2. Locate the “Webhooks” section.
3. Click “Add Callback URL”.
4. You’ll configure this in Step 7 after creating the integration in ZappWay.

​

6.2 Webhook Fields to Subscribe

• ✅ 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

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

​

Step 2: Page Access Token

1. Paste the Page Access Token you generated in Step 4.
2. 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

1. Paste the Instagram Account ID you obtained in Step 5.
2. 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

https://app.zappway.ai/api/integrations/instagram/webhook?service_provider_id=abc123

[unique string generated by ZappWay]

1. Copy both values.
2. Return to your Meta App → Instagram → Settings → Webhooks.
3. Paste the Callback URL.
4. Paste the Verify Token.
5. Click “Verify and Save.”
6. Subscribe to webhook fields: messages, messaging_postbacks, messaging_optins, message_deliveries, message_reads.
7. 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

1. Send a Direct Message to your Instagram Business account from another account.
2. Verify the message appears in ZappWay’s Inbox.
3. 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

• 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

• 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