Sosyabot Docs

Appearance

Connections Overview ​

A channel in Sosyabot is one connected social account. The unified store is the Accounts MongoDB collection, keyed by (workspace, social_network, pid). Posts target channels by their _id; the composer fans out across many at once.

Three connection types ​

Every supported platform falls into one of three buckets:

  1. OAuth 2.0 — the majority. Sosyabot redirects to the provider, the user grants scopes, the provider redirects back to ${BASE_URL}/api/v1/auth/<platform>/callback with an authorization code. Sosyabot exchanges the code for tokens and stores them. Login type 1.
  2. App-credentials + cookie / app-password — X (cookie connect) and Bluesky (app password). The user submits credentials directly; Sosyabot validates them server-side before persisting. Login type 2.
  3. User-supplied bot token / API key — Telegram (BotFather token), Listmonk (admin API key or basic auth). No callback, no global app credential.

Token refresh ​

A BullMQ worker (backend/src/queues/tokenRefresh.queue.ts) sweeps four platforms on a schedule and refreshes tokens that expire within 7 days:

  • Threads — default 60-day TTL.
  • Pinterest — default 30-day TTL.
  • YouTube — default 1-hour TTL (refreshed almost continuously).
  • Reddit — default 1-hour TTL with permanent refresh tokens.

The other platforms are not auto-refreshed. They either issue long-lived tokens (LinkedIn, Slack, Mastodon, Instagram, Facebook), don't use OAuth (Bluesky, Telegram, Listmonk), or rely on manual reconnect (X, TikTok).

A failed refresh emits an account.refresh_failed webhook event and marks the channel needs_reconnect. See Webhooks.

All 14 platforms ​

X (Twitter)

Instagram

Facebook

LinkedIn

TikTok

Threads

Bluesky

Mastodon

Pinterest

YouTube

Reddit

Discord

Slack

Telegram

Listmonk

OAuth callback URLs ​

Every OAuth platform mounts under ${BASE_URL}/api/v1/auth/<platform>/callback. Configure this exact URL when registering your OAuth apps with each provider. The full list is in Self-Hosting → OAuth Callback URLs.

Disconnecting ​

The connections list has a Disconnect button on every channel. Disconnecting:

  1. Deletes the Accounts record (so posts can no longer target it).
  2. Does not revoke the token on the provider — for that, the user goes to the platform's authorized-applications page (e.g. twitter.com/settings/connected_apps) and revokes Sosyabot directly.
  3. Cancels any scheduled posts that targeted only this channel; posts with multiple targets keep firing for the others.

Composer

OAuth Callback URLs

Webhooks