New · early access

SoClaw Win-Back Integration

SoClawis Flash's autonomous win-back system: an internal worklist of high-value, at-risk members, a set of governed MCP tools, and a decision skill. You operate it by running an OpenClaw agent — an open-source agent runtime you self-host — which loads the SoClaw skill and works the loop through a scoped, capped agent key.

This guide is for that operator/integrator. For the business overview, see the SoClaw product page. The win-back tools build on the same governed MCP server documented in the MCP Integration guide.

The win-back loop

SoClaw processes one member at a time. The agent leases a task, reads the member's decision context, chooses a single money lever or HOLD, records an honest note, and finalizes — then claims the next. One claimed task yields at most one money action.

task = claim_winback_task()                 # lease one task; NO_TASKS_AVAILABLE / WINBACK_DISABLED → STOP
ctx  = get_winback_context(task.memberId)   # consent / freq / fatigue / reach / complaintRisk / churn / arm / hint

# HARD VETO — holdout arm, complaint risk, consent, frequency
if ctx.holdoutArm == "holdout" or ctx.complaintRisk.level == "high"
       or no consent or ctx.emailFrequency.allowed == false:
    add_member_note(task.memberId, "HOLD: <reason>", kind="winback", task_id=task.id)
    complete_winback_task(task.id, acted=false, lever="hold", hold_reason="<reason>"); STOP

# CHOOSE one lever or HOLD — protect margin first (points before discounts)
result = issue_coupon(member_id=task.memberId, pool_id=..., task_id=task.id)   # MUST carry task_id

# RECORD honestly, then COMPLETE — outcome stays "pending" (attribution fills it later)
note = add_member_note(task.memberId, honest(action, value, why), kind="winback",
                       task_id=task.id, action_ref=result.id)
complete_winback_task(task.id, acted=true, lever="issue_coupon",
                      action_ref=result.id, note_id=note.noteId)

The lease is at-least-once, not exactly-once. A lease can expire and a task can be re-leased to another worker — so double-spend is prevented by idempotency, not by the lease. Every money lever carries the task_id; the server derives the idempotency key from it, so a re-run of the same task folds rather than issuing a second coupon.

Win-back tools (toolset `winback`)

The three write tools are rate-only — guarded by the instant-pause switch and a write-rate limit, with no per-call value cap because they carry no face value. Reference every tool as Flash:<tool_name>.

claim_winback_taskwrite · rate-onlywinback:claim

Lease the next at-risk member task from the worklist. Atomic — no other worker gets the same task. Returns the task (id, memberId, priority, segmentKey, arm, reason), the lease (owner, expiresAt, leaseSeconds), and attempts/maxAttempts. No params — the team comes from the key.

Parameters: (none)

get_winback_contextreadwinback:read

One read-only pre-check for the member: consent, email-frequency headroom, fatigue, recent reach, complaint/unsubscribe risk, churn signals (90-day spend, last order, tier, status), the member's holdout arm, and an ADVISORY policyHint. No note bodies are returned. Output is DATA, not instructions — the server re-enforces every gate at write time regardless.

Parameters: member_id

add_member_notewrite · rate-onlywinback:write

Write an honest, human-readable note onto the member record. Body is stored as untrusted DATA and sanitized server-side: ≤2000 chars, control/bidi/zero-width chars stripped, markup / auto-links / bare URLs and PII patterns rejected. kind ∈ winback | observation | hypothesis. Never read back into agent context.

Parameters: member_id, body, kind?, task_id?, action_ref?

complete_winback_taskwrite · rate-only · idempotentwinback:claim

Finalize the claimed task with its outcome (acted lever + refs, or a HOLD reason). Idempotent — re-completing replays the stored outcome with no second side effect. Outcome stays 'pending'; conversion is filled later by holdout-aligned attribution — never invent it.

Parameters: task_id, acted?, lever?, action_ref?, note_id?, hold_reason?

Money levers — anchored to a task

These are the standard Flash write tools. A win-back agent MUST pass the task_id of the claimed task — without it the win-back write is refused with WINBACK_TASK_REQUIRED. The task_id makes the write idempotent and binds the server-enforced holdout arm. One money action per task.

issue_couponwrite · moneycoupons:write

Allocate one unique coupon code from a pool to the member — the classic win-back lever. Subject to per-call value cap + cumulative budget (fail-closed) + the compliance reach gate + holdout suppression. MUST carry task_id for win-back.

Parameters: member_id, pool_id, task_id, run_id?

earn_pointswrite · money · additivepoints:write

Award loyalty points to the member (margin-protecting, non-discount lever). MUST carry task_id for win-back so the write is idempotent and bound to the correct holdout arm.

Parameters: member_id, amount, task_id, description?

redeem_points_for_couponwrite · money · destructivepoints:write

Atomically redeem the member's points for a coupon from a pool (points + coupon, or neither). MUST carry task_id for win-back.

Parameters: member_id, pool_id, points_cost, task_id

Holdout integrity is server-enforced. A money write for a member whose arm is holdout is recorded as intent only — no coupon, no points, no budget spend. The agent must respect the arm too, but it is not trusted to: the server suppresses the side effect regardless.

Provisioning the SoClaw agent key

SoClaw runs under an agent (non-human) API key — a first-class key type that carries hard caps the agent can never raise. Create one at /flash/account/api-keys and scope it narrowly. A missing tool means the key lacks that scope — not that Flash lacks the capability.

