# Optional Instagram Follow-to-DM: buyer and AI-agent setup guide

Updated September 30, 2026. Read this before configuring direct Meta access.

## What this release does

Settings → Instagram Follow-to-DM → Optional setup stores a workspace's Meta app ID, professional account ID, app secret, and hashed webhook verification token. Owners/admins can save, pause diagnostics, rotate credentials, or disconnect. Public queries never return the secrets.

The Convex endpoint supports Meta callback verification and HMAC-SHA256 validation of Instagram follow webhook payloads. It records only the latest receipt timestamp for a matching account; no follower identifiers, message content or raw payloads are persisted. A signed dashboard sample may also update this timestamp. It is NOT evidence of live eligibility.

**This release does not send welcome DMs, subscribe an account automatically, obtain Meta access, or expose a publishable new-follower automation trigger.** The restricted outbound contract is not established. Do not tell a buyer that saving credentials activates the feature.

## 1. Obtain the restricted capability first

You need a professional Instagram account, a Meta developer app you control, and explicit Meta access for BOTH:

1. The Instagram `follow` webhook subscription.
2. The initial welcome DM to someone who has not previously messaged you.

Meta's webhook reference documents the event, but its public permission matrix does not currently explain general access. Ordinary messaging permission, business verification, Advanced Access, or a Meta partner badge does not by itself prove this capability. Zernio does not currently document this trigger either.

Use the developer support channel available to your Meta app/business to request eligibility instructions. There is no confirmed self-service enrollment path or promised approval timeline. Ask:

> Can this app subscribe to Instagram's follow webhook and send an initial Follow-to-DM welcome message? Please provide the approved login flow, permissions, app/account eligibility, Graph API version, account subscription request, send endpoint/payload, recipient ID type, limits, and messaging-window rules.

If `follow` is unavailable or access is denied, stop this setup. Do not replace it with a message trigger and label it new-follower automation. A follow-status lookup is not a follower event.

## 2. Prepare the buyer-owned Meta app

1. Create/select your app at https://developers.facebook.com/apps/ and add Instagram API with Instagram Login, unless Meta's restricted program instructs you to use another flow.
2. Configure your business details, privacy-policy and data-deletion requirements, OAuth redirect URIs and eligible professional account according to that flow's current setup guide.
3. For an app serving client businesses, complete the applicable business verification, Advanced Access and App Review process. Provide the requested reviewer instructions and end-to-end screencast. Owned-account development access is not proof of client-account production access.
4. Standard Instagram Login messaging uses `instagram_business_basic` and `instagram_business_manage_messages`. Follow Meta's separate restricted-feature instructions; do not invent a `follow` permission name or assume these standard scopes suffice.
5. Record the Meta app ID and Instagram professional account ID. The Instagram ID here is NOT the Zernio connection ID, profile ID, username, Facebook Page ID, or a follower ID. Get it using the account lookup for your approved login/token flow.

Use a separate app/callback per independently operated workspace where practical. Reusing an app may share its app-level webhook configuration; ensure your existing integrations are not overwritten. This setup provides a workspace-specific callback, not an app-wide multi-workspace dispatcher.

## 3. Configure Hyperchat

1. Install/update this source normally. Deploy the new Convex schema/functions to YOUR Hyperchat deployment before using the new Settings UI. Never reuse DevLaunch's backend or another buyer's credentials.
2. Confirm `NEXT_PUBLIC_CONVEX_SITE_URL` points to your deployment's HTTPS `.convex.site` origin. Rebuild/restart the frontend if it changes. Do not paste the `.convex.cloud` API origin or localhost into Meta's callback field.
3. Sign in as workspace owner/admin. Open Settings → Instagram Follow-to-DM → Optional setup.
4. Enter your app ID, Instagram professional account ID, and Meta app secret (from your app settings).
5. Generate a random verification token, for example `node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"`. Save it in your password manager and paste it into the masked token field. This token is not a Meta access token.
6. Select Receive diagnostic webhooks and Save Meta setup. Copy the displayed callback URL.

App secrets remain server-side in Convex. Only a hash of the verification token is stored. Do not put secrets in `NEXT_PUBLIC_*`, source control, screenshots, support tickets, or agent prompts. Leaving saved secret fields blank preserves them. Changing the app/account requires re-entering both secrets and resets diagnostic evidence.

## 4. Verify and subscribe in Meta

