Core Concepts
Sosyabot revolves around a small set of nouns. Once these click, the rest of the docs read fast.
Workspace
The workspace is the top-level tenant. It owns billing, channels, members, posts, AI credits, and feature toggles. A user may belong to many workspaces; the workspace switcher (top-left in /app) chooses which one is "current."
A new account gets one default workspace at sign-up time, configured for the Turkish market: currency TRY, locale tr, FREE plan with a 3-day trial. Change any of these from Team & Workspace.
Roles inside a workspace are owner, admin, editor, and viewer. See Roles & Permissions.
Channel
A channel (sometimes called an account in older UI) is one connected social profile — one X handle, one Instagram business account, one Discord server, etc. Each channel has its own:
- Provider (
x,instagram,bluesky,telegram, …) - Auth state (OAuth token + refresh token, or app password, or bot token)
- Timezone (used by the composer when scheduling)
- Watermark and caption defaults
Background workers refresh tokens before they expire for Threads, Pinterest, YouTube, and Reddit; failed refreshes mark the channel needs_reconnect. See Connections Overview.
Post
A post is the unit of publication. It carries:
- A list of target channels (the same body fans out to many).
- A body (
caption), atype(text,image,video,mixed),media[]references to the Files Library, andlabels[]. - A
category(profile,reel,story, etc. — platform-dependent). - A
post_byvalue (0publish now,3schedule for a future time) andtime_posts[](one timestamp per channel — they may differ when channels are in different timezones).
Lifecycle states: draft → scheduled → queued → sent (or failed). A post in failed state can be retried from the composer; the failure reason from the platform API is surfaced inline.
Schedule
A schedule is a future moment pinned to a channel and to that channel's timezone. Single-shot schedules are just a timestamp. Recurring schedules use rrule syntax, the same iCalendar standard your calendar app uses.
The composer's Find slot button proposes the next free slot based on the channel's existing queue and the workspace's quiet hours.
Campaign
A campaign groups related posts. Use it for product launches, content series, weekly digests, or ad-driven moments. Campaign-level analytics roll up impressions, engagement, and short-link clicks across every member post — see Campaign Performance.
Label
A label is a free-form tag applied to posts. Filter the publishing list, analytics, and API queries by label. Labels are workspace-scoped and admins can pre-seed a brand palette so teammates don't invent ten variants of "tutorial."
Agent
An agent is an autonomous AI worker running on a cadence — hourly, daily, or weekly. Configure the prompt, the channel set, the cadence, and (optionally) the source signal (RSS feed, last-N-posts, custom query) and the agent enqueues posts unattended via the aiAgents.queue.ts BullMQ worker.
Agents debit AI credits on every run, exactly like manual prompt invocations.
Credit
The credit is the AI usage unit. Image generation, video generation, prompt runs, and inline assistance all spend credits. Each model in the Models registry carries a per-call multiplier that the admin sets. Quotas refresh on the workspace's billing cycle; track consumption at Credits.
Role
A role is a permission bundle. The four roles cover the common access patterns:
- Owner — billing, plan, all admin features.
- Admin — workspace settings, users, integrations.
- Editor — compose, schedule, run AI.
- Viewer — read-only.
Tenant scoping is enforced at the API layer so role checks can't be bypassed by a hand-crafted request. See Roles & Permissions.
Token / API key
Two flavours of programmatic credentials:
- Personal API token — generated under Account → API Tokens. Bearer header. Carries the issuer's role.
- Webhook signing secret — issued when you register a webhook. Sosyabot signs every outbound request with HMAC-SHA256; you verify on your end. See Webhooks.
Both are workspace-scoped and revocable.