Integrations

Connect Instagram Direct

Follow Evnao’s Facebook Login setup path to connect an Instagram Professional account linked to a Facebook Page. This reference shares the setup wizard’s instructions; use the wizard to verify and save your connection.

Open Instagram setup wizard

Open the step you need. Meta menu labels and API fields retain their original names so you can find them. External links below open Meta tools.

Setup steps

Step 1: Prepare Instagram Professional Account & Facebook Page

Verify account types, Page connections, and administrative rights

Evnao's Instagram AI integration connects via Meta's Facebook Login bridge. This requires an Instagram Professional account linked to an active Facebook Page with administrative access.

Instagram account type is set to Professional (Business or Creator, not Personal)
Facebook Page exists and is published
Instagram account is actively linked to the Facebook Page (Settings -> Linked Accounts)
Your Facebook account has Full Control / Admin access over both the Page and Instagram account
Two-Factor Authentication (2FA) is enabled on your Facebook account if your Business Portfolio enforces it

If you manage multiple Facebook Pages with the same name, do NOT identify the Page by name alone. In later steps, we will verify the exact numeric Page ID.

Personal Instagram accounts cannot receive automated direct messages via Meta Graph API.

Open Meta Business Settings

Check your Business Portfolio, Pages, and Instagram accounts

Open Facebook 2FA Settings

Ensure Two-Factor Authentication is active on your profile

Step 2: Create or Open Your Meta Developer App

Maintain a single consistent Meta App for all configurations and credentials

Open the Meta Developer Portal and select or create the app you will use for Evnao. It is critical that all permissions, Facebook Login configurations, webhooks, and App Secrets come from the exact same Meta App.

developers.facebook.com → My Apps → Create App (or open existing)

Do NOT create one Meta app for permissions and then copy the App Secret or tokens from a different app. All credentials must belong to the same app.

Select 'Business' or 'Other' when prompted for the app type during creation in Meta Developer Portal.

Open Meta Developer Apps

View and manage your Meta Developer applications

Step 3: Configure Instagram Messaging Use Case

Enable Business Messaging with the Facebook Login API setup

Add the Instagram messaging capability to your Meta App. When Meta asks for the API setup type, select 'API setup with Facebook login'.

Meta Developer App → Use Cases → Add Use Case → Business messaging → Manage messaging & content on Instagram → Customize → API setup with Facebook login

IMPORTANT: Choose 'API setup with Facebook login' and NOT 'API setup with Instagram login'. These are two separate Meta integration architectures, and Evnao's current integration is designed around the Facebook Login Page-bridge architecture.

Meta Instagram Messaging Docs

Official Meta documentation for Instagram messaging setup

Step 4: Configure Required Page & Messaging Permissions

Enable the complete 7-permission set required for messaging and webhook delivery

Your Meta App and authorization token must include all 7 required permissions to read messages, discover Page assets, and subscribe to webhooks.

instagram_basic
instagram_manage_messages
pages_show_list
pages_read_engagement
pages_manage_metadata
pages_messaging
business_management

If you do not see pages_manage_metadata in the explorer: Go to 'Use Cases' -> 'Add Use Case' -> 'Manage everything on your Page' and enable Page management permissions.