1. In your Meta app's Instagram webhook configuration, enter Hyperchat's callback URL and the SAME verification token.
2. Verify/save. Hyperchat accepts `hub.mode=subscribe`, checks `hub.verify_token`, and responds with the plain-text `hub.challenge`. Settings will show Callback verified.
3. Subscribe to `follow` only if Meta exposes it to your app. Subscribe the professional account as directed by Meta for the approved login flow. App-level field selection and account-level subscription are separate requirements.
4. Do not copy a subscription command from a different login flow: host, token type, permissions and account IDs must match. There is deliberately no speculative `subscribed_fields=follow` command here.
5. Test callback transport using Meta's dashboard; then have a separate eligible test account follow. Confirm the receipt time matches the real action. A synthetic test alone does not establish eligibility.

POST requests must include Meta's `X-Hub-Signature-256` HMAC over the unmodified body using the app secret. Only `object: instagram`, entries whose `id` equals the configured Instagram account, and `changes[].field: follow` with `value.from.id` are recorded. Unknown fields are acknowledged without starting anything. Invalid signatures are rejected. Diagnostics never open a DM window or create an automation run.

## 5. Instructions for the implementing AI agent

Preserve buyer customizations. Inspect existing code, take a backup/branch, and merge narrowly. Current integration files:

- `convex/metaFollow.ts`: admin settings, verification and signed receipt diagnostics.
- `convex/schema.ts`: `metaFollowConfig` table, isolated by workspace.
- `convex/http.ts`: GET/POST `/webhooks/meta-follow/{workspaceId}`.
- `src/components/meta-follow-settings.tsx`: optional setup UI and instructions.
- `tests/meta-follow.spec.ts`: isolation, secrets, callback and signature tests.

Do not implement a sender until the buyer supplies Meta's approved contract. Do not guess message tags, permissions, Graph hosts or beta endpoints. Do not collect an unused access token in this release.

When the contract is available:

1. Implement server-side token storage/renewal and verify the token belongs to the configured app/account. Keep IDs for direct Meta separate from Zernio IDs.
2. Persist/deduplicate follower events per account and follower according to Meta's documented repeat/refollow rules. Record freshness and cancellation state. Do not message historical followers when enabling.
3. Add a disabled-by-default trigger and explicit activation only after verifying subscription, account eligibility and the welcome-send capability.
4. Bind the immutable published workflow to its sending account; enforce workspace authorization, recipient opt-out, human takeover, eligibility, rate limits and permitted welcome content at dispatch.
5. Use durable Convex jobs. Hold ambiguous sends for reconciliation; do not blindly retry a timeout/5xx that may have delivered.
6. Integrate inbound replies and conversation ownership. Establish Meta's permitted reply window from qualifying interaction, not from the follow event. Verify coexistence with Zernio and other inbox apps; prevent duplicate replies.
7. Require real end-to-end acceptance before calling the feature ready: new follow → signed event → accepted welcome DM → recipient reply → correct Hyperchat conversation. Test private/unsupported accounts, refollows, duplicates, revoked access, disconnect and opt-out too.

## Troubleshooting and removal

- Callback verification fails: check diagnostics enabled, exact token, `.convex.site` URL, deployed HTTP routes and selected workspace.
- Signed POST rejected: check the app secret and raw-body signature. Never disable signature checking to fix delivery.
- Callback verifies but no event arrives: verify app and account subscriptions, matching account ID and Meta eligibility. Verification alone doesn't grant `follow` access.
- Event appears but no DM: expected in this release; the welcome sender is not implemented.
- To pause intake, uncheck Receive diagnostic webhooks and save. Requests will be rejected while paused, so also remove the subscription in Meta if you want to stop retries.
- Disconnect Meta setup removes its stored configuration/secrets. Remove the subscription in Meta separately; Hyperchat does not alter Meta app configuration. Your Zernio connection is unaffected.

## Official references

- Webhook schema: https://developers.facebook.com/docs/graph-api/webhooks/reference/instagram/
- Webhook setup: https://developers.facebook.com/documentation/instagram-platform/webhooks
- Field permissions: https://developers.facebook.com/documentation/instagram-platform/webhooks/fields
- App Review: https://developers.facebook.com/documentation/instagram-platform/app-review
- Standard Send API (prior-message requirement): https://www.postman.com/meta/instagram/folder/uxudqu0/send-api
- Zernio webhook capabilities: https://docs.zernio.com/webhooks

Provider documentation changes. Recheck the restricted contract at implementation time; this guide cannot grant Meta access.