Connecting Facebook also automatically connects a linked Instagram Business account if one is associated with your Facebook Page. Both accounts share the same OAuth flow and are disconnected together.
How the Facebook OAuth flow works
Initiate the connection
Hayon’s backend (
GET /api/platform/facebook/connect) builds a Facebook OAuth URL targeting https://www.facebook.com/v24.0/dialog/oauth with the required scopes and your Hayon user ID in the state parameter. The URL is returned to the frontend.Authorize on Facebook
You are redirected to Facebook’s authorization dialog. Review the requested permissions (listed below) and click Continue as [your name].
Callback
Facebook redirects back to
GET /api/platform/facebook/callback with a one-time authorization code and your user ID in state.Short-lived token exchange
Hayon exchanges the code for a short-lived user access token via
GET https://graph.facebook.com/v24.0/oauth/access_token.Long-lived token exchange
Hayon immediately exchanges the short-lived token for a long-lived token (valid ~60 days) using the
fb_exchange_token grant type.Page token retrieval
Hayon calls
GET /me/accounts with the long-lived token to retrieve your Facebook Pages. It selects the first Page and stores that Page’s own access token (Page tokens do not expire as long as the user token they were generated from remains valid).Instagram Business account check
Hayon queries the Page for a linked
instagram_business_account. If one exists, the Instagram account is also connected and stored alongside the Facebook connection.Required permissions (OAuth scopes)
Hayon requests the following Facebook permissions during the OAuth flow:| Scope | Purpose |
|---|---|
public_profile | Read your name and profile picture |
pages_show_list | List the Facebook Pages you manage |
pages_read_engagement | Read engagement data on Pages |
pages_manage_posts | Publish and manage posts on Pages |
pages_manage_metadata | Read Page metadata |
business_management | Access business accounts |
instagram_basic | Access basic Instagram profile data |
instagram_content_publish | Publish content to Instagram |
instagram_manage_insights | Read Instagram analytics |
Connecting a Facebook Page
The connection always targets a Facebook Page, not your personal profile. Requirements:- You must be an admin of at least one Facebook Page.
- The Page must not be restricted by Meta’s policies.
- For Instagram connection, the Instagram account must be a Business or Creator account linked to the Facebook Page in your Meta Business Suite.
Hayon connects to the first Page returned by
GET /me/accounts. If you manage multiple Pages and want a different Page connected, ensure the intended Page appears first in your Facebook account, or disconnect and reconnect after reordering.What Hayon stores
| Field | Description |
|---|---|
platformId | Page ID (or user ID if no Page found) |
auth.accessToken | Page access token |
auth.expiresAt | Approximately 60 days from connection time |
profile.displayName | Page name |
profile.handle | Page username (if set) |
profile.avatar | Page profile picture URL |
Instagram (if linked)
| Field | Description |
|---|---|
platformId | Instagram Business account ID |
auth.accessToken | Long-lived user access token |
linkedPageId | ID of the associated Facebook Page |
businessId | Instagram Business account ID |
profile.handle | Instagram username |
profile.displayName | Instagram display name |
Supported post types
| Content type | Supported |
|---|---|
| Text-only posts | Yes |
| Photo posts (single image) | Yes |
| Photo posts (multiple images) | Yes |
| Link posts (URL with preview) | Yes |
| Video posts | No |
| Stories | No |
| Reels | No |
| Events | No |
Media requirements
- Image formats: JPEG, PNG, GIF (static), WebP.
- Maximum image size: 4 MB for photos published via the Graph API.
- Maximum images per post: Up to 10 images in a multi-photo post.
- Aspect ratio: Facebook recommends 1.91:1 for link images and 1:1 for standard photos.
- Video: Video publishing is not currently implemented in Hayon’s Facebook integration.
Token expiry and refresh
Facebook long-lived tokens expire after approximately 60 days if not refreshed. Hayon stores the expiry timestamp inauth.expiresAt. When the health status shows expired or needsReconnection: true, you need to disconnect and reconnect your Facebook account.
To manually refresh profile data while the token is still valid:
Disconnecting
To disconnect Facebook (and the linked Instagram account), navigate to Settings > Connected accounts and click Disconnect next to Facebook, or call:connected: false for both.
To fully revoke Hayon’s access on Meta’s side, visit https://www.facebook.com/settings?tab=applications and remove the Hayon app.
Troubleshooting
No Facebook Pages found
No Facebook Pages found
If you have no Pages or are not an admin on any Page, Hayon falls back to storing your personal user profile (with
platformId set to your Facebook user ID). Publishing to personal profiles is restricted by Meta — you need a Page.Instagram not connected after Facebook OAuth
Instagram not connected after Facebook OAuth
Instagram is only connected if your Facebook Page has a linked Instagram Business or Creator account. Go to your Facebook Page settings and link your Instagram account under Linked accounts, then disconnect and reconnect Facebook in Hayon.
Facebook session expired
Facebook session expired
Long-lived tokens are valid for ~60 days. After expiry, the health status shows
expired. Disconnect and reconnect to obtain a new token.Permissions not granted during OAuth
Permissions not granted during OAuth
If you did not grant all requested permissions during the Facebook authorization dialog, some features may not work. Disconnect and reconnect, granting all permissions when prompted.