Skip to main content

Provider Integrations

Soku integrates with 8 social media platforms. Each provider follows a consistent pattern: OAuth authentication, token storage in Firestore, and platform-specific publishing logic.

Supported Platforms​

PlatformOAuth FlowToken RefreshPublishPollingMetrics
FacebookFB Login (OAuth 2.0)Long-lived tokensPages feed-Scheduled
InstagramFB Login (Business Account)Via FacebookContainer + PublishScheduledScheduled (via FB)
ThreadsMeta OAuthVia MetaText/image posts-Scheduled
X (Twitter)OAuth 2.0 PKCE + OAuth 1.0aRefresh tokenTweet APIScheduled-
TikTokOAuth 2.0Refresh sweepDirect publish (video/photo)ScheduledScheduled
YouTubeGoogle OAuth 2.0Refresh sweepVideo uploadScheduled-
LinkedInOAuth 2.0N/AUGC Posts API--
SnapchatOAuth 2.0Refresh sweepSnap post--

Integration Architecture​

OAuth Flow (all platforms)​

Every provider follows this pattern:

  1. Auth start — Client calls *AuthStart with Authorization: Bearer <idToken>. The function saves a random state to oauthStates/{state} with { uid, provider, returnTo } and returns the provider's OAuth URL.
  2. User consent — User authorizes on the provider's OAuth page.
  3. Callback — Provider redirects to *AuthCallback with code and state. The function exchanges the code for tokens, stores them in users/{uid}/integrations/{platform}/accounts/{accountId}, deletes the oauthStates doc, and redirects to returnTo.

Token Storage​

All tokens are stored in Firestore under users/{uid}/integrations/{platform}/accounts/{accountId}:

  • accessToken — Current access token
  • refreshToken — Refresh token (if provided by platform)
  • expiresAt — Token expiration timestamp
  • displayName, username, avatarUrl — Profile metadata
  • enabled_for_repost, can_be_source — Automation flags
  • poll_cursor — Last seen post ID/time for polling
  • Provider-specific fields (e.g., pageAccessToken for Facebook, openId for TikTok)

Token Refresh​

Platforms with expiring tokens use refresh mechanisms:

  • Sweep functions (*RefreshSweep) run on schedules and refresh tokens nearing expiry
  • On-demand refresh (*RefreshNow) refreshes a specific account's token
  • Publish-time refresh — Publisher functions check token freshness before API calls

Multi-Account Support​

Each platform supports multiple connected accounts:

  • Accounts are stored as subcollections: integrations/{platform}/accounts/{accountId}
  • defaultAccountId on the parent doc determines the default account
  • connectedCount tracks total connected accounts
  • API requests must specify accountId when multiple accounts exist

Per-Platform Details​

Facebook​

  • Auth: FB Login OAuth 2.0 → long-lived user token
  • Publishing: Pages feed posting via Graph API
  • Functions: fbAuthStart, fbAuthCallback, publishFacebook
  • Metrics: fbMetricsCollector, scheduledFacebookMetrics
  • Triggers: onFacebookAccountCreated (setup on new connection)

Instagram​

  • Auth: FB Login with Instagram Business Account mapping via Facebook Page
  • Publishing: Image/video container creation + publish (Graph API)
  • Polling: pollInstagram, pollerInstagram, scheduledInstagramPoll — detects new organic posts
  • Functions: igAuthStart, igAuthCallback, publishInstagram
  • Webhooks: igDataDeletion, igDeauth — Meta compliance callbacks
  • Triggers: onInstagramAccountCreated

Threads​

  • Auth: Meta OAuth 2.0
  • Publishing: Text and image posts
  • Functions: thAuthStart, thAuthCallback, publishThreads
  • Metrics: thMetricsCollector, scheduledThreadsMetrics, thInsightsTest

X (Twitter)​

  • Auth: OAuth 2.0 PKCE (xAuthStart, xAuthCallback) + OAuth 1.0a for v1.1 media endpoints (xAuth1Start, xAuth1Callback)
  • Publishing: Tweet creation via v2 API
  • Polling: pollX, pollerX, scheduledXPoll
  • Functions: publishX
  • Triggers: onXAccountCreated

TikTok​

  • Auth: OAuth 2.0 with client key/secret
  • Publishing: Direct publish for video and photo with status polling
  • Token refresh: ttRefreshNow, ttRefreshSweep
  • Polling: pollTiktok, pollerTiktok, scheduledTikTokPoll
  • Metrics: ttMetricsCollector, scheduledTikTokMetrics
  • Functions: ttAuthStart, ttAuthCallback, publishTiktok, ttCreatorInfo
  • Triggers: onTiktokAccountCreated
  • Special: Desktop auth flow via ?desktop=1 parameter; verification file serving

YouTube​

  • Auth: Google OAuth 2.0 with offline access
  • Publishing: Video upload via YouTube Data API v3
  • Token refresh: ytRefreshNow, ytRefreshSweep
  • Polling: pollYoutube, pollerYoutube, scheduledYouTubePoll
  • Functions: ytAuthStart, ytAuthCallback, publishYoutube, fetchYouTubeCaptions

LinkedIn​

  • Auth: OAuth 2.0
  • Publishing: UGC Posts API for text and media posts
  • Functions: liAuthStart, liAuthCallback, publishLinkedin
  • Triggers: onLinkedinAccountCreated

Snapchat​

  • Auth: OAuth 2.0
  • Publishing: Snap post creation
  • Token refresh: snapRefreshNow, snapRefreshSweep
  • Functions: snapAuthStart, snapAuthCallback, snapPost

Cross-Platform Functions​

FunctionPurpose
onOrganicPostCreatedFirestore trigger on organicPosts/* — initiates repost workflows
onIntegrationAccountAvatarChangeHosts integration avatars on Firebase Storage
onAccountDeletedCleans up workflows when an account is disconnected
onWorkflowWritten / onWorkflowDeletedSyncs workflow source account metadata
integrationsHealthSweepScheduled check of all integration connection health

Frontend Integration​

The web app interacts with integrations through:

  • useConnectIntegration hook — Calls startAuth(platform, idToken, returnTo, isLocal) to initiate OAuth
  • IntegrationsContext — Provides connected account data to all components
  • Platform picker — Reads users/{uid}/integrations/* to display connected accounts with profile info
  • Publish hooks — Call platform-specific publish endpoints with the user's ID token