If you receive error (#200) requiring pages_messaging: Go to 'Use Cases' -> 'Add Use Case' -> 'Engage with customers on Messenger from Meta' and enable pages_messaging.

Step 5: Configure Facebook Login for Business

Create a reusable business configuration requesting Pages and Instagram accounts

In your Meta App dashboard, navigate to Facebook Login for Business and create a new configuration. This defines which assets and permissions are requested during authorization.

Meta Developer App → Facebook Login for Business → Configurations → Create Configuration

Meta will generate a Configuration ID (e.g. 1122334455667788). Do NOT paste this Configuration ID into Evnao's Page ID or Instagram ID fields. The Configuration ID is only used inside Meta.

Name the configuration clearly, e.g., 'Evnao Instagram AI'.

Under 'Required Assets', check both 'Pages' and 'Instagram accounts', and mark them as 'Asset Required'.

Leave unrelated assets (Ad accounts, Catalogs, Pixels) unchecked.

Include all 7 permissions from Step 4 in the configuration.

Facebook Login for Business Docs

Official guide on configuring Facebook Login for Business

Step 6: Authorize the Business in Graph API Explorer

Select your Business Portfolio, Facebook Page, and Instagram account

Open Meta's Graph API Explorer tool. Select your Meta App, initiate authorization, and select your specific Business Portfolio, Facebook Page, and Instagram account.

If you belong to multiple Business Portfolios, make sure you choose the portfolio that owns the target Page. Choosing the wrong portfolio will cause Graph API to return empty results.

Open Graph API Explorer

Meta's interactive tool for running Graph API queries and generating tokens

Step 7: Discover Your Numeric Page & Instagram IDs

Execute /me/accounts to find the exact numeric IDs needed by Evnao

In Graph API Explorer, run the query below to retrieve your Facebook Pages and their linked Instagram Professional accounts.

Connected Facebook Page ID: Found at data[].id (e.g. 123456789012345). Enter this into Evnao.
Instagram Professional Account ID: Found at data[].instagram_business_account.id (e.g. 17841412345678901). Enter this into Evnao.
Instagram Username: Found at instagram_business_account.username. Used only to identify your account. Do NOT enter username into ID fields.

DUPLICATE PAGE NAMES: If multiple Pages appear with the same name, inspect the 'instagram_business_account.username' field to pick the Page that actually connects to your Instagram account.

MISSING instagram_business_account: If data[].instagram_business_account is null, check that your Instagram account is Professional and linked to that exact Page in Instagram App Settings.

Query to Discover Page & Instagram IDs

GET /me/accounts?fields=id,name,access_token,instagram_business_account{id,username,name}

Run this GET request in Graph API Explorer to find your numeric Page ID and Instagram Account ID.

{
  "data": [
    {
      "id": "123456789012345",
      "name": "Example Business",
      "access_token": "EAABw...",
      "instagram_business_account": {
        "id": "17841412345678901",
        "username": "examplebusiness",
        "name": "Example Business"
      }
    }
  ]
}

Step 8: Generate a Long-Lived Page Access Token

Derive a Page token and check its validity and expiration details

Follow the User-token extension and Page-token derivation steps below. Inspect validity and expiration in Meta's debugger rather than assuming the token will remain valid indefinitely.

Stage A: In Graph API Explorer, click 'Get User Access Token' and grant all 7 required permissions.
Stage B: Open Access Token Debugger, paste the User token, and click 'Extend Access Token' to get a 60-day long-lived User token.
Stage C: Paste the 60-day User token back into Graph API Explorer, run GET /me/accounts, and copy the 'access_token' belonging to your Page.

SECURITY WARNING: Never share your Page Access Token, App Secret, or passwords in support chats or public channels.

Do NOT store a short-lived User token into Evnao. The final token must be derived from the Page object.

Open Access Token Debugger

Inspect token type, scopes, and click 'Extend Access Token'

Meta Long-Lived Token Docs

Official guide on obtaining long-lived access tokens

Step 9: Verify Your Page Access Token & Account Link

Confirm the Page token type, validity, expiration and data-access details

Paste your derived Page Access Token into Meta's Access Token Debugger and run the verification queries below in Graph API Explorer.

Access Token Debugger reports Type: Page
Access Token Debugger reports Valid: True
Review expiration and data-access details in Access Token Debugger
Page ID in debugger matches your Facebook Page ID
Scopes list contains pages_messaging and instagram_manage_messages

1. Verify Page Token Identity

GET /me?fields=id,name

Run with your Page token selected. The returned ID must match your Facebook Page ID.

{
  "id": "123456789012345",
  "name": "Example Business"
}

2. Verify Linked Instagram Relationship

GET /{PAGE_ID}?fields=id,name,instagram_business_account{id,username,name}

Replace {PAGE_ID} with your numeric Page ID. Must return your linked Instagram account.

{
  "id": "123456789012345",
  "name": "Example Business",
  "instagram_business_account": {
    "id": "17841412345678901",
    "username": "examplebusiness"
  }
}

Step 10: Test Page Webhook Subscription

Subscribe your Facebook Page to receive messages and messaging_postbacks events

Using your verified Page Access Token in Graph API Explorer, issue a POST request to subscribe the Page to messages webhook events.

Do NOT proceed until this endpoint returns { "success": true }.

If you receive Error #210 ('A Page access token is required'): you have a User token selected instead of a Page token.

If you receive Error #200 ('User does not have sufficient administrative permission'): ensure your Facebook user has Full Control in Business Settings and enable 2FA on your account.

Subscribe Page to Messages Webhook

POST /{PAGE_ID}/subscribed_apps?subscribed_fields=messages,messaging_postbacks

Replace {PAGE_ID} with your numeric Facebook Page ID and ensure POST is selected with the Page Access Token.

{
  "success": true
}

Step 11: Configure Meta App Webhooks & Verify Token

Set up the Evnao Webhook Callback URL and matching private Verify Token in Meta

Configure your Meta Developer App's Instagram Webhooks so Meta knows where to send real-time incoming Direct Messages.

Meta Developer App → Webhooks → Select 'Instagram' → Edit Subscription / Callback URL

Callback URL = Evnao Webhook Callback URL (provided in your Evnao workspace)
Verify Token = Identical private string generated in Evnao
Subscribed fields: 'messages' and 'messaging_postbacks'
App-level webhook subscribed AND Page-level subscription completed

The Verify Token is a private secret created by you / Evnao — it is NOT provided by Meta.

If Meta reports 'The callback URL or verify token couldn't be validated', make sure the Verify Token entered in Meta matches the one in Evnao character-for-character without extra spaces.

Step 12: Enter the Five Values into Evnao

Save your verified IDs and secret credentials securely into Evnao

Enter the 5 required parameters into the Evnao Instagram connection form. All secrets are stored securely and encrypted in your workspace.

Instagram Professional Account ID: Numeric ID found at instagram_business_account.id (e.g. 17841412345678901).
Connected Facebook Page ID: Numeric ID of the Facebook Page connected to Instagram (e.g. 123456789012345).
Page Access Token: A Page token whose type, validity and expiration details you checked in Meta's debugger.
Meta App Secret: Found at Meta Developer Dashboard -> App Settings -> Basic -> App Secret.
Webhook Verify Token: The private random string matching the verify token entered in Meta's Webhook configuration.

Step 13: Enable AI Replies & Set Reply Policies

Activate automatic AI responses, business hours, and human handoff rules

In Evnao Integrations Settings, enable 'Allow AI replies on this channel' and optionally configure business hours schedules or timezone limits.

Check 'Allow AI replies on this channel' is ON
Configure Business Hours if you want AI active only during specific work hours
Set your workspace timezone (e.g. Asia/Amman, America/New_York)
Review Human Takeover: replying directly from Instagram or Evnao Inbox automatically pauses AI for that customer

Step 14: Test in Development / Testing Mode

Send a test DM from an authorized Instagram Tester account

Before your Meta App receives Advanced Access approval, only authorized Instagram Testers and App Admins can exchange messages with the connected account.

Meta Developer App → App Roles → Roles → Instagram Testers → Add Instagram Tester

Add a test Instagram account as an 'Instagram Tester' in Meta Developer App
Log into that test Instagram account, open Settings -> Apps & Websites -> Tester Invites, and ACCEPT the invitation
Confirm tester status is no longer 'Pending'
From the test account, send a plain text message ('Hello test') to your business Instagram account
Check Evnao Inbox for the new inbound thread and verified AI reply

If the tester invitation is still 'Pending', Meta will drop all incoming webhook messages. The invite MUST be accepted.

Start with simple text-only messages first (e.g. 'Hello test'). Avoid voice notes, reels, or images for the initial test.

Step 15: Production Readiness & Live Customer Access

Transition from testing mode to live public access for all Instagram users

Review your Meta app's mode, permissions and required app review before serving the public. Saving a connection in Evnao does not confirm Meta approval.

Development Mode: Only registered testers and page administrators can message the bot.
Check Live mode and the permissions required for public messaging.
Verify the required app review and access in Meta; do not assume Evnao grants them automatically.

Check Meta's requirements for the app you are using. Completing this guide is not approval from Meta.

Setup-path permissions

Review the wizard’s permissions step before creating the token. These are the Meta identifiers used by this setup path.

instagram_basic
instagram_manage_messages
pages_show_list
pages_read_engagement
pages_manage_metadata
pages_messaging
business_management

Connection troubleshooting

(#210) A Page access token is required to request this resource

You are executing an operation (like subscribing webhooks or sending messages) using a User Access Token or System User Token instead of a Page Access Token.

Open Graph API Explorer (developers.facebook.com/tools/explorer).
In the 'User or Page' dropdown, select your Facebook Page (NOT your User profile).
Verify the token identity by running: GET /me?fields=id,name. The returned ID must match your numeric Facebook Page ID.
Re-run your endpoint (e.g. POST /{PAGE_ID}/subscribed_apps) with this Page token selected.

(#200) To subscribe to the messages field, one of these permissions is needed: pages_messaging

The Page Access Token or Meta App lacks the 'pages_messaging' permission, which is strictly required to subscribe to the messages webhook field.

Open your Meta Developer App (developers.facebook.com/apps).
Go to 'Use Cases' -> 'Add Use Case' -> 'Engage with customers on Messenger from Meta'.
Add and enable the 'pages_messaging' permission.
Return to Graph API Explorer, click 'Get User Access Token', ensure 'pages_messaging' is checked, and reauthorize.
Extend your User token in Token Debugger, then re-derive a fresh Page Access Token via GET /me/accounts.
Retry the POST /{PAGE_ID}/subscribed_apps subscription call.

(#100) Object does not exist, cannot be loaded due to missing permission: pages_read_engagement

The token cannot read the Page or its linked Instagram business account because the 'pages_read_engagement' and 'pages_show_list' permissions are missing or not granted on the token.

Open Graph API Explorer.
Add both 'pages_read_engagement' and 'pages_show_list' to the Permissions list.
Click 'Generate Access Token' and grant full access to your Page and Instagram account in the Meta popup.
Remember: Permissions added in the dashboard do NOT automatically update existing tokens. You must derive a fresh token after adding permissions.

Cannot find 'pages_manage_metadata' in Graph API Explorer

Meta organizes permissions by Use Case. If 'pages_manage_metadata' is not listed in Explorer, the Page Management use case has not been added to your app.

Open your Meta Developer App.
Navigate to 'Use Cases' -> 'Add Use Case'.
Look for 'Manage everything on your Page' (or Page Management) and click 'Add'.
Enable 'pages_manage_metadata' inside the use case.
Reload Graph API Explorer to see the permission available.

(#200) User does not have sufficient administrative permission for this action on this page

Your Facebook personal account does not have Full Control (Admin) rights over the Facebook Page or Instagram business account in Meta Business Settings.

Open Meta Business Settings (business.facebook.com/settings).
Go to 'Users' -> 'People' and click on your name.
Under 'Pages', click on your Page and toggle 'Full Control (Manage Page)' to ON.
Under 'Instagram accounts', click on your account and assign yourself full access.
Save changes, reauthorize in Graph API Explorer, and generate a fresh token.

Two Factor Authentication required by Business Portfolio

The Meta Business Portfolio enforcing security rules requires all admins to have 2FA enabled on their personal Facebook profile before performing administrative API operations.

Open Facebook Security Settings: https://www.facebook.com/security/2fa/settings/.
Enable Two-Factor Authentication using an authenticator app (e.g. Google Authenticator, 1Password) or SMS.
Confirm 2FA is active on your profile, then reload Meta Business Settings.
Re-generate your tokens in Graph API Explorer.

(#100) Tried accessing nonexisting field (accounts) on /me/accounts

You ran GET /me/accounts while a System User Token or Page Token was loaded in Graph API Explorer. The '/me/accounts' edge is only valid for User Access Tokens.

In Graph API Explorer, check the 'User or Page' dropdown.
Switch to 'User Token' (representing your personal Facebook user).
Ensure you paste your extended Long-Lived User Token into the Access Token field.
Re-run: GET /me/accounts?fields=id,name,access_token,instagram_business_account{id,username,name}.

The callback URL or verify token couldn't be validated

Meta's webhook verification GET challenge failed because the Verify Token entered in Meta does not match Evnao, or the Callback URL is unreachable.

In Evnao, copy your Webhook Verify Token and paste it into Meta's 'Verify Token' field without any leading/trailing spaces.
Confirm that the Callback URL in Meta exactly matches your Evnao webhook URL (e.g. https://evnao.com/api/webhooks/instagram/{teamId}).
Ensure your Evnao integration is saved with that exact Verify Token before clicking 'Verify and Save' in Meta.

Error validating access token: Session has expired or token is invalid

The Page Access Token was derived from a short-lived User token (which expires in 1-2 hours), or the Facebook user's password/security settings were changed.

Open Meta's Access Token Debugger (developers.facebook.com/tools/debug/accesstoken/).
Inspect your token: If 'Expires' says 'in about an hour' or is in the past, it was a short-lived token.
Follow Step 8: Generate a User Token -> Click 'Extend Access Token' in Token Debugger -> Paste the extended User Token into Graph API Explorer -> Run GET /me/accounts -> Copy the Page access_token.
Verify the new token's Page type, validity, expiration and data-access details in Token Debugger.
Update the new Page token in Evnao Integrations Settings.

(#3) Application does not have the capability to make this API call

For Facebook Login integrations, outbound messages to Instagram users must use the connected Facebook Page ID endpoint (/{PAGE_ID}/messages) with the Page Access Token. Also occurs if the recipient has not accepted their Instagram Tester invitation in Development mode.

Confirm your Instagram Tester has ACCEPTED the tester invite in Instagram App Settings -> Apps & Websites -> Tester Invites.
Confirm your Evnao settings have the correct numeric Facebook Page ID and Page Access Token entered.
Evnao's backend automatically routes outbound messages through the verified /{PAGE_ID}/messages endpoint.

Meta Webhook Debugger reports: Manage Messaging Toggle is Off

In Instagram account settings, access to messages by third-party connected tools is disabled.

Open the Instagram mobile app on your phone.
Go to Settings and privacy -> Messages and story replies -> Message controls.
Under 'Connected tools', toggle 'Allow access to messages' to ON.
Retest in Meta's Webhook Debugger.

Instagram Tester status shows 'Pending' in Meta Developer Portal

The test Instagram account was invited as an Instagram Tester in the Meta Developer Portal, but the user has not yet accepted the invite inside the Instagram app.

Log into the test Instagram account on a mobile device or web browser.
Open Profile -> Settings and privacy -> Website permissions (or Apps and websites) -> Tester invitations.
Click 'Accept' on the pending Evnao app invitation.
Return to Meta Developer Portal and confirm the status has changed from 'Pending' to active.

Multiple Facebook Pages appear with the exact same name

You or your organization have multiple Facebook Pages sharing the same business name, and only one is linked to your Instagram account.

In Graph API Explorer, run GET /me/accounts?fields=id,name,instagram_business_account{id,username,name}.
Look at each returned Page object. Find the one where 'instagram_business_account' contains your exact Instagram username.
Record the numeric 'id' belonging to THAT specific Page object.
Do NOT use Page names to distinguish them — always use the verified numeric Page ID.

Wrong ID: Entered Configuration ID, App ID, or Business ID instead of Page ID

Meta has many IDs (App ID, Business Portfolio ID, Configuration ID, Page ID, Instagram ID). Evnao requires ONLY the numeric Facebook Page ID and Instagram Account ID.

Facebook Page ID: Found at data[].id from /me/accounts. Must be numeric.
Instagram ID: Found at data[].instagram_business_account.id from /me/accounts (usually starts with 1784...).
Do NOT use your Meta App ID, Business Portfolio ID, or Configuration ID in Evnao.

/me/accounts returns Facebook Page but 'instagram_business_account' is missing or null

The Facebook Page is not actively linked to an Instagram Professional account, or the Instagram account is set to Personal.

Open Instagram on mobile: Settings -> Account type and tools -> Switch to professional account (Business or Creator).
Open Facebook Page Settings -> Linked Accounts -> Instagram -> Connect Account.
In Meta Business Settings, ensure both the Page and Instagram account are in the same Business Portfolio.
Re-run GET /me/accounts in Graph API Explorer to confirm the ID appears.

Messages not arriving: App-level vs Page-level webhook confusion

Meta separates webhooks into two distinct steps: 1) App-level Instagram webhook configuration with Callback URL, and 2) Page-level subscription via /{PAGE_ID}/subscribed_apps.

Ensure App-level webhook is configured under Meta App -> Webhooks -> Instagram with 'messages' and 'messaging_postbacks' subscribed.
Ensure Page-level webhook is subscribed by running POST /{PAGE_ID}/subscribed_apps?subscribed_fields=messages,messaging_postbacks using your Page Access Token.
Both layers must be active for messages to reach Evnao.

Integrations

Connect Instagram Direct

Open Instagram setup wizard

Open the step you need. Meta menu labels and API fields retain their original names so you can find them. External links below open Meta tools.

Setup steps

Step 1: Prepare Instagram Professional Account & Facebook Page

Verify account types, Page connections, and administrative rights

Evnao's Instagram AI integration connects via Meta's Facebook Login bridge. This requires an Instagram Professional account linked to an active Facebook Page with administrative access.

Instagram account type is set to Professional (Business or Creator, not Personal)
Facebook Page exists and is published
Instagram account is actively linked to the Facebook Page (Settings -> Linked Accounts)
Your Facebook account has Full Control / Admin access over both the Page and Instagram account
Two-Factor Authentication (2FA) is enabled on your Facebook account if your Business Portfolio enforces it

If you manage multiple Facebook Pages with the same name, do NOT identify the Page by name alone. In later steps, we will verify the exact numeric Page ID.

Personal Instagram accounts cannot receive automated direct messages via Meta Graph API.

Open Meta Business Settings

Check your Business Portfolio, Pages, and Instagram accounts

Open Facebook 2FA Settings

Ensure Two-Factor Authentication is active on your profile

Step 2: Create or Open Your Meta Developer App

Maintain a single consistent Meta App for all configurations and credentials

developers.facebook.com → My Apps → Create App (or open existing)

Do NOT create one Meta app for permissions and then copy the App Secret or tokens from a different app. All credentials must belong to the same app.

Select 'Business' or 'Other' when prompted for the app type during creation in Meta Developer Portal.

Open Meta Developer Apps

View and manage your Meta Developer applications

Step 3: Configure Instagram Messaging Use Case

Enable Business Messaging with the Facebook Login API setup

Add the Instagram messaging capability to your Meta App. When Meta asks for the API setup type, select 'API setup with Facebook login'.

Meta Developer App → Use Cases → Add Use Case → Business messaging → Manage messaging & content on Instagram → Customize → API setup with Facebook login

Meta Instagram Messaging Docs

Official Meta documentation for Instagram messaging setup

Step 4: Configure Required Page & Messaging Permissions

Enable the complete 7-permission set required for messaging and webhook delivery

Your Meta App and authorization token must include all 7 required permissions to read messages, discover Page assets, and subscribe to webhooks.

instagram_basic
instagram_manage_messages
pages_show_list
pages_read_engagement
pages_manage_metadata
pages_messaging
business_management

If you do not see pages_manage_metadata in the explorer: Go to 'Use Cases' -> 'Add Use Case' -> 'Manage everything on your Page' and enable Page management permissions.

If you receive error (#200) requiring pages_messaging: Go to 'Use Cases' -> 'Add Use Case' -> 'Engage with customers on Messenger from Meta' and enable pages_messaging.

Step 5: Configure Facebook Login for Business

Create a reusable business configuration requesting Pages and Instagram accounts

In your Meta App dashboard, navigate to Facebook Login for Business and create a new configuration. This defines which assets and permissions are requested during authorization.

Meta Developer App → Facebook Login for Business → Configurations → Create Configuration

Meta will generate a Configuration ID (e.g. 1122334455667788). Do NOT paste this Configuration ID into Evnao's Page ID or Instagram ID fields. The Configuration ID is only used inside Meta.

Name the configuration clearly, e.g., 'Evnao Instagram AI'.

Under 'Required Assets', check both 'Pages' and 'Instagram accounts', and mark them as 'Asset Required'.

Leave unrelated assets (Ad accounts, Catalogs, Pixels) unchecked.

Include all 7 permissions from Step 4 in the configuration.

Facebook Login for Business Docs

Official guide on configuring Facebook Login for Business

Step 6: Authorize the Business in Graph API Explorer

Select your Business Portfolio, Facebook Page, and Instagram account

Open Meta's Graph API Explorer tool. Select your Meta App, initiate authorization, and select your specific Business Portfolio, Facebook Page, and Instagram account.

If you belong to multiple Business Portfolios, make sure you choose the portfolio that owns the target Page. Choosing the wrong portfolio will cause Graph API to return empty results.

Open Graph API Explorer

Meta's interactive tool for running Graph API queries and generating tokens

Step 7: Discover Your Numeric Page & Instagram IDs

Execute /me/accounts to find the exact numeric IDs needed by Evnao

In Graph API Explorer, run the query below to retrieve your Facebook Pages and their linked Instagram Professional accounts.

Connected Facebook Page ID: Found at data[].id (e.g. 123456789012345). Enter this into Evnao.
Instagram Professional Account ID: Found at data[].instagram_business_account.id (e.g. 17841412345678901). Enter this into Evnao.
Instagram Username: Found at instagram_business_account.username. Used only to identify your account. Do NOT enter username into ID fields.

DUPLICATE PAGE NAMES: If multiple Pages appear with the same name, inspect the 'instagram_business_account.username' field to pick the Page that actually connects to your Instagram account.

MISSING instagram_business_account: If data[].instagram_business_account is null, check that your Instagram account is Professional and linked to that exact Page in Instagram App Settings.

Query to Discover Page & Instagram IDs

GET /me/accounts?fields=id,name,access_token,instagram_business_account{id,username,name}

Run this GET request in Graph API Explorer to find your numeric Page ID and Instagram Account ID.

{
  "data": [
    {
      "id": "123456789012345",
      "name": "Example Business",
      "access_token": "EAABw...",
      "instagram_business_account": {
        "id": "17841412345678901",
        "username": "examplebusiness",
        "name": "Example Business"
      }
    }
  ]
}

Step 8: Generate a Long-Lived Page Access Token

Derive a Page token and check its validity and expiration details

Follow the User-token extension and Page-token derivation steps below. Inspect validity and expiration in Meta's debugger rather than assuming the token will remain valid indefinitely.

Stage A: In Graph API Explorer, click 'Get User Access Token' and grant all 7 required permissions.
Stage B: Open Access Token Debugger, paste the User token, and click 'Extend Access Token' to get a 60-day long-lived User token.
Stage C: Paste the 60-day User token back into Graph API Explorer, run GET /me/accounts, and copy the 'access_token' belonging to your Page.

SECURITY WARNING: Never share your Page Access Token, App Secret, or passwords in support chats or public channels.

Do NOT store a short-lived User token into Evnao. The final token must be derived from the Page object.

Open Access Token Debugger

Inspect token type, scopes, and click 'Extend Access Token'

Meta Long-Lived Token Docs

Official guide on obtaining long-lived access tokens

Step 9: Verify Your Page Access Token & Account Link

Confirm the Page token type, validity, expiration and data-access details

Paste your derived Page Access Token into Meta's Access Token Debugger and run the verification queries below in Graph API Explorer.

Access Token Debugger reports Type: Page
Access Token Debugger reports Valid: True
Review expiration and data-access details in Access Token Debugger
Page ID in debugger matches your Facebook Page ID
Scopes list contains pages_messaging and instagram_manage_messages

1. Verify Page Token Identity

GET /me?fields=id,name

Run with your Page token selected. The returned ID must match your Facebook Page ID.

{
  "id": "123456789012345",
  "name": "Example Business"
}

2. Verify Linked Instagram Relationship

GET /{PAGE_ID}?fields=id,name,instagram_business_account{id,username,name}

Replace {PAGE_ID} with your numeric Page ID. Must return your linked Instagram account.

{
  "id": "123456789012345",
  "name": "Example Business",
  "instagram_business_account": {
    "id": "17841412345678901",
    "username": "examplebusiness"
  }
}

Step 10: Test Page Webhook Subscription

Subscribe your Facebook Page to receive messages and messaging_postbacks events

Using your verified Page Access Token in Graph API Explorer, issue a POST request to subscribe the Page to messages webhook events.

Do NOT proceed until this endpoint returns { "success": true }.

If you receive Error #210 ('A Page access token is required'): you have a User token selected instead of a Page token.

If you receive Error #200 ('User does not have sufficient administrative permission'): ensure your Facebook user has Full Control in Business Settings and enable 2FA on your account.

Subscribe Page to Messages Webhook

POST /{PAGE_ID}/subscribed_apps?subscribed_fields=messages,messaging_postbacks

Replace {PAGE_ID} with your numeric Facebook Page ID and ensure POST is selected with the Page Access Token.

{
  "success": true
}

Step 11: Configure Meta App Webhooks & Verify Token

Set up the Evnao Webhook Callback URL and matching private Verify Token in Meta

Configure your Meta Developer App's Instagram Webhooks so Meta knows where to send real-time incoming Direct Messages.

Meta Developer App → Webhooks → Select 'Instagram' → Edit Subscription / Callback URL

Callback URL = Evnao Webhook Callback URL (provided in your Evnao workspace)
Verify Token = Identical private string generated in Evnao
Subscribed fields: 'messages' and 'messaging_postbacks'
App-level webhook subscribed AND Page-level subscription completed

The Verify Token is a private secret created by you / Evnao — it is NOT provided by Meta.

If Meta reports 'The callback URL or verify token couldn't be validated', make sure the Verify Token entered in Meta matches the one in Evnao character-for-character without extra spaces.

Step 12: Enter the Five Values into Evnao

Save your verified IDs and secret credentials securely into Evnao

Enter the 5 required parameters into the Evnao Instagram connection form. All secrets are stored securely and encrypted in your workspace.

Instagram Professional Account ID: Numeric ID found at instagram_business_account.id (e.g. 17841412345678901).
Connected Facebook Page ID: Numeric ID of the Facebook Page connected to Instagram (e.g. 123456789012345).
Page Access Token: A Page token whose type, validity and expiration details you checked in Meta's debugger.
Meta App Secret: Found at Meta Developer Dashboard -> App Settings -> Basic -> App Secret.
Webhook Verify Token: The private random string matching the verify token entered in Meta's Webhook configuration.

Step 13: Enable AI Replies & Set Reply Policies

Activate automatic AI responses, business hours, and human handoff rules

In Evnao Integrations Settings, enable 'Allow AI replies on this channel' and optionally configure business hours schedules or timezone limits.

Check 'Allow AI replies on this channel' is ON
Configure Business Hours if you want AI active only during specific work hours
Set your workspace timezone (e.g. Asia/Amman, America/New_York)
Review Human Takeover: replying directly from Instagram or Evnao Inbox automatically pauses AI for that customer

Step 14: Test in Development / Testing Mode

Send a test DM from an authorized Instagram Tester account

Before your Meta App receives Advanced Access approval, only authorized Instagram Testers and App Admins can exchange messages with the connected account.

Meta Developer App → App Roles → Roles → Instagram Testers → Add Instagram Tester

Add a test Instagram account as an 'Instagram Tester' in Meta Developer App
Log into that test Instagram account, open Settings -> Apps & Websites -> Tester Invites, and ACCEPT the invitation
Confirm tester status is no longer 'Pending'
From the test account, send a plain text message ('Hello test') to your business Instagram account
Check Evnao Inbox for the new inbound thread and verified AI reply

If the tester invitation is still 'Pending', Meta will drop all incoming webhook messages. The invite MUST be accepted.

Start with simple text-only messages first (e.g. 'Hello test'). Avoid voice notes, reels, or images for the initial test.

Step 15: Production Readiness & Live Customer Access

Transition from testing mode to live public access for all Instagram users

Review your Meta app's mode, permissions and required app review before serving the public. Saving a connection in Evnao does not confirm Meta approval.

Development Mode: Only registered testers and page administrators can message the bot.
Check Live mode and the permissions required for public messaging.
Verify the required app review and access in Meta; do not assume Evnao grants them automatically.

Check Meta's requirements for the app you are using. Completing this guide is not approval from Meta.

Setup-path permissions

Review the wizard’s permissions step before creating the token. These are the Meta identifiers used by this setup path.

instagram_basic
instagram_manage_messages
pages_show_list
pages_read_engagement
pages_manage_metadata
pages_messaging
business_management

Connection troubleshooting

(#210) A Page access token is required to request this resource

You are executing an operation (like subscribing webhooks or sending messages) using a User Access Token or System User Token instead of a Page Access Token.

Open Graph API Explorer (developers.facebook.com/tools/explorer).
In the 'User or Page' dropdown, select your Facebook Page (NOT your User profile).
Verify the token identity by running: GET /me?fields=id,name. The returned ID must match your numeric Facebook Page ID.
Re-run your endpoint (e.g. POST /{PAGE_ID}/subscribed_apps) with this Page token selected.

(#200) To subscribe to the messages field, one of these permissions is needed: pages_messaging

The Page Access Token or Meta App lacks the 'pages_messaging' permission, which is strictly required to subscribe to the messages webhook field.

Open your Meta Developer App (developers.facebook.com/apps).
Go to 'Use Cases' -> 'Add Use Case' -> 'Engage with customers on Messenger from Meta'.
Add and enable the 'pages_messaging' permission.
Return to Graph API Explorer, click 'Get User Access Token', ensure 'pages_messaging' is checked, and reauthorize.
Extend your User token in Token Debugger, then re-derive a fresh Page Access Token via GET /me/accounts.
Retry the POST /{PAGE_ID}/subscribed_apps subscription call.

(#100) Object does not exist, cannot be loaded due to missing permission: pages_read_engagement

The token cannot read the Page or its linked Instagram business account because the 'pages_read_engagement' and 'pages_show_list' permissions are missing or not granted on the token.

Open Graph API Explorer.
Add both 'pages_read_engagement' and 'pages_show_list' to the Permissions list.
Click 'Generate Access Token' and grant full access to your Page and Instagram account in the Meta popup.
Remember: Permissions added in the dashboard do NOT automatically update existing tokens. You must derive a fresh token after adding permissions.

Cannot find 'pages_manage_metadata' in Graph API Explorer

Meta organizes permissions by Use Case. If 'pages_manage_metadata' is not listed in Explorer, the Page Management use case has not been added to your app.

Open your Meta Developer App.
Navigate to 'Use Cases' -> 'Add Use Case'.
Look for 'Manage everything on your Page' (or Page Management) and click 'Add'.
Enable 'pages_manage_metadata' inside the use case.
Reload Graph API Explorer to see the permission available.

(#200) User does not have sufficient administrative permission for this action on this page

Your Facebook personal account does not have Full Control (Admin) rights over the Facebook Page or Instagram business account in Meta Business Settings.

Open Meta Business Settings (business.facebook.com/settings).
Go to 'Users' -> 'People' and click on your name.
Under 'Pages', click on your Page and toggle 'Full Control (Manage Page)' to ON.
Under 'Instagram accounts', click on your account and assign yourself full access.
Save changes, reauthorize in Graph API Explorer, and generate a fresh token.

Two Factor Authentication required by Business Portfolio

The Meta Business Portfolio enforcing security rules requires all admins to have 2FA enabled on their personal Facebook profile before performing administrative API operations.

Open Facebook Security Settings: https://www.facebook.com/security/2fa/settings/.
Enable Two-Factor Authentication using an authenticator app (e.g. Google Authenticator, 1Password) or SMS.
Confirm 2FA is active on your profile, then reload Meta Business Settings.
Re-generate your tokens in Graph API Explorer.

(#100) Tried accessing nonexisting field (accounts) on /me/accounts

You ran GET /me/accounts while a System User Token or Page Token was loaded in Graph API Explorer. The '/me/accounts' edge is only valid for User Access Tokens.

In Graph API Explorer, check the 'User or Page' dropdown.
Switch to 'User Token' (representing your personal Facebook user).
Ensure you paste your extended Long-Lived User Token into the Access Token field.
Re-run: GET /me/accounts?fields=id,name,access_token,instagram_business_account{id,username,name}.

The callback URL or verify token couldn't be validated

Meta's webhook verification GET challenge failed because the Verify Token entered in Meta does not match Evnao, or the Callback URL is unreachable.

In Evnao, copy your Webhook Verify Token and paste it into Meta's 'Verify Token' field without any leading/trailing spaces.
Confirm that the Callback URL in Meta exactly matches your Evnao webhook URL (e.g. https://evnao.com/api/webhooks/instagram/{teamId}).
Ensure your Evnao integration is saved with that exact Verify Token before clicking 'Verify and Save' in Meta.

Error validating access token: Session has expired or token is invalid

The Page Access Token was derived from a short-lived User token (which expires in 1-2 hours), or the Facebook user's password/security settings were changed.

Open Meta's Access Token Debugger (developers.facebook.com/tools/debug/accesstoken/).
Inspect your token: If 'Expires' says 'in about an hour' or is in the past, it was a short-lived token.
Follow Step 8: Generate a User Token -> Click 'Extend Access Token' in Token Debugger -> Paste the extended User Token into Graph API Explorer -> Run GET /me/accounts -> Copy the Page access_token.
Verify the new token's Page type, validity, expiration and data-access details in Token Debugger.
Update the new Page token in Evnao Integrations Settings.

(#3) Application does not have the capability to make this API call

Confirm your Instagram Tester has ACCEPTED the tester invite in Instagram App Settings -> Apps & Websites -> Tester Invites.
Confirm your Evnao settings have the correct numeric Facebook Page ID and Page Access Token entered.
Evnao's backend automatically routes outbound messages through the verified /{PAGE_ID}/messages endpoint.

Meta Webhook Debugger reports: Manage Messaging Toggle is Off

In Instagram account settings, access to messages by third-party connected tools is disabled.

Open the Instagram mobile app on your phone.
Go to Settings and privacy -> Messages and story replies -> Message controls.
Under 'Connected tools', toggle 'Allow access to messages' to ON.
Retest in Meta's Webhook Debugger.

Instagram Tester status shows 'Pending' in Meta Developer Portal

The test Instagram account was invited as an Instagram Tester in the Meta Developer Portal, but the user has not yet accepted the invite inside the Instagram app.

Log into the test Instagram account on a mobile device or web browser.
Open Profile -> Settings and privacy -> Website permissions (or Apps and websites) -> Tester invitations.
Click 'Accept' on the pending Evnao app invitation.
Return to Meta Developer Portal and confirm the status has changed from 'Pending' to active.

Multiple Facebook Pages appear with the exact same name

You or your organization have multiple Facebook Pages sharing the same business name, and only one is linked to your Instagram account.

In Graph API Explorer, run GET /me/accounts?fields=id,name,instagram_business_account{id,username,name}.
Look at each returned Page object. Find the one where 'instagram_business_account' contains your exact Instagram username.
Record the numeric 'id' belonging to THAT specific Page object.
Do NOT use Page names to distinguish them — always use the verified numeric Page ID.

Wrong ID: Entered Configuration ID, App ID, or Business ID instead of Page ID

Meta has many IDs (App ID, Business Portfolio ID, Configuration ID, Page ID, Instagram ID). Evnao requires ONLY the numeric Facebook Page ID and Instagram Account ID.

Facebook Page ID: Found at data[].id from /me/accounts. Must be numeric.
Instagram ID: Found at data[].instagram_business_account.id from /me/accounts (usually starts with 1784...).
Do NOT use your Meta App ID, Business Portfolio ID, or Configuration ID in Evnao.

/me/accounts returns Facebook Page but 'instagram_business_account' is missing or null

The Facebook Page is not actively linked to an Instagram Professional account, or the Instagram account is set to Personal.

Open Instagram on mobile: Settings -> Account type and tools -> Switch to professional account (Business or Creator).
Open Facebook Page Settings -> Linked Accounts -> Instagram -> Connect Account.
In Meta Business Settings, ensure both the Page and Instagram account are in the same Business Portfolio.
Re-run GET /me/accounts in Graph API Explorer to confirm the ID appears.

Messages not arriving: App-level vs Page-level webhook confusion

Meta separates webhooks into two distinct steps: 1) App-level Instagram webhook configuration with Callback URL, and 2) Page-level subscription via /{PAGE_ID}/subscribed_apps.

Ensure App-level webhook is configured under Meta App -> Webhooks -> Instagram with 'messages' and 'messaging_postbacks' subscribed.
Ensure Page-level webhook is subscribed by running POST /{PAGE_ID}/subscribed_apps?subscribed_fields=messages,messaging_postbacks using your Page Access Token.
Both layers must be active for messages to reach Evnao.

Getting started

Core concepts

Integrations

Getting started

Core concepts

Integrations

Connect Instagram Direct

Setup steps

Query to Discover Page & Instagram IDs

1. Verify Page Token Identity

2. Verify Linked Instagram Relationship

Subscribe Page to Messages Webhook

Setup-path permissions

Connection troubleshooting

Connect Instagram Direct

Setup steps

Query to Discover Page & Instagram IDs

1. Verify Page Token Identity

2. Verify Linked Instagram Relationship

Subscribe Page to Messages Webhook

Setup-path permissions

Connection troubleshooting