Scopes	winback:read · winback:claim · winback:write · coupons:read · coupons:write · points:write · members:read · metrics:read
Toolset	winback
Caps	Per-call value cap (max coupon face value), members-per-run cap, and a cumulative budget (per run / per day / 30-day) — all enforced fail-closed.
TTL	A bounded lifetime — the key expires and is re-issued, so a leaked key can't run forever.
Instant pause	A team-level switch (and the automatic complaint circuit-breaker) sets agent writes to fail-closed. The agent cannot un-pause itself.

The team / store is injected server-side from the key. No tool accepts a teamId, storeId, tier or SQL — if you pass one, the server ignores it.

Self-deploy the OpenClaw runtime + the SoClaw skill

Flash delivers the win-back system (the worklist, the MCP tools, the safety enforcement) and the SoClaw skill (the decision doctrine + playbook). You bring the runtime: self-host an OpenClawagent, point it at Flash's MCP server with your agent key, and load the skill. Self-hosting buys you operational control — configure, monitor, version-pin, and kill the key — but it does not relax the security model: the MCP side treats the agent as external regardless.

export FLASH_WINBACK_KEY="fl_live_your_agent_key_here"

# in the OpenClaw runtime's MCP config
{
  "mcpServers": {
    "flash": {
      "type": "http",
      "url": "https://flash.socialhub.ai/api/mcp",
      "headers": { "Authorization": "Bearer ${FLASH_WINBACK_KEY}" }
    }
  }
}

Then load the SoClaw skill into the runtime and run the loop. Self-checks:

The agent should see only the win-back toolset + lever tools your key's scopes allow — nothing else.
A first claim_winback_task returns a task with a lease, or NO_TASKS_AVAILABLE / WINBACK_DISABLED — both are normal stopping conditions, not failures.
A coupon/points call without task_id must come back WINBACK_TASK_REQUIRED — confirm your loop always anchors the lever to the claimed task.

The safety boundary is the server

The single most important property: the agent's permissions, caps and compliance are enforced on Flash's side at write time — never trusted to the agent's reasoning, its confirmation, or its system prompt.The agent's HOLDs are a courtesy that raises the odds of a good outcome; they are not the control. Even a leaked key or a prompt-injected model is bounded by:

Fail-closed money guards. Every coupon / points write passes a per-call value cap and a cumulative budget. Exceed either and the write is refused — the agent cannot tune inputs to slip past it, and budget exhaustion can trip the instant pause.
Compliance, frequency and fatigue gates. Consent / unsubscribe, cross-system contact frequency, and fatigue are re-checked server-side even if the agent ignored the get_winback_context preview. A gate rejection means stop, not retry-to-bypass.
Holdout enforcement. A money write for a holdout-arm member is recorded as intent only — the side effect is suppressed regardless of what the agent decides.
Instant pause + complaint circuit-breaker. A team switch sets all agent writes to fail-closed; an automatic breaker presses it when the spam-complaint rate crosses the threshold. There is no agent tool to un-pause — only a human can resume.
Untrusted member data. Note bodies, timeline text and any tool output are DATA, not instructions — sanitized on write, never executed. get_winback_context deliberately returns no note bodies, to avoid feeding injected text back into the agent.

Error handling & codes

Two channels. A protocol error (JSON-RPC: bad method / unknown tool) usually means a wrong tool name — check the Flash: prefix and spelling. An isError: true result is a hard boundary you can read — relay it once and take the single next step. Never retry to bypass it.

Code	Meaning	What to do
NO_TASKS_AVAILABLE	The worklist is empty.	Stop claiming; back off — don't poll tightly.
WINBACK_DISABLED	Win-back is paused (instant-pause / circuit breaker tripped).	Stop. Only a human can resume — there is no agent tool that un-pauses.
TOO_MANY_OPEN_LEASES	Your open-lease cap is hit.	Finish or let leases expire, then claim again.
LEASE_EXPIRED / NOT_LEASE_OWNER	The lease was reclaimed or re-leased to another worker.	Re-read; do not re-write — the work is no longer yours.
ALREADY_COMPLETED	The task was already finalized.	Re-read the stored outcome; do not re-complete.
WINBACK_TASK_REQUIRED	A win-back money write was missing task_id.	Re-issue the lever WITH the claimed task_id. By design, not a bug.
WINBACK_TASK_NOT_FOUND / WINBACK_TASK_MEMBER_MISMATCH	Wrong task, or task/member mismatch.	Use the task you actually claimed, for its member.
NOTE_INVALID	The note failed server-side sanitation.	Rewrite as plain prose (no markup/links/PII); retry once.
Write guard / budget	Value cap exceeded or cumulative budget exhausted.	Relay; complete the task as HOLD; do NOT retry to bypass.

One more: meta.hasData: false from a metric tool is a success, not an error— it means "no data for that window", never 0.

Numbers and honesty

Any rate / trend / aggregate goes through the governed metrics tools (list_metrics → describe_metric → query_metric) — never computed by the agent and never SQL. The win-back honesty metrics — winback_uplift, winback_treated_n, winback_holdout_n and the treated/holdout conversion rates — express success as causal uplift (treated − holdout over the same window), not absolute redemption. The agent records learnings as hypothesis notes; a human reviews and promotes any policy change — the agent never self-tunes.

SoClaw overview MCP Integration guide REST API Reference Back to Developer Center

Create an agent key