Meta Conversions API

Server Source code Package

Server-side event delivery to Meta's Conversions API for enhanced tracking accuracy and privacy compliance.

Where this fits

Meta CAPI is a server destination in the walkerOS flow:

Sends events server-side to Meta's Conversions API, bypassing browser limitations for improved data quality and privacy-compliant tracking.

Installation

npm install @walkeros/server-destination-meta

Integrated

import { startFlow } from '@walkeros/collector';
import { destinationMeta } from '@walkeros/server-destination-meta';

await startFlow({
destinations: {
  meta: {
    code: destinationMeta,
    config: {
      settings: {
        accessToken: 'YOUR_ACCESS_TOKEN',
        pixelId: 'YOUR_PIXEL_ID',
      },
    },
  },
},
});

Bundled

Add to your flow.json destinations:

"destinations": {
"meta": {
  "package": "@walkeros/server-destination-meta",
  "import": "destinationMeta",
  "config": {
    "settings": {
      "accessToken": "YOUR_ACCESS_TOKEN",
      "pixelId": "YOUR_PIXEL_ID"
    }
  }
}
}

See bundled mode setup | CLI reference

Configuration

This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.

Settings

Property	Type	Description	More
accessToken*	string	Meta access token for Conversions API authentication
pixelId*	string	Meta Pixel ID from your Facebook Business account
action_source		Source of the event (website, app, phone_call, etc.)
doNotHash	Array<string>	Array of user_data fields that should not be hashed
test_event_code	string	Test event code for debugging Meta Conversions API events
url	string	Custom URL for Meta Conversions API endpoint
user_data	Record<string, string>	Mapping configuration for user data fields

* Required fields

Mapping

This package does not define custom rule-level settings. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

Examples

Form submit

A form submission is forwarded to Meta CAPI as a custom event with the event source URL.

Event

{
  "name": "form submit",
  "data": {
    "type": "newsletter"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "email": "user@example.com"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "c1d2e3f4a5b60002",
  "trigger": "test",
  "entity": "form",
  "action": "submit",
  "timestamp": 1700000901,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "browser",
    "platform": "web",
    "url": "https://example.com"
  }
}

Out

sendServer("https://graph.facebook.com/v22.0/p1x3l1d/events", "{\"data\":[{\"event_name\":\"form submit\",\"event_id\":\"c1d2e3f4a5b60002\",\"event_time\":1700001,\"action_source\":\"website\",\"user_data\":{},\"event_source_url\":\"https://example.com\"}]}", {
  "headers": {
    "Authorization": "Bearer s3cr3t"
  }
})

Purchase

A completed order is sent to the Meta Conversions API as a Purchase event with value, currency, and contents.

Event

{
  "name": "order complete",
  "data": {
    "id": "ORD-300",
    "total": 249.99,
    "currency": "EUR"
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "user-123",
    "device": "device-456"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "SKU-A1",
        "price": 129.99,
        "quantity": 2
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "c1d2e3f4a5b60001",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000900,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "browser",
    "platform": "web",
    "url": "https://shop.example.com"
  }
}

Mapping

{
  "name": "Purchase",
  "data": {
    "map": {
      "order_id": "data.id",
      "currency": {
        "key": "data.currency",
        "value": "EUR"
      },
      "value": "data.total",
      "contents": {
        "loop": [
          "nested",
          {
            "condition": {
              "$code": "e=>y(e)&&\"product\"===e.entity"
            },
            "map": {
              "id": "data.id",
              "item_price": "data.price",
              "quantity": {
                "key": "data.quantity",
                "value": 1
              }
            }
          }
        ]
      },
      "num_items": {
        "fn": {
          "$code": "e=>e.nested.filter(e=>\"product\"===e.entity).length"
        }
      }
    }
  }
}

Out

sendServer("https://graph.facebook.com/v22.0/p1x3l1d/events", "{\"data\":[{\"event_name\":\"Purchase\",\"event_id\":\"c1d2e3f4a5b60001\",\"event_time\":1700001,\"action_source\":\"website\",\"order_id\":\"ORD-300\",\"currency\":\"EUR\",\"value\":249.99,\"contents\":[{\"id\":\"SKU-A1\",\"item_price\":129.99,\"quantity\":2}],\"num_items\":1,\"user_data\":{},\"event_source_url\":\"https://shop.example.com\"}]}", {
  "headers": {
    "Authorization": "Bearer s3cr3t"
  }
})

Purchase with fbclid

A purchase is sent to Meta CAPI with an external_id and a formatted fbc click id for ads attribution.

Event

{
  "name": "order complete",
  "data": {
    "id": "ORD-700",
    "total": 89.99,
    "currency": "USD"
  },
  "context": {
    "fbclid": [
      "abc123xyz",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "cust-42"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "c1d2e3f4a5b60003",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000902,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "browser",
    "platform": "web",
    "url": "https://shop.example.com"
  }
}

Mapping

{
  "name": "Purchase",
  "data": {
    "map": {
      "currency": {
        "key": "data.currency",
        "value": "EUR"
      },
      "value": "data.total",
      "order_id": "data.id",
      "user_data": {
        "map": {
          "external_id": "user.id",
          "fbclid": "context.fbclid"
        }
      }
    }
  }
}

Out

sendServer("https://graph.facebook.com/v22.0/p1x3l1d/events", "{\"data\":[{\"event_name\":\"Purchase\",\"event_id\":\"c1d2e3f4a5b60003\",\"event_time\":1700001,\"action_source\":\"website\",\"currency\":\"USD\",\"value\":89.99,\"order_id\":\"ORD-700\",\"user_data\":{\"external_id\":\"8a3c5a67cad508582b5edf6b8352cea3ffbad7f44812c1a736b4444c0f5746aa\",\"fbc\":\"fb.1.1700000902.abc123xyz,0\"},\"event_source_url\":\"https://shop.example.com\"}]}", {
  "headers": {
    "Authorization": "Bearer s3cr3t"
  }
})