SalesAI Social Account Connection Guide Version: 2026-03-05 (Updated) This file is written in simple words for non-technical users. ============================================================ A) Quick Answer: Scheduled Posting Support (Current Code) ============================================================ Platforms in SalesAI: Facebook, LinkedIn, Instagram, Twitter/X, YouTube Native scheduling API support: - Facebook: YES (implemented in backend) - LinkedIn: NO native scheduling in this integration - Instagram: NO native scheduling in this integration - Twitter/X: NO native scheduling in this integration - YouTube: NO native scheduling in this integration What works right now on the SalesAI page: - Facebook schedules using Facebook native API. - LinkedIn, Instagram, Twitter/X, YouTube schedule using SalesAI queue (delayed publish at selected time). - So practically, scheduling can be used for all 5 platforms in SalesAI. - Compose Post supports public image URLs (including public Google Drive image links). - YouTube video posting supports public video URLs (including public Google Drive video links). Facebook schedule limits in current code: - Must be at least 10 minutes in the future. - Must be within 75 days. ============================================================ B) What Each Field Means in SalesAI ============================================================ - Platform: Which social app you are connecting. - Account Name: The name/handle you want to see in SalesAI. - Access Token: Main token used to post. - Access Token Secret: Used only in legacy Twitter/X OAuth1 media setup. - Refresh Token: Used to refresh expired access tokens (platform-specific). - Client ID / Client Secret: App credentials (mainly for token refresh flows). - Consumer Key / Consumer Secret: Used only in legacy Twitter/X OAuth1 media setup. - Platform Account ID: - Facebook: Page ID - LinkedIn: Author URN (example: urn:li:person:...) - Instagram: IG User ID - Twitter/X: optional in current flow - YouTube: Channel ID (auto-filled by OAuth flow) ============================================================ C) Facebook (OAuth Connect) ============================================================ Official links: - Apps: https://developers.facebook.com/apps/ - Access tokens: https://developers.facebook.com/docs/facebook-login/guides/access-tokens - Graph API Explorer: https://developers.facebook.com/tools/explorer/ - Page posting docs: https://developers.facebook.com/docs/pages-api/posts/ What to fill in SalesAI: - Platform: Facebook - Click: Continue with Facebook - Approve page permissions - SalesAI will store Page ID + Page Access Token automatically Simple steps: 1. Open Meta Developer portal and keep app credentials on backend env. 2. In SalesAI, choose Facebook and click Continue with Facebook. 3. Approve requested permissions for your Pages. 4. SalesAI auto-creates connected Facebook page account(s). 5. For scheduling, select any connected Facebook page account. ============================================================ D) LinkedIn ============================================================ Official links: - LinkedIn apps: https://www.linkedin.com/developers/apps - OAuth flow: https://learn.microsoft.com/en-us/linkedin/shared/authentication/authorization-code-flow - Refresh tokens: https://learn.microsoft.com/en-us/linkedin/shared/authentication/programmatic-refresh-tokens - Posting docs: https://learn.microsoft.com/en-us/linkedin/compliance/integrations/shares/ugc-post-api Important: - LinkedIn native schedule API is NOT implemented here. - But SalesAI scheduling is available (queue-based delayed publish). What to fill in SalesAI: - Platform: LinkedIn - Account Name: your profile/company name - Access Token: required - Refresh Token: required for auto-refresh - Client ID + Client Secret: required for refresh flow - Platform Account ID: author URN (person/company URN) Very important: - Reconnect with scope `offline_access` to get refresh token. ============================================================ E) Instagram ============================================================ Official links: - Main docs: https://developers.facebook.com/docs/instagram-platform - Instagram API with Instagram Login: https://www.postman.com/meta/instagram/documentation/6yqw8pt/instagram-api-with-instagram-login - Instagram publishing: https://developers.facebook.com/docs/instagram-platform/content-publishing Important: - Instagram native schedule API is NOT implemented here. - But SalesAI scheduling is available (queue-based delayed publish). - Instagram feed posting requires an image in current code. - Instagram connect is OAuth-based in SalesAI (no manual token paste needed for normal users). - Manual Instagram account creation from API/UI is disabled; use OAuth connect only. Before adding Instagram account (normal user checklist): 1) Your Instagram must be Professional: - Business account or Creator account. - Personal Instagram accounts cannot publish through this API flow. 2) Keep login ready for the same Instagram account you want to connect. 3) If your company app is in Development mode, ask your admin to add your account as tester/developer first. 4) Click Continue with Instagram and finish Allow once. - Do not refresh or go back on callback page during connect. 5) After connect, for publishing: - add image (Instagram feed post requires image in SalesAI). What to do in SalesAI: - Platform: Instagram - Click: Continue with Instagram - Approve permissions - SalesAI stores Instagram user ID + token automatically Requirements: - Instagram professional account (Business or Creator) is required for publish API. - Personal Instagram accounts are not supported for API publishing. - Required scopes for posting: instagram_business_basic + instagram_business_content_publish. - Optional scopes (if you also need moderation/messaging): instagram_business_manage_comments + instagram_business_manage_messages. - App-side credentials/settings are managed by your SalesAI admin team. Why app comes in the middle (Meta platform rule): - Instagram API publishing always runs through a Meta App. - In Development mode, only app roles/testers can use publish API. - For "any user can connect and post", app must be Live + approved in App Review. - Instagram Login flow itself does not require linking a Facebook Page. Meta setup checklist (must match exactly): 1. In Meta app, enable "Instagram API with Instagram Login". 2. Add exact redirect URL: https://salesai.jain.software/api/social/oauth/instagram/callback 3. In Instagram API -> Business Login settings, set: Deauthorize callback URL: https://salesai.jain.software/api/social/instagram/deauthorize Data deletion request URL: https://salesai.jain.software/api/social/instagram/data-deletion 4. Ensure scopes are enabled in app: instagram_business_basic instagram_business_content_publish instagram_business_manage_comments instagram_business_manage_messages 5. If app is in Development mode, add the same Instagram account as tester/developer and accept the invite. 6. Reconnect Instagram in SalesAI after any permission/app-mode change. 7. Backend switch: - `INSTAGRAM_ENABLE_FB_LOGIN=0` -> direct Instagram login. - `INSTAGRAM_ENABLE_FB_LOGIN=1` -> Facebook login flow for Instagram accounts. ============================================================ F) Twitter / X ============================================================ Official links: - Developer portal: https://developer.x.com/en/portal/dashboard - Projects and apps: https://developer.x.com/en/portal/projects-and-apps - OAuth docs: https://developer.x.com/en/docs/authentication/oauth-2-0/authorization-code Important: - Twitter/X native schedule API is NOT implemented here. - But SalesAI scheduling is available (queue-based delayed publish). - Twitter/X connect is OAuth-based in SalesAI (no manual token pasting in Connect modal). What to do in SalesAI: - Platform: Twitter - Click: Continue with Twitter/X - Approve requested permissions - SalesAI stores account ID + tokens automatically Backend env needed: - TWITTER_CLIENT_ID (required) - TWITTER_REDIRECT_URI (required if custom; default is /api/social/oauth/twitter/callback) - TWITTER_CLIENT_SECRET (recommended) Note: - For OAuth-login Twitter accounts, text publishing works directly. - Image upload currently needs legacy OAuth1 media credentials (access token secret + consumer key/secret). ============================================================ G) YouTube (OAuth + Video URL) ============================================================ Official links: - Google Cloud Console: https://console.cloud.google.com/ - YouTube Data API: https://developers.google.com/youtube/v3 - OAuth scopes: https://developers.google.com/identity/protocols/oauth2/scopes Important: - YouTube account connect is OAuth-based (no manual token paste in UI). - In compose post, provide a public video URL. - Google Drive share links are supported (SalesAI converts to a downloadable link). - Local video upload from browser/server storage is intentionally avoided in this flow. What to fill in SalesAI: - Platform: YouTube - Click: Continue with YouTube - Approve permissions - Then in compose post: - Caption (optional; first line used as YouTube title) - Video URL (required for publish/schedule) ============================================================ H) Character Limits (Current SalesAI UI) ============================================================ - Twitter/X: 280 - Instagram: 2200 - LinkedIn: 3000 - YouTube: 5000 - Facebook: 63206 ============================================================ I) Common Errors and Easy Fixes ============================================================ 1) "Access token missing" - For OAuth-connected accounts, reconnect the platform. - Manual credential edit is only for advanced troubleshooting. 2) "LinkedIn token refresh failed / invalid_grant" - Reconnect LinkedIn with `offline_access`. - Save new Refresh Token + Client ID + Client Secret. 3) "No connected account found" - Make sure account status is ON/Connected. - Select the correct connected account in compose form. 4) "Instagram publish requires an image" - Add an image. Text-only Instagram feed posts are not supported here. 5) "Scheduled post failed" - If Facebook: make sure time is 10+ minutes ahead and within 75 days. - For LinkedIn/Instagram/Twitter-X/YouTube: make sure queue worker is running, token is valid, and selected time is correct. 6) "YouTube publish requires video_url" - Add a public direct video URL in compose form. - If using Google Drive, ensure file is shared publicly. 7) "Instagram media creation failed: Unsupported request - method type: post" - This is usually a Meta capability/access issue, not a caption/image format issue. - Check: Professional account type, required scopes, app mode (Live vs Development), tester assignment, and reconnect. - If your account requires Page/PPA under Meta rules, complete that setup too. ============================================================ J) Security Note ============================================================ - Treat tokens like passwords. - Do not share tokens in chat/email. - If you suspect leakage, revoke token and reconnect. End of file.