MetaBuyer Workflow

MetaBuyer is an operational Meta Ads monitoring and guarded execution workflow. It is not primarily an "app testing" feature.

Current behavior documented as of February 25, 2026.

Slack approvals do not execute writes automatically. Operators must run execution commands manually with explicit confirmation.

What MetaBuyer Actually Does

• Polls Meta Ads insights/metadata across campaign, ad set, and ad levels
• Builds deterministic recommendations (CPA/ROAS/CTR/frequency/spend-spike logic)
• Publishes performance reports and approval queues to Slack
• Supports guarded execution for pause/budget actions with manual confirmation
• Maintains action logs and rollback windows (72h default)
• Can seed sandbox campaigns/ad sets/ads for controlled testing

Operational Cycle

Load connected `meta_ads` runtime credentials and pull insights + metadata.
Generate recommendations and alerts from configured thresholds.
Build an execution plan preview (including which actions require approval).
Post performance report + approval queue to Slack when reporting is enabled.
Ingest approval decisions from Slack thread replies (`APPROVE`, `REJECT`, `CLEAR`).
Execute approved actions only when an operator runs `execute-actions` with `--confirm sandbox|live`.
Refresh state, append logs, and allow rollback inside the rollback window.

Default loop interval is 6 hours (`intervalSeconds: 21600`) unless overridden in config.

Execution Scope and Limits

Current write operations are intentionally narrow and guardrailed:

• `set_status` (typically pauses campaign/ad set on high-risk signals)
• `update_daily_budget` (controlled up/down adjustments)

Non-goals in the current release:

• No auto-execution from Slack approvals
• No destructive deletes
• No targeting-change automation
• Writes are limited to status changes and daily budget updates

Meta App Setup (Onboarding)

Create a Meta Business app and add the Marketing API product.
Create/select a System User in Business Settings, assign the ad account, and grant asset access.
Generate an access token (recommended: system user token) with required permissions:

• ads_read
• ads_management
• business_management
• pages_show_list
• pages_read_engagement

In z0, connect Settings → Integrations → Meta Ads using:

• Access Token: required (recommended: system user token)
• Ad Account ID: required (numeric or act_123...)
• Business ID: optional
• Facebook Page ID: optional (recommended for sandbox ad/creative creation)
• Instagram Actor ID: optional
• App ID: optional
• Token Mode: optional (set to system_user when applicable)

Validation checklist:

• Run /metabuyer doctor and confirm meta_api_read and meta_permissions.
• Run /metabuyer verify-use-cases (optionally with --page-id ...) to probe required endpoints.
• If sandbox creative/ad creation warns about development mode, switch the Meta app to live/public.

Meta Ads is connected as an API-key style integration (token + account ID), not an in-product OAuth app flow.

Suggested Operator Workflow

/metabuyer init
/metabuyer doctor
/metabuyer setup --apply --target-cpa 120 --target-roas 1.8 --date-preset last_7d --slack-target channel:C12345678
/metabuyer run-now
/metabuyer plan-actions
# Decide in Slack thread: APPROVE ... / REJECT ...
/metabuyer sync-approvals
/metabuyer execute-actions --confirm sandbox  # or --confirm live
/metabuyer action-log --limit 20
/metabuyer rollback-actions --confirm sandbox --limit 3

Simulated Chat in the UI

Example back-and-forth between an operator and MetaBuyer during normal operations.

Operator

Can you configure MetaBuyer for our account? Target CPA 120, target ROAS 1.8, and post updates in channel:C12345678.

MetaBuyer

Yes. I will apply the config and keep writes disabled initially. /metabuyer setup --apply --target-cpa 120 --target-roas 1.8 --date-preset last_7d --attribution-window 7d_click --source-of-truth meta --slack-target channel:C12345678 --execution-enabled false

Config applied

Operator

Run health checks and give me current status.

MetaBuyer

/metabuyer doctor PASS meta_runtime PASS meta_api_read PASS meta_permissions /metabuyer status enabled=true, executionEnabled=false, intervalSeconds=21600, halted=false

Diagnostics complete

Operator

Great. Run analysis now and tell me what it found.

MetaBuyer

/metabuyer run-now Summary: spend $2,843.19 | purchases 19 | CPA $149.64 | ROAS 1.21 Top recs: 2 high, 3 medium Posted report to Slack thread in channel:C12345678

Analysis run complete

Operator

Create an action plan but do not execute anything yet.

MetaBuyer

/metabuyer plan-actions Planned actions: 4 Requires approval: 3 Approval queue posted to Slack thread

Plan generated

Operator

I approved two actions in Slack and rejected one. Pull the latest decisions.

MetaBuyer

/metabuyer sync-approvals scannedThreads=1 processedCommands=2 approvedKeys=2 rejectedKeys=1

Slack decisions synced

Operator

Execute only approved actions in sandbox mode.

MetaBuyer

/metabuyer execute-actions --confirm sandbox applied=2 skipped=2 (1 rejected, 1 approval_required) failed=0 action log updated

Manual execution complete

Operator

Show last 10 actions and pause the agent until tomorrow.

MetaBuyer

/metabuyer action-log --limit 10 /metabuyer pause-agent --reason "manual review until tomorrow"

Operator override active

Approval replies in Slack never trigger writes by themselves. Execution only happens after explicit execute command confirmation.

Diagnostics (Optional)

`verify-use-cases` exists to validate Meta Marketing API permission/use-case probes on real connected accounts. It is a diagnostic helper, not the core purpose of MetaBuyer.

/metabuyer verify-use-cases [--page-id 123456789012345]

Command Reference

/metabuyer init

/metabuyer setup --apply ...

/metabuyer status

/metabuyer run-now

/metabuyer plan-actions

/metabuyer sync-approvals

/metabuyer execute-actions --confirm sandbox|live

/metabuyer rollback-actions --confirm sandbox|live

/metabuyer pause-agent --reason "manual review"

/metabuyer resume-agent

/metabuyer doctor

This page is the canonical workflow doc for MetaBuyer operations.