📖 SocialConductor Documentation

What is SocialConductor?

SocialConductor is an AI-powered TikTok management platform with two modes: Creator (auto-reply to comments, schedule/publish videos, generate viral content ideas) and Business (manage TikTok ad campaigns, creatives, audiences, and AI optimization). Both modes use Google Gemini AI under the hood.

🎬 Creator Features
AI Auto-Reply

The system polls your TikTok videos for new comments every 10 minutes. When a comment is found, Gemini AI generates a contextual reply using your System Prompt. Replies are either posted live (when Auto-Reply is ON) or saved as simulations for you to review. To enable: Settings → Enable Auto-Reply + Enable Comment Replies.

Simulation Mode: Replies are generated but never posted — useful for testing tone and quality before going live.

Spam filtering: If the AI outputs exactly NO_REPLY, the comment is flagged as spam/toxic and skipped.

System Prompt

The System Prompt is the core instruction that tells the AI how to behave. Write it in first person as if you're describing your own voice. Example: "Reply as Jade, a bubbly fitness creator. Be encouraging, use TikTok slang, max 30 words per reply. Output NO_REPLY for spam."

Click ✨ Magic Generate to have AI write one from your channel name automatically.

Video Studio

Publish videos to TikTok in two ways: paste a direct MP4 URL (TikTok fetches it via PULL_FROM_URL) or upload a file (stored in your media library, sent via FILE_UPLOAD API). You can schedule posts for a future date/time or publish immediately.

Note for sandbox/unaudited apps: Your TikTok account must be set to Private (TikTok App → Settings → Privacy → Private Account) and TIKTOK_SANDBOX_MODE=true must be set. All posts will appear as private-only.

AI Caption: Enter a description of your video and Gemini will generate a TikTok-optimised title and hashtag set.

Content Calendar

Plan your upcoming content as "ideas" with target dates. Set status to Idea → Drafted → Scheduled → Published as the piece moves through your workflow. Does not automatically schedule posts — use Video Studio for that.

Viral Vault

Click Generate 5 Viral Ideas, enter your niche, and Gemini produces hooks, captions, and hashtag sets scored by predicted virality. Save ideas you like — they stay in the vault until used. Copy any idea into Video Studio with one click.

Scheduling

In AI Settings → Scheduling, define the days of the week and time window when the AI is allowed to reply. Replies outside this window are held and sent at the next available slot. Timezone-aware.

Plans & Billing (Creator)

Plans control how many AI replies are generated per day: Free (5), Basic (30), Enhanced (60), Enterprise (120), Unlimited. Plans are purchased monthly via PayPal in Settings → Subscription Plans. Bonus Credits are purchased separately and are consumed after your daily plan limit is reached — they never expire. Redeem coupon codes in Settings → Redeem Coupon.

💼 Business Features
Campaign Hierarchy

TikTok Ads are structured in three tiers: Campaign (objective + total budget) → Ad Group (targeting, bidding, placement) → Creative (the actual image/video + ad copy). You must create them in this order.

AI Optimizer

Go to AI Optimizer and click Analyse Campaign. Gemini reviews your campaign metrics (impressions, clicks, spend, ROAS) and returns 3–5 specific recommendations. Click Apply to mark a recommendation as actioned — this is for your records only, it does not automatically change the campaign in TikTok.

Ad Inspiration

Enter a product/niche (e.g. "organic skincare for Gen Z") and optionally a target audience. Gemini generates ad concepts with a hook, caption, and hashtags. Click Use Template to copy the copy into your Creatives workflow.

Audience Segments

Create Custom, Lookalike, or Interest-based audience segments. These are stored locally for planning purposes. Click Analyse on any segment to get AI insight on its potential reach and content approach.

Ad Comments

View comments on your running ads. Click AI Generate Reply to get a brand-voice reply from Gemini. Review the text, edit if needed, then click Post Reply to publish it.

Reports

Generate AI-written campaign performance summaries. Specify a campaign and date range, and Gemini writes a plain-English report covering highlights, issues, and next steps.

⚙️ Setup & Technical
Environment Variables
VariableDescription
TIKTOK_CLIENT_KEYTikTok Creator app client key
TIKTOK_CLIENT_SECRETTikTok Creator app secret
TIKTOK_SANDBOX_MODESet true to force SELF_ONLY privacy (required for unaudited apps)
TIKTOK_BUSINESS_APP_IDTikTok Business API app ID
GEMINI_API_KEYGoogle Gemini API key
GCP_KEY_BASE64Base64 Vertex AI service account JSON (for Vertex fallback)
PAYPAL_CLIENT_ID / SECRETPayPal API credentials
PAYPAL_MODEsandbox or live
DB_HOST/NAME/USER/PASS/PORTPostgreSQL connection
❓ FAQ

Check: (1) Auto-Reply is ON in Settings; (2) Comment Replies is ON; (3) Simulation Mode is OFF if you want live posts; (4) your TikTok OAuth token is valid — try logging out and back in; (5) your daily limit hasn't been reached (check Analytics).

Until TikTok approves your app, you can only post to private accounts. Set TIKTOK_SANDBOX_MODE=true in your .env, and set your TikTok account to Private in the TikTok app (Settings → Privacy → Private Account). Posts will appear in your private feed.

Go to AI Settings (Creator) or Business Settings. In the right column Quick Links panel, click the Hints toggle button.

Your Plan limit resets every 24 hours. Bonus Credits are a permanent reserve used only after your daily plan limit is exhausted. Credits never expire and roll over month to month.

You need at least one Campaign created under your business account. Go to Campaigns → + New Campaign, create a campaign, then come back to Optimizer.
API Endpoints (Developer Reference)

All endpoints require an active session. CSRF token must be sent in the request body as csrf_token.

Creator
EndpointMethod
/api/upload_videoPOST multipart
/api/publish_directPOST JSON
/api/publish_now/:idPOST JSON
/api/schedule_postPOST JSON
/api/generate_captionPOST JSON
/api/generate_viral_ideasPOST JSON
/api/ai_weekly_planPOST JSON
/api/analyze_videoPOST JSON
/api/create_orderPOST JSON
/api/capture_orderPOST JSON
/api/export_logsGET
/apply_couponPOST form
Business
EndpointMethod
/api/biz/create_campaignPOST form
/api/biz/toggle_campaignPOST form
/api/biz/create_creativePOST form
/api/biz/upload_creativePOST multipart
/api/biz/ai_optimize_campaignPOST JSON
/api/biz/generate_inspirationPOST JSON
/api/biz/analyze_audiencePOST JSON
/api/biz/analyze_videoPOST JSON
/api/biz/generate_ad_copyPOST JSON
/api/biz/generate_reportPOST JSON
/api/biz/reply_commentPOST JSON