Write-Back (Meta CAPI)

Push attributed conversions to Meta Conversions API with preview, dry-run, and confirm safety flow

The send_meta_conversions tool lets you push attributed conversions from Atribu to Meta's Conversions API (CAPI). This improves Meta's ad delivery optimization by feeding real conversion data back to the algorithm.

Atribu has a second write tool with the same gates and safety flow: apply_recommendation, which applies AI media-buyer recommendations (pause / budget changes) against Meta. Most of this page covers send_meta_conversions; the differences for apply_recommendation are at the end.

Irreversible action

Confirmed conversions are sent to Meta and cannot be recalled. The tool enforces a three-step safety flow to prevent accidental submissions.

Prerequisites

Before using write-back, all four conditions must be met:

Token scope -- your MCP token must include mcp:write
Workspace setting -- a workspace admin must enable MCP write-back in workspace settings
User role -- you must be a workspace owner or admin
Meta connection -- a Meta Ads connection must be active

If any condition is unmet, the tool returns a typed error explaining what's missing and how to fix it.

The three-step flow

Step 1: Preview

Build conversion events locally and inspect them without calling Meta.

Send my last 7 days of payment_received conversions to Meta in preview mode

The tool returns:

Total event count
Sample events (first 3) with mapped fields
Match-quality breakdown (great / good / weak) based on available user data

No data leaves Atribu during preview — no Meta call is made. The preview itself is still recorded in the audit trail.

Step 2: Dry-run

Submit events to Meta with a test event code. Meta validates the payload format and match quality without recording real conversions.

Do a dry-run of those conversions with pixel ID 1234567890

The tool returns:

events_received count from Meta
fbtrace_id for debugging in Meta Events Manager
Any validation warnings from Meta

Test events

Dry-run events appear in Meta Events Manager under the Test Events tab. They do not affect ad delivery or reporting.

Step 3: Confirm

Submit events to Meta for real. Requires an idempotency key to prevent duplicate submissions.

Confirm sending those conversions. Use idempotency key "april-week2-payments"

The AI tool should generate a unique idempotency key (typically a UUID or descriptive string) and include it in the confirm call. If the same idempotency key is used twice, the tool returns the prior result instead of submitting again.

Event type mapping

Atribu outcome types map to Meta standard events:

Atribu event	Meta event
`payment_received`	`Purchase`
`order_placed`	`Purchase`
`closed_won`	`Purchase`
`appointment_booked`	`Schedule`
`lead_created`	`Lead`
`checkout_started`	`InitiateCheckout`
`add_to_cart`	`AddToCart`
`add_payment_info`	`AddPaymentInfo`
`view_content`	`ViewContent`
`search`	`Search`

Safety rails

Idempotency

Every confirm call requires an idempotency_key. If a confirm with the same key was already processed for this profile, the tool returns the prior result. This prevents accidental double-sends even if the AI tool retries.

Circuit breaker

If 3 or more confirm operations fail for the same profile within 30 minutes, the tool enters circuit-open state and rejects new confirm calls. Wait for the cooldown or investigate the failures.

Audit trail

Every operation (preview, dry-run, confirm) creates an immutable audit record with:

Payload hash, event count, window dates
External submission IDs (on success)
Result status and error details
Request ID for traceability

Audit records are visible to workspace admins in the dashboard.

Match quality

The preview step estimates how well Meta can match your events to ad clicks. The strong identifiers are email, phone, fbc (Meta click ID), and ctwa_clid (Click-to-WhatsApp click ID):

Quality	Criteria
Great	Has 2 or more strong identifiers
Good	Has exactly 1 strong identifier, or an `fbp` (browser) cookie
Weak	None of the above -- Meta may not match this event

Higher match quality means Meta can better attribute the conversion to the right ad click, improving future ad delivery.

apply_recommendation — the second write tool

apply_recommendation applies an AI media-buyer recommendation (pause an underperformer, scale a winner, reallocate budget between ad sets) against Meta. It shares the write-back machinery:

Same three modes -- preview (no side effects; shows the target ad/ad-set, the planned Meta call(s), and the budget % delta), dry_run (records an audit row capturing intent), confirm (executes for real).
Same gates -- mcp:write scope + workspace write-back enabled + owner/admin role, enforced on dry_run and confirm. preview works without them.
Same cost -- 10 units.
Same audit trail -- every operation writes to the same audit log admins see in the dashboard.

Differences from send_meta_conversions:

Idempotency key is optional. When omitted on confirm, one is derived automatically from (user, recommendation, day) — so replaying the same recommendation on the same day deduplicates, while a deliberate next-day retry is distinct. Replaying a processed key returns the existing application, not a duplicate write.
Confirm is asynchronous. confirm enqueues a job for the pipeline worker, which captures the pre-change Meta state, executes the Meta write(s), and verifies the change actually landed about 5 minutes later. Use diagnose_recommendation to inspect the application, its pre/post state, and the verification result.
Confirm requires an open recommendation. Recommendations that are already applied, dismissed, superseded, expired, or rolled back are rejected (preview still works as a history lookup).
creative_refresh_pre_fatigue never calls Meta. That kind returns an Ads Lab handoff URL instead.