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

# Meta / Instagram setup

> Configure Instagram Login, Meta permissions, webhooks, and account connection for Nudgra.

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.

<Warning>
  Do not guess the callback URLs. Pick the row for your distribution and paste those exact values into Meta.
</Warning>

## URL checklist

Replace the placeholder domains before you configure Meta.

<Tabs>
  <Tab title="Nudgra OSS">
    | Purpose                               | Value                                       |
    | ------------------------------------- | ------------------------------------------- |
    | App URL                               | `https://your-domain.com`                   |
    | Instagram business login redirect URL | `https://your-domain.com/api/meta/callback` |
    | Webhook callback URL                  | `https://your-domain.com/api/meta/webhooks` |
    | Verify token                          | Same value as `META_VERIFY_TOKEN` in `.env` |

    Nudgra OSS receives both OAuth callbacks and webhooks through the app server.
  </Tab>

  <Tab title="Nudgra Cloud">
    | Purpose                               | Value                                                  |
    | ------------------------------------- | ------------------------------------------------------ |
    | App URL                               | `https://your-app-domain.com`                          |
    | Convex site URL                       | `https://your-convex-site.convex.site`                 |
    | Instagram business login redirect URL | `https://your-app-domain.com/api/meta/callback`        |
    | Webhook callback URL                  | `https://your-convex-site.convex.site/meta/webhooks`   |
    | Verify token                          | Same value as `META_VERIFY_TOKEN` in Convex and Vercel |

    Nudgra Cloud receives OAuth callbacks through the Next.js app, but receives webhooks through Convex.
  </Tab>
</Tabs>

## Required permissions

Add these Instagram business permissions in the Meta app:

```text theme={null}
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

<Steps>
  <Step title="Open Meta for Developers">
    Go to:

    ```text theme={null}
    https://developers.facebook.com/apps/
    ```
  </Step>

  <Step title="Create an app">
    Click **Create App**.
  </Step>

  <Step title="Choose the Instagram use case">
    For the use case, select **Manage messaging & content on Instagram**.
  </Step>

  <Step title="Finish app creation">
    Give the app a name and finish the setup flow.
  </Step>
</Steps>

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.

<Info>
  The **Website permissions** area may not appear on mobile. Use Instagram on a computer when accepting tester invites.
</Info>

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

```text theme={null}
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:

```bash theme={null}
openssl rand -hex 32
```

Or generate one with Node:

```bash theme={null}
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

## 6. Set environment variables

<Tabs>
  <Tab title="Nudgra OSS">
    Put the Meta values in `.env`:

    ```env theme={null}
    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`:

    ```bash theme={null}
    docker compose up -d --build
    ```
  </Tab>

  <Tab title="Nudgra Cloud">
    Put the values on the Convex production deployment:

    ```bash theme={null}
    npx convex env set --prod META_APP_ID your-instagram-app-id
    npx convex env set --prod META_APP_SECRET your-instagram-app-secret
    npx convex env set --prod META_VERIFY_TOKEN your-random-webhook-verify-token
    ```

    Put the same values on the Next.js host:

    ```env theme={null}
    META_APP_ID=your-instagram-app-id
    META_APP_SECRET=your-instagram-app-secret
    META_VERIFY_TOKEN=your-random-webhook-verify-token
    ```

    Redeploy after changing hosted values:

    ```bash theme={null}
    npx convex deploy --cmd "npm run build"
    ```
  </Tab>
</Tabs>

## 7. Configure webhooks

In **API setup with Instagram login**, open **Configure webhooks**.

<Tabs>
  <Tab title="Nudgra OSS">
    Set:

    ```text theme={null}
    Callback URL:
    https://your-domain.com/api/meta/webhooks

    Verify token:
    same value as META_VERIFY_TOKEN in .env
    ```
  </Tab>

  <Tab title="Nudgra Cloud">
    Set:

    ```text theme={null}
    Callback URL:
    https://your-convex-site.convex.site/meta/webhooks

    Verify token:
    same value as META_VERIFY_TOKEN in Convex
    ```

    Do not use `https://your-app-domain.com/api/meta/webhooks` for Nudgra Cloud.
  </Tab>
</Tabs>

Subscribe to these webhook fields:

```text theme={null}
messages
messaging_postbacks
comments
```

Click **Verify and save**.

<Info>
  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.
</Info>

## 8. Configure Instagram business login

In **API setup with Instagram login**, open **Set up Instagram business login**.

<Tabs>
  <Tab title="Nudgra OSS">
    Set:

    ```text theme={null}
    Redirect URL:
    https://your-domain.com/api/meta/callback
    ```
  </Tab>

  <Tab title="Nudgra Cloud">
    Set:

    ```text theme={null}
    Redirect URL:
    https://your-app-domain.com/api/meta/callback
    ```
  </Tab>
</Tabs>

Save the redirect URL.

## 9. Connect Instagram in Nudgra

<Tabs>
  <Tab title="Nudgra OSS">
    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.
  </Tab>

  <Tab title="Nudgra Cloud">
    Open your deployment, sign in with an email in `NUDGRA_ALLOWED_EMAILS`, then:

    1. Go to **Dashboard > Account**.
    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.
  </Tab>
</Tabs>

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

<Check>
  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.
</Check>

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