> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zappway.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Instagram

> The Instagram integration allows you to connect an **AI Employee** (Agent) to your Instagram Business or Creator account via Meta Instagram Messaging API. Once configured, the AI will automatically respond to incoming Direct Messages (DMs) according to your settings. You can also intervene manually at any time through the ZappWay Inbox interface.

> **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](#1-convert-to-instagram-business-account)
2. [Link Instagram to Facebook Page](#2-link-instagram-to-facebook-page)
3. [Create a Meta App and Enable Instagram](#3-create-a-meta-app-and-enable-instagram)
4. [Generate a Page Access Token](#4-generate-a-page-access-token)
5. [Get Your Instagram Account ID](#5-get-your-instagram-account-id)
6. [Configure Webhooks](#6-configure-webhooks)
7. [Connect to ZappWay](#7-connect-to-zappway)
8. [Final Checks and Monitoring](#8-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

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

Your Instagram Business account must be connected to a Facebook Page to use the API.

### 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](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](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

The Page Access Token authenticates your integration and allows ZappWay to send and receive messages through your Instagram account.

### 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

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

Verify permissions at: `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

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

You can also get the ID using Graph API:

```bash theme={null}
curl -X GET "https://graph.facebook.com/v21.0/me/accounts?access_token=YOUR_PAGE_ACCESS_TOKEN"
```

Then use the Page ID to get Instagram account:

```bash theme={null}
curl -X GET "https://graph.facebook.com/v21.0/PAGE_ID?fields=instagram_business_account&access_token=YOUR_PAGE_ACCESS_TOKEN"
```

The response will contain the `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

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

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

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

ZappWay will display webhook configuration details:

**Callback URL:**

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

**Verify Token:**

```
[unique string generated by ZappWay]
```

**Action Required:**

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

**"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

**Webhook verification fails:**

* 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

**Messages not sending:**

* Verify token has instagram\_manage\_messages permission
* Check Instagram messaging is enabled in Instagram app settings
* Review rate limits in Meta App dashboard

**"Not authorized to access this resource":**

* 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

**Messaging Windows:**

* 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

**Content Restrictions:**

* 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](https://developers.facebook.com/docs/messenger-platform/instagram)
* **Instagram Graph API**: [https://developers.facebook.com/docs/instagram-api](https://developers.facebook.com/docs/instagram-api)
* **Webhooks for Instagram**: [https://developers.facebook.com/docs/messenger-platform/instagram/features/webhook](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](https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/overview#instagram-platform-policy)
* **Community Guidelines**: [https://help.instagram.com/477434105621119](https://help.instagram.com/477434105621119)

***

**Need Help?**

If you encounter issues during setup, contact ZappWay support or visit our documentation at [docs.zappway.ai](https://docs.zappway.ai)