Documentation

What this Hub is

The Social Hub is an instance-licensed command center for developer marketing and community support. You sign in with a Parrot Integrated account. This machine then:

1. Broadcasts one set of notes across live social adapters. AI formats each network.
2. Ingests inbound mentions, drafts grounded replies, and either auto-posts or parks them in a Human-in-the-Loop (HITL) inbox.
3. Optionally runs Premium automations (ROI, post analytics, client-ready reports, audit log, crisis, campaigns, A/B variants, client workspaces, out-of-band alerts, evergreen, competitor watch). Each module toggle defaults off.

Workspace data (encrypted credentials, drafts, local knowledge store, wallet) stays on this Hub. Your master account and subscription stay on the Parrot portal.

Sign-in and access

1. Open the Hub. With no session you see Log In / Sign up.
2. After a successful handshake the Hub stores the session on this instance.
3. Gate must grant Hub access via the Social add-on. Without it you stay on the paywall: signed in, dispatch locked.
4. Log out clears the session here. It does not delete integrations.

Base ecosystem tiers (Sandbox, Mimic, Apex, Enterprise) do not unlock this Hub by themselves.

Command center

Home after unlock: broadcast counts, inbound/HITL volume, rate-limit health, credit wallet, premium toggles, competitor pane, master composer, and a HITL snapshot.

Master composer

1. Pick a persona (default DevRel). Staging generates copy and stamps UTM but never posts.
2. Paste notes.
3. Optional URL Preview (does not post).
4. Optional public media URL, or insert a shelf item from the asset library.
5. Generate & dispatch. AI formats a package; live adapters post in parallel. One network failing does not cancel the rest. Landing links pick up workspace UTM when that policy is on.
6. Or pick a time and Schedule. Copy is generated immediately; review or edit it on /calendar before it posts.
7. On Premium, with A/B variants on in Account settings: Generate A/B produces two cuts (two credit hits). Post A, post B, or schedule them to different calendar times. Canonical UTM then adds utm_content=a or utm_content=b. Campaigns stay one-cut. This Hub does not pick a winner or count clicks. Reviewer seats cannot generate A/B.
8. On Premium, with Client workspaces on in Account settings: the header switcher isolates tokens, calendar, assets, personas, inbox, and RAG per client (cap 5, including Default). Login, wallet, kill switch, and the reviewer seat stay shared. Reviewer cards are labeled by workspace; they cannot switch. If Premium lapses, the Hub stays on Default.
9. On Premium, with Out-of-band alerts on: HITL, crisis (alert/critical), credits paused, kill switch on, and calendar fire failed can ping your Slack webhook, Discord webhook, or SMTP. Destinations are instance-wide and encrypted. 30-minute cooldown per event per workspace. Not SMS, PagerDuty, or per-client webhooks.
10. On Premium, with Client-ready reports on: download a 30-day CSV or PDF for the active workspace from Post performance or Account settings. Successful posts, inbound, stored metrics, and the heat-grid. Missing metrics stay not_available. Not ROI, not email, not the JSON backup. Reviewers cannot download.
11. On Premium, with Audit log on: /audit lists HITL, kill switch, module toggles, workspaces, emergency direct, campaign generate, integrations (name only, including Post/Listen/Report), alert saves, and report/backup downloads. Actor is operator or reviewer:<label>. No secrets. 90 days / 3,000 rows. Reviewers cannot open it.

Live adapters today: Discord, Reddit, X, LinkedIn, Facebook, Instagram, Threads, WhatsApp, Messenger, Telegram, Bluesky, Mastodon, Pinterest, YouTube, TikTok, Snapchat, Twitch, Skool, Product Hunt, GitHub. LinkedIn, Skool, and Snapchat are broadcast-only (no inbound). Catalog expansions (WordPress, Slack, Farcaster, etc.) store credentials and return ready until a live adapter ships.

Asset library

Standard includes a shelf of public image/video URLs, text snippets, and UTM templates on /assets. Insert them from the composer or a calendar slot. This Hub stores bookmarks and copy only — it does not host uploaded files. UTM templates stamp params onto a URL when you insert them; workspace Canonical UTM in Account settings fills any still-missing params on outbound posts.

Kill switch

Header Active / Paused. Paused blocks outbound dispatch (broadcasts, replies, direct posts). Inbound sync and URL preview still run.

Posting windows

Account settings can set one IANA timezone and optional days/start/end per Live or Broadcast-only network. Unset networks stay 24/7. Calendar Beat holds a due slot until every targeted live network is in-window — the slot stays scheduled. Generate & dispatch, calendar Post now, emergency direct post, and campaign HITL posts that actually dispatch skip quiet networks and log quiet_hours unless you check Post anyway. Inbound auto-replies and HITL conversation replies are not gated. The kill switch still outranks windows.

Canonical UTM

Account settings can enable workspace UTM defaults. When on, outbound landing http/https links get missing utm_source (per network), utm_medium (default social), and optional utm_campaign. Params already on a URL are kept. Media URLs and inbound replies are never stamped. Composer A/B posts also get utm_content=a or utm_content=b when this policy is on. This is query-string attribution only — the Hub does not shorten links or count clicks.

