Sosyabot Docs

Appearance

Agents ​

An agent is an autonomous worker that drafts posts unattended at a cron-scheduled cadence. Agents output drafts in approval_status: pending_review, never publish directly — humans always sign off.

Endpoints ​

GET    /api/v1/ai-agents                  list
POST   /api/v1/ai-agents                  create — registers a cron job
GET    /api/v1/ai-agents/:id              fetch one
PATCH  /api/v1/ai-agents/:id              update — re-schedules if cron changed
DELETE /api/v1/ai-agents/:id              delete — unschedules
POST   /api/v1/ai-agents/:id/run          manual trigger (one-shot)
GET    /api/v1/ai-agents/:id/runs         past run history

Agent model ​

typescript
{
  name: string,
  role: string,                    // role/persona for the system prompt
  persona: string,                 // tone, voice
  system_prompt: string,           // explicit system prompt
  schedule_cron: string,           // 5-field cron, e.g. "0 9 * * *"
  timezone: string,                // default UTC
  accounts: ObjectId[],            // target social channels
  posts_per_run: number,           // 1–10
  daily_limit: number,             // 1–50
  active: boolean,
  posts_today: number,
  posts_today_date: Date,          // resets at midnight UTC
}

Execution ​

The ai-agents BullMQ queue runs a repeating job per agent. Each run (aiAgents.runner.ts):

  1. Loads the agent and the user's last 5 posts (for context).
  2. Checks the daily limit — if exhausted, returns 0 posts.
  3. Generates up to min(posts_per_run, daily_remaining) post drafts via the Qevron gateway (max 512 tokens per post).
  4. Persists each as a Post document with status: 0 (draft), post_by: 3 (draft), approval_status: "pending_review".
  5. Records the run in AgentRuns and increments posts_today.

Manual runs via POST /ai-agents/:id/run enqueue a one-shot job — they bypass the cron timer but respect daily_limit.

Cost ​

Not metered per call. Agents create drafts; the underlying text generation uses the workspace's general AI capacity, not a per-call credit debit.

Prompts

Drafts

Composer Overview