Skip to main content
Nudgra needs Meta setup before real Instagram automation can work. This is the part where most setup mistakes happen because the OAuth redirect URL and webhook callback URL are different, especially in Nudgra Cloud. Use this guide after your app has a local URL, tunnel URL, or production domain.
Do not guess the callback URLs. Pick the row for your distribution and paste those exact values into Meta.

​
URL checklist

Replace the placeholder domains before you configure Meta.
PurposeValue
App URLhttps://your-domain.com
Instagram business login redirect URLhttps://your-domain.com/api/meta/callback
Webhook callback URLhttps://your-domain.com/api/meta/webhooks
Verify tokenSame value as META_VERIFY_TOKEN in .env
Nudgra OSS receives both OAuth callbacks and webhooks through the app server.

​
Required permissions

Add these Instagram business permissions in the Meta app: 
instagram_business_basic
instagram_business_manage_messages
instagram_business_manage_comments
You do not need to manually generate Instagram access tokens in Meta. Nudgra performs the Instagram login flow and stores account tokens.

​
1. Create the Meta app

1

Open Meta for Developers

Go to:
https://developers.facebook.com/apps/
2

Create an app

Click Create App.
3

Choose the Instagram use case

For the use case, select Manage messaging & content on Instagram.
4

Finish app creation

Give the app a name and finish the setup flow.
Meta dashboard labels move over time. If a label has changed, look for the Instagram Login or Instagram messaging setup area.

​
2. Add Instagram testers

Add every Instagram account you want to test with before the app is fully reviewed or used by real users. Inside your Meta app dashboard:
  1. Go to App roles.
  2. Click Roles, not Test users.
  3. Click Add People.
  4. Choose Instagram Tester.
  5. Add the Instagram accounts you want to automate with Nudgra.
Each Instagram account must accept the invite:
  1. Open Instagram in a desktop browser.
  2. Go to Settings.
  3. Go to Website permissions.
  4. Go to Apps and Websites.
  5. Open Test invites.
  6. Accept the invite.
The Website permissions area may not appear on mobile. Use Instagram on a computer when accepting tester invites.

​
3. Add permissions

In the Meta app dashboard:
  1. Go to Use cases.
  2. Open the Instagram use case.
  3. Go to API setup with Instagram login.
  4. In Add required messaging permissions, add the required permissions.
Confirm these permissions are present: 
instagram_business_basic
instagram_business_manage_messages
instagram_business_manage_comments

​
4. Publish the app

Webhooks need the app to be published for real delivery. In the Meta app dashboard:
  1. Go to Publish.
  2. Add a privacy policy URL.
  3. Fill any required basic fields.
  4. Publish the app.
For testing, a simple public privacy policy page is enough.

​
5. Copy app credentials

Return to your app in Meta for Developers, then:
  1. Go to Use cases.
  2. Click Customize or open the Instagram use case.
  3. Open API setup with Instagram login.
  4. Find Instagram app ID and copy it.
  5. Reveal Instagram app secret and copy it.
Generate a verify token yourself: 
openssl rand -hex 32
Or generate one with Node: 
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

​
6. Set environment variables

Put the Meta values in .env:
META_APP_ID=your-instagram-app-id
META_APP_SECRET=your-instagram-app-secret
META_VERIFY_TOKEN=your-random-webhook-verify-token
Restart after editing .env:
docker compose up -d --build

​
7. Configure webhooks

In API setup with Instagram login, open Configure webhooks.
Set:
Callback URL:
https://your-domain.com/api/meta/webhooks

Verify token:
same value as META_VERIFY_TOKEN in .env
Subscribe to these webhook fields: 
messages
messaging_postbacks
comments
Click Verify and save.
A plain browser request to the webhook URL may return 403 because it is missing Meta verification query parameters. Use Meta’s Verify and save button as the real verification check.

​
8. Configure Instagram business login

In API setup with Instagram login, open Set up Instagram business login.
Set:
Redirect URL:
https://your-domain.com/api/meta/callback
Save the redirect URL.

​
9. Connect Instagram in Nudgra

Open your deployment, sign in with an email in OPERATOR_EMAIL_ALLOWLIST, then:
  1. Go to Manage Accounts.
  2. Click Add account.
  3. Complete the Instagram permission screen.
  4. Allow profile/media access, comment access, and message access.
  5. Confirm that the account appears as connected and active.

​
10. Verify delivery

After the account is connected:
  1. Send a real test DM, comment, or story reply from another Instagram account.
  2. Confirm that the contact appears in the dashboard.
  3. Confirm that conversations, automations, and logs update.
  4. Check webhook logs if nothing appears.
A connected account means OAuth and token storage worked. It does not prove that the app-level webhook callback is correct. Always send a real event after setup.

​
Common mistakes

  • Using the Next.js app URL for Nudgra Cloud webhooks. Use the Convex site URL instead.
  • Adding the Google OAuth redirect URL in the Meta dashboard. Meta needs /api/meta/callback.
  • Forgetting to accept the Instagram tester invite from Instagram on desktop.
  • Forgetting to publish the Meta app before testing real webhook delivery.
  • Subscribing to the wrong webhook fields.
  • Setting META_VERIFY_TOKEN in one place but pasting a different token in Meta.