📖 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
| Variable | Description |
|---|---|
TIKTOK_CLIENT_KEY | TikTok Creator app client key |
TIKTOK_CLIENT_SECRET | TikTok Creator app secret |
TIKTOK_SANDBOX_MODE | Set true to force SELF_ONLY privacy (required for unaudited apps) |
TIKTOK_BUSINESS_APP_ID | TikTok Business API app ID |
GEMINI_API_KEY | Google Gemini API key |
GCP_KEY_BASE64 | Base64 Vertex AI service account JSON (for Vertex fallback) |
PAYPAL_CLIENT_ID / SECRET | PayPal API credentials |
PAYPAL_MODE | sandbox or live |
DB_HOST/NAME/USER/PASS/PORT | PostgreSQL connection |
❓ FAQ
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.API Endpoints (Developer Reference)
All endpoints require an active session. CSRF token must be sent in the request body as csrf_token.
Creator
| Endpoint | Method |
|---|---|
/api/upload_video | POST multipart |
/api/publish_direct | POST JSON |
/api/publish_now/:id | POST JSON |
/api/schedule_post | POST JSON |
/api/generate_caption | POST JSON |
/api/generate_viral_ideas | POST JSON |
/api/ai_weekly_plan | POST JSON |
/api/analyze_video | POST JSON |
/api/create_order | POST JSON |
/api/capture_order | POST JSON |
/api/export_logs | GET |
/apply_coupon | POST form |
Business
| Endpoint | Method |
|---|---|
/api/biz/create_campaign | POST form |
/api/biz/toggle_campaign | POST form |
/api/biz/create_creative | POST form |
/api/biz/upload_creative | POST multipart |
/api/biz/ai_optimize_campaign | POST JSON |
/api/biz/generate_inspiration | POST JSON |
/api/biz/analyze_audience | POST JSON |
/api/biz/analyze_video | POST JSON |
/api/biz/generate_ad_copy | POST JSON |
/api/biz/generate_report | POST JSON |
/api/biz/reply_comment | POST JSON |