Connect an Instagram Professional account using Meta Unified Login.
An installation administrator first configures the Meta OAuth application and Business Login configuration. Connecting an Instagram channel requires an Instagram Professional account (Business or Creator) managed through a Meta Business Portfolio. Personal Instagram profiles cannot publish through the Meta Graph API.
For your own eligible business accounts, Meta's Standard Access and app-role requirements differ from the Advanced Access required to connect external businesses. See Meta setup and review boundaries before starting an App Review process. Postdot does not require every self-hosted operator to obtain external-business access.
Prerequisites
Before connecting in Postdot, confirm your Meta asset hierarchy in Meta Business Suite:
- Business Portfolio: A Meta Business account that owns or manages your application and Instagram assets.
- Instagram Professional Account: The target profile must be converted to a Business or Creator account.
A Facebook Page is not required by Unified Login. The account must be shared with the application through its business portfolio.
Configure the application
Operators configure the Meta Developer application and Postdot deployment:
Create the Meta Developer application
Create an app in the Meta for Developers portal:
- Select Manage messaging & content on Instagram as the use case.
- Associate the app with your business portfolio.
Configure Facebook Login for Business (Unified Login)
Meta requires newly created applications to use Facebook Login for Business with the Unified Login template:
- Navigate to Facebook Login for Business -> Configurations.
- Create or edit a configuration using the Instagram API (Unified Login) template.
- Under Assets, select Instagram accounts (deselect Ad accounts if not needed).
- Under Permissions, include:
instagram_basicinstagram_content_publishinstagram_manage_messages
- Use the template's System-user access token. Check its expiration in the configuration preview. Postdot preserves a verified non-expiring token without assigning a deadline; expiring Unified tokens require reconnection when they expire.
- Note the generated Configuration ID (numeric identifier).
Register the OAuth callback
Under Facebook Login for Business -> Settings, add your deployment's callback to Valid OAuth Redirect URIs and save the changes:
https://postdot.example/api/oauth/instagram/callbackReplace postdot.example with your public Postdot API origin. Use a public HTTPS callback.
Set Postdot environment and OAuth application
- Add the configuration ID to your Postdot API environment:
POSTDOT_INSTAGRAM_CONFIG_ID=your_meta_configuration_id - In Postdot's OAuth applications in the administration settings,
register the Instagram application:
- Client ID: Your Meta App ID.
- Client secret: Your Meta App Secret.
- Set the application to Active and mark it as default if desired.
Connect the channel
- Open Channels in Studio and select Instagram.
- Click Connect account. You will be redirected to the Meta Business Login flow.
- Log in with your Meta credentials, select your Business Portfolio, and choose the Instagram Professional account to connect.
- When returned to Postdot, verify the account username and ID shown on the channel card.
Publishing and media requirements
Instagram requires an image file for feed publishing:
- Format: exactly one JPEG, up to 8,000,000 bytes.
- Media accessibility: Uploaded media must be served over a publicly accessible HTTPS URL so Meta's servers can retrieve the media container during publishing.
- Captions: Standard text captions are delivered with the image.
If authorization or delivery fails
- App mode and permissions: When the Meta app is in Development mode, only users listed under App Roles (Administrators, Developers, or Testers) can authorize the application.
- No Instagram accounts found: Ensure the account is Professional, belongs to the selected business portfolio and was shared with the app during consent.
- Expired tokens: If access is revoked or token expiration occurs, reconnect the channel from Studio. Retrying a failed send without reconnecting will not renew credentials.
If Meta's API setup with Unified login screen fails to load, use Facebook Login for Business -> Templates to create the Unified Login configuration, then Settings to register the callback. A successful setup still needs a complete authorization and publication check.
Privacy and data requests
Read Application data and privacy for the information held by a self-hosted instance and Delete application data for disconnection, content removal and requests to its operator. Operators must publish their own policy and contact procedure for the instance covered by their Meta application.