Skip to main content

​
Keyword Warmup

keyword_warmup is the most automation-ready public capability. It is currently:
  • implemented
  • live verified
  • allowed for unattended use

​
What It Does

Phonefarm turns one capability request into a search_warmup_session execution plan that:
  • searches one or more keywords
  • watches result videos
  • optionally likes, saves, and comments based on configured probabilities

​
Minimal Request

{
  "request_id": "warmup-2026-03-22-001",
  "capability": "keyword_warmup",
  "mode": "manual",
  "target": {
    "routing": "direct",
    "phone_id": "phone_01",
    "account_id": "account_user095916355"
  },
  "inputs": {
    "keywords": ["healthy dinner ideas", "meal prep"],
    "videos_per_keyword": 2,
    "interaction_mode": "smart",
    "comment_probability": 0
  },
  "callback": {
    "url": "https://ugc-tracker.example.com/phonefarm/process-updates",
    "metadata": {}
  },
  "requested_by": {
    "system": "ugc-tracker",
    "user": "operator@example.com",
    "metadata": {}
  }
}

​
Inputs

FieldTypeNotes
keywordsstring[]Preferred multi-keyword form.
keywordstringSingle-keyword fallback.
videosintegerSimple fixed count per session.
videos_per_keywordinteger or integer[]Number or explicit per-keyword array.
videos_minintegerOptional lower bound.
videos_maxintegerOptional upper bound.
interaction_modestringlight, smart, or engaged.
like_probabilitynumberOptional override.
save_probabilitynumberOptional override.
comment_probabilitynumberOptional override.
comment_planobjectKeyword-keyed map of comment candidates.
keyword_comment_plan_promptobjectRequired when comments are enabled and explicit comment_plan is absent.
dismiss_app_on_finishbooleanDefaults to true.

​
Interaction Modes

ModeDefault comment probability
light0.03
smart0.08
engaged0.14

​
Comment Rules

If the effective comment probability is greater than 0:
  • either provide comment_plan
  • or provide keyword_comment_plan_prompt

​
comment_plan rules

  • must be an object
  • keys must match the resolved keyword set exactly
  • each keyword bucket must contain at least one non-empty comment string
Example: 
{
  "healthy dinner ideas": [
    "this is actually useful",
    "saving this one for later"
  ],
  "meal prep": [
    "needed this reminder honestly",
    "this was way more practical than most meal prep tips"
  ]
}

​
Routing Guidance

  • Use direct for agent-like or immediate single-target execution.
  • Use queue when your control plane wants Phonefarm to materialize work later.
  • Use group for explicit multi-target fanout.

​
Failure Cases To Expect

  • duplicate keywords
  • unknown interaction mode
  • missing comment prompt when comments are enabled
  • malformed comment plan