/meta-capi

name: meta-capi
description: Meta Conversions API (CAPI) Setup Reference — architecture, event types, customer information hashing, deduplication, implementation examples, AEM, and testing
version: "1.0.0"
author: Cogny AI
platforms: []
user-invocable: true
argument-hint: "<query or topic>"
allowed-tools:
  - WebFetch
  - WebSearch
  - Bash
  - Read
  - Write
  # Meta Ads tools (when connected via Cogny MCP)
  - mcp__cogny__meta_ads__tool_get_pixels
  - mcp__cogny__meta_ads__tool_get_insights
  - mcp__cogny__meta_ads__tool_get_campaigns
  - mcp__cogny__meta_ads__tool_get_ad_sets
  - mcp__cogny__meta_ads__tool_get_ads
  - mcp__cogny__meta_ads__tool_get_custom_audiences
  - mcp__cogny__meta_ads__tool_list_ad_accounts

Meta Conversions API (CAPI) Setup Reference

Complete technical reference for Meta Conversions API: architecture, all standard event types with parameters, customer information hashing, implementation methods, event deduplication, testing, and Aggregated Event Measurement.

Full docs: https://cogny.com/docs/meta-conversions-api

Usage

/meta-capi                          # Full CAPI overview
/meta-capi deduplication            # Event dedup strategy
/meta-capi purchase event           # Purchase event parameters
/meta-capi emq                      # Improve Event Match Quality
/meta-capi aem                      # Aggregated Event Measurement
/meta-capi node.js                  # Node.js implementation example
/meta-capi gtm server-side          # GTM SS container setup

Instructions

You are a Meta Conversions API expert. Use this reference to help users implement CAPI correctly, debug event tracking issues, improve Event Match Quality, configure deduplication, and understand Aggregated Event Measurement.

When the user asks a question, find the relevant section below and provide precise, actionable answers with ready-to-use code examples.

If the user provides a specific topic as an argument, focus on that area. Otherwise, provide an overview of the CAPI architecture and key implementation steps.

If Cogny MCP tools are available, use them to inspect the user's actual Pixel configuration, ad account setup, and campaign data to provide contextual recommendations.

---

Architecture: Browser Pixel vs Server-Side CAPI

                         User's Browser
                        +------------------------------+
                        |  Meta Pixel (fbevents.js)     |
                        |  - Fires on page interaction  |
                        |  - Sets _fbp / _fbc cookies   |
                        |  - Sends event_id for dedup   |
                        +----------+-------------------+
                                   |  HTTPS (browser -> Meta)
                                   v
                        +------------------------------+
                        |       Meta Servers            |
                        |  - Receives Pixel events      |
                        |  - Receives CAPI events       |
                        |  - Deduplicates via event_id  |
                        |  - Matches users (EMQ)        |
                        |  - Feeds ad optimization      |
                        +------------------------------+
                                   ^
                                   |  HTTPS (server -> Meta)
                        +----------+-------------------+
                        |  Your Server / GTM SS         |
                        |  - Conversions API endpoint   |
                        |  - POST /v21.0/{pixel_id}/    |
                        |    events                     |
                        |  - Hashes PII before sending  |
                        |  - Sends same event_id        |
                        +------------------------------+

**Why both matter:**

• **Pixel only:** Subject to ad blockers (15-30% signal loss), ITP cookie expiry (7-day cap on Safari), and network failures.
• **CAPI only:** Misses real-time browser interactions and cannot set first-party cookies.
• **Pixel + CAPI (recommended):** Redundant data paths with deduplication. Recovers 10-25% of lost conversions.

Standard Events

Purchase

Fired when a transaction is completed.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `value` | float | **Yes** | Total transaction value | | `currency` | string | **Yes** | ISO 4217 code (e.g., `USD`, `EUR`) | | `content_ids` | array<string> | Recommended | Product IDs from catalog | | `content_type` | string | Recommended | `product` or `product_group` | | `contents` | array<object> | Recommended | Array of `{id, quantity, item_price}` | | `content_name` | string | Optional | Product or page name | | `content_category` | string | Optional | Product category | | `num_items` | integer | Optional | Number of items | | `order_id` | string | Optional | Internal order ID |

AddToCart

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `value` | float | Recommended | Item value | | `currency` | string | Recommended | ISO 4217 code | | `content_ids` | array<string> | Recommended | Product IDs | | `content_type` | string | Recommended | `product` or `product_group` | | `contents` | array<object> | Recommended | `{id, quantity, item_price}` | | `content_name` | string | Optional | Product name | | `content_category` | string | Optional | Product category |

InitiateCheckout

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `value` | float | Recommended | Cart value | | `currency` | string | Recommended | ISO 4217 code | | `content_ids` | array<string> | Recommended | Product IDs in cart | | `content_type` | string | Recommended | `product` or `product_group` | | `contents` | array<object> | Recommended | `{id, quantity, item_price}` | | `num_items` | integer | Optional | Number of items |

CompleteRegistration

| Parameter | Type | R