Herald/Documentation
← All documentation
Owner setup

Owner Guide — Register Herald's Meta (Instagram) App

Audience: Herald owner/developer (you), one time. Registers the single Meta app Herald uses for all tenants. Path chosen: Instagram API with Instagram Login — the customer connects their Instagram Business/Creator account directly, no Facebook Page required. (This is simpler and current; it relaxes the old "must link a FB Page" rule.) Good news: you can do a real end-to-end connect with your OWN Instagram account today, with no App Review, by adding yourself as an Instagram Tester while the app is in Development Mode.

Every step marked ⚠️VERIFY is one where Meta's console wording changes often — do it live and tell me what you actually see; I'll adjust the connector to match.

Prerequisites

  • A Facebook account (to access the Meta developer console).
  • Your Instagram account switched to Business or Creator (Instagram app → Settings → Account type and tools → Switch to professional account). You already have this.

Steps

  1. Create the app

    • Go to https://developers.facebook.com/apps → Create app.
    • Use case / type: choose Business (⚠️VERIFY — Meta sometimes shows a "use case" picker; pick the one that lets you add the Instagram product / "Instagram API setup with Instagram login").
    • Name it e.g. Herald (this name shows on the customer consent screen — keep it recognizable).

  2. Add the Instagram product (Instagram Login)

    • In the app dashboard, add product Instagram → "API setup with Instagram login".
    • This section shows an Instagram App ID and Instagram App Secret — copy these, and paste them into Herald in step 6 (stored encrypted — never in a file, never in env).
    • ⚠️ Critical: use the Instagram App ID, NOT the Meta/Facebook App ID shown at the top of the dashboard. They are different numbers. If you use the Meta App ID, connecting fails with "Invalid Request: … Invalid platform app" at the Instagram consent step.

  3. Register Herald's redirect URI

    • In the Instagram-login setup section, find "Business login settings" → Valid OAuth Redirect URIs (⚠️VERIFY exact label).
    • Add this exact URL: https://herald.leiritech.com/api/oauth/instagram/callback (This is Herald's live deployment. If you later put Herald on your own domain, use https://<your-domain>/api/oauth/instagram/callback instead.)
    • Also add the domain (herald.leiritech.com) to App Domains if prompted.
    • Meta requires HTTPS and an exact string match — copy it verbatim. Railway serves a valid cert, so the .up.railway.app URL is accepted.

  4. Add yourself as an Instagram Tester (this is what lets you test with no App Review)

    • App dashboard → Roles → Roles → Instagram Testers → Add Instagram Testers → enter your Instagram username → send invite.
    • On instagram.com (or the app): Profile → Edit Profile → Apps and Websites → Tester Invites → Accept.
    • Keep the app in Development Mode (default). Your tester account now works for the full real OAuth + publish flow.

  5. Note the scopes (Herald requests these in the authorize URL; you don't set them here beyond enabling the product):

    • instagram_business_basic, instagram_business_content_publish (⚠️VERIFY these exact names appear in the app's permission list — Meta renamed them Jan 2025).

  6. Put the credentials into Herald (in the UI, encrypted)

    • Open Herald: https://herald.leiritech.com → log in → Settings → Platform apps.
    • Under Instagram, paste the Instagram App ID (Client ID) and Instagram App Secret, then Save. The card flips to "Configured ✓". The secret is encrypted at rest and never shown again.

Then connect

  • Accounts → Connect Instagram → complete the consent → your account shows Connected.
  • If a network isn't configured yet, Connect shows a clear "set it up in Settings" message instead of an error.

Also: enable Facebook Page publishing (optional, same Meta app)

Herald can also publish to a Facebook Page (a separate connector from Instagram). To enable it on this same Meta app:

  1. Add the Facebook Login product to the app.
  2. Register the redirect URI https://<your-herald-domain>/api/oauth/facebook/callback.
  3. In Herald → Settings → Platform apps → Facebook Page, paste the Meta App ID + App Secret (the top-level Facebook app credentials — not the Instagram App ID). Customers then use Accounts → Connect Facebook Page.

Later (for real multi-tenant production, NOT needed to test now)

Publishing for customers' accounts (not added as testers) needs Advanced Access → App Review + Business Verification (~weeks). Start Business Verification early. For now, Development Mode + your tester account is enough to prove the whole flow works.