[gitpascal]

Closes #1716.

Summary

Adds support for Meta's Instagram API with Unified Login to the existing instagram-direct integration while preserving the current direct Instagram OAuth flow.

The flow is selected per platform credential:

• with unifiedLoginConfigId: use Meta Unified Login;
• without it: retain the existing instagram.com/oauth/authorize behavior.

What changed

• add an optional Unified Login Configuration ID to Instagram platform credentials;
• generate the Unified Login URL with client_id, config_id, response_type=code, and override_default_response_type=true;
• exchange the code through the Graph API and resolve client_business_id;
• paginate assigned_instagram_accounts and expose all returned accounts in the existing account-selection flow;
• store the Unified business access token and selected Instagram professional account ID;
• route messaging, profile, attachment, comment, media, sync, and webhook calls through the correct Graph host/account ID;
• subscribe Unified-compatible webhook fields;
• keep legacy refresh-token behavior only for direct Instagram login;
• add no database migration: the credential and auth metadata fields are optional.

Compatibility

The existing direct Instagram login remains the default when no Unified Login Configuration ID is set. Existing credentials and connected channels keep their previous code path.

Validation

• Instagram integration: 30 files / 134 tests passed
• Database credential tests: 19 passed
• Instagram integration TypeScript check
• Database package TypeScript check
• Builder TypeScript check
• Unified OAuth URL, token exchange, account pagination/selection, Graph routing, webhook fields, and fallback behavior covered by tests
• Live Meta OAuth smoke test against a production-mode Unified Login app

I am opening this as a draft until the live OAuth callback, account selection, webhook subscription, and first message are verified end to end.

Meta references

• https://developers.facebook.com/documentation/instagram-platform/instagram-api-with-unified-login/get-started
• https://developers.facebook.com/documentation/instagram-platform/instagram-api-with-unified-login/business-login

[sung17]

Thanks for the detailed issue and for putting this together. Gating the new flow behind an optional unifiedLoginConfigId, with no migration, is the right approach. We'd like to merge it once a few things are addressed:

1. The legacy flow changes after all (multiAccount: false → true)
integrations/instagram/src/integration.ts now sets multiAccount: true for every Instagram connection, including the direct flow. In apps/builder/src/app/integrations/[...integration]/callback.ts (around line 368), a non-multi-account provider finishes the connect automatically for API/MCP callers. With this change, an agent connecting a legacy Instagram channel has to make an extra targets call it doesn't make today. AI agents are the primary users of the connect API, so we need the legacy path to behave exactly as before. Could you either keep auto-completion when there is exactly one selectable candidate, or limit multi-account selection to the Unified flow?

2. Hardcoded UI label
"Unified Login Configuration ID" in instagram-settings.tsx needs to go through useTranslations(), with the key added to every file under apps/builder/messages/.

3. Unrelated version changes

• The form default changes from v25.0 to v27.0. Please revert it or move it to a separate PR.
• exchangeUnifiedCodeForToken and getUnifiedInstagramAccounts hardcode "v22.0". Please use DEFAULT_API_VERSION from src/constants.ts.

4. Token type assumption
refreshAuth returns Unified auth unchanged, which assumes the code exchange always returns a non-expiring Business Integration System User token. If the Login for Business configuration is set to User access token, the token will expire and the channel will stop working without any visible error. Could you either detect the token type at exchange time (for example with debug_token) and fail clearly or handle refresh, or document that the configuration must use a system-user token? A short admin note on creating the config_id would help either way.

5. Things only a live test can confirm
These look reasonable but are assumptions until the smoke test runs:

• Webhook routing uses entry.id. Does it match the id returned by me/assigned_instagram_accounts, which is now stored as igId/pageId? If they differ, inbound messages won't find the channel.
• /{ig-id}/messages, /{ig-id}/messenger_profile, conversation sync and subscribed_apps (sent as query params) on graph.facebook.com with this token.

Please share the results of the end-to-end test (OAuth → account selection → webhook subscription → inbound message → reply → history sync) once you've run it.

6. Docs
The new credential field should be reflected in the CLI/MCP docs and the Instagram setup docs.

Happy to help test once these are in. Thanks again!