Staging persona

Composer includes a Staging persona. Generate & dispatch and calendar fire still produce copy, stamp workspace UTM, and write history with dry_run — live adapters are not called. Emergency direct post is live unless you check Dry run on that form. Inbound auto-replies, HITL conversation replies, and campaign HITL posts that dispatch stay live. Staging is not A/B testing and not a mock network. Kill switch still pauses outbound.

Reviewer seat

Premium Account settings can create one invite URL. The reviewer’s browser gets a cookie and the HITL inbox only: edit, approve, reject, skip. Approving a campaign card that is allowed to post still posts. Composer, calendar, emergency direct, integrations, kill switch, wipe, and campaign generate stay operator-only. The invite is not a ParrotGate user and is not emailed by the Hub. If Premium lapses or the operator revokes the seat, the cookie fails closed. Approvals from that seat store source_meta.approved_by as reviewer:<label>. With Audit log on, the same action also lands on /audit. Reviewers cannot open that page.

Hub credits

• Wallet allotment is 25,000 credits per period on Basic and 50,000 on Premium.
• AI generation, drafting, and analysis draw down that wallet balance.
• Auto-refill is off by default. When on, an empty wallet can refill via ATM cash-out from your central balance.
• If the wallet hits zero and auto-refill is off, AI work pauses until the next allotment or a refill.

Inbox and inbound

Inbox is a unified stream of every inbound row, not only HITL. Filter by status, kind, and platform. HITL cards stay at the top. Approve, reject, or skip (including swipe) applies only to HITL items; other statuses are history.

Open HITL cards to approve, reject, or skip drafts. You can edit a reply before approve. Swipe right to approve, left to reject. On Premium, a reviewer seat can do the same from an invite URL without operator tools.

Cap: 3 auto-replies per author per platform per 24 hours. Beat polls connected listen networks every five minutes; Sync still runs on demand. Kill switch pauses outbound replies only — ingest and drafts continue, parked in HITL until you resume.

Catalog stubs do not listen. Each platform console states whether that network listens, uses a webhook, or is outbound only.

Integrations

The Integrations page is opt-in. You will not see 27 cards on first visit.

1. Add integration — pick a network. A credential card appears. The dropdown marks each network Live, Broadcast-only, or Stub.
2. Save credentials. Secrets are encrypted on this instance. Connected means the required keys are present; it is not the same as Live.
3. Post / Listen / Report on the card are per workspace. Defaults on when that direction is implemented. Disabled means this Hub cannot do that direction yet (stubs, or LinkedIn/Skool listen). Post off skips composer/calendar/campaign send. Listen off skips inbound poll/webhooks into Inbox. Report off omits the network from Performance By network and client CSV/PDF. Kill switch still pauses every Post.
4. Disconnect deletes that card and its stored secrets.
5. The Platforms nav lists only networks you added, with the same capability label.

You can still add a catalog expansion and store credentials. Dispatch returns {"status":"ready"} until a live outbound adapter ships — never a fake success. Instagram feed posts require a public image URL. Threads supports text plus an optional public image URL. Bluesky posts text (≤300 characters) or a public image URL via handle + app password. Mastodon posts text (≤500 on this Hub) or a public image URL via instance URL + access token. Pinterest creates Pins from a public image URL to a board (OAuth access token; Standard app access needed for write). WhatsApp, Messenger, and Telegram send free-form chat messages to a recipient chat ID. YouTube and TikTok uploads require a public video URL (TikTok also needs a verified URL domain in the developer console). Snapchat Public Profile posts Stories / Spotlights / Saved Stories from a public image or video URL (app must be allowlisted by Snap). Twitch sends Helix chat messages or creates a live clip. Publishing expansions include Ghost, DEV, Hashnode, WordPress, and Webflow; messaging adds LINE and Slack; video adds Vimeo and Kick; decentralized adds Farcaster and Nostr; audio adds SoundCloud.

Campaigns and Premium toggles

Two different checkbox groups. Top-right Premium toggles opt into automations (default off). Platform checkboxes pick which networks to draft. Each target is labeled Live, Broadcast-only, or Stub. Checking a stub does not post until a live adapter exists.

On Basic, those toggles open an upsell. On Premium they are real on/off switches.

Optional publish time on /campaigns uses the posting-windows timezone. Approve then places one calendar slot per live network (quiet hours, kill switch, UTM, and Staging dry-run apply when it fires). Skip HITL is only for a future time — there is no immediate post-without-review. Evergreen still never auto-posts.

Account, logout, delete

Account settings: log out clears the Parrot Integrated session on this Hub. Integrations stay until you disconnect or delete. Download workspace saves a JSON backup of the active client: drafts, history, post metrics, A/B drafts, assets, calendar, inbox, competitors, posting windows, UTM policy, reviewer seat label, and the integration list — not tokens, webhook secrets, API keys, the Fernet key, wallet internals, or the knowledge store. The file can contain community names and inbound message text; treat it as confidential. This Hub cannot import it. Delete Account (type DELETE) wipes this instance’s workspace data and logs out. It does not cancel the master subscription — manage billing at portal.polycracker.dev.