Write-Back (Meta CAPI)

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.

Prerequisites

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

1. Token scope -- your MCP token must include mcp:write
2. Workspace setting -- a workspace admin must enable MCP write-back in workspace settings
3. User role -- you must be a workspace owner or admin
4. 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.

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

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:

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:

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

Related