Skip to main content
Ask your AI

Meta Conversions API

Server Source code Package

Sends walkerOS events from your server to the Meta Conversions API. Customer information such as email and phone number is normalized and SHA-256 hashed before the request leaves your server.

Where this fits

Meta CAPI is a server destination in the walkerOS flow:

It receives events from the collector and posts each one to the Conversions API endpoint of your Meta Pixel.

Installation​

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

await startFlow({
  destinations: {
    meta: {
      code: destinationMeta,
      config: {
        settings: {
          accessToken: process.env.META_ACCESS_TOKEN,
          pixelId: '1234567890',
        },
      },
    },
  },
});

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​

PropertyTypeDescriptionMore
accessToken*stringMeta access token for Conversions API authentication
pixelId*stringMeta Pixel ID from your Facebook Business account
action_sourceSource of the event (website, app, phone_call, etc.)
doNotHashArray<string>user_data keys to send without normalizing and hashing, for values that are already hashed. Only em, ph, fn, ln, db, ge, ct, st, zp, country and external_id are hashed
test_event_codestringTest event code for debugging Meta Conversions API events
urlstringCustom URL for Meta Conversions API endpoint
user_dataRecord<string, Mapping.Value>Mapping of Meta customer information parameters to event values, applied to every event. Keys must be Meta's short names such as em and ph
ipany | booleanClient IP, sent as user_data.client_ip_address. Resolves against { ingest, event }. Default: ["ingest.ip", "event.user.ip"]. false switches it off. A mapped user_data.client_ip_address wins.
userAgentany | booleanClient user agent, sent as user_data.client_user_agent. Resolves against { ingest, event }. Default: ["ingest.userAgent", "event.user.userAgent"]. false switches it off. A mapped user_data.client_user_agent wins.
* 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

Add to cart

A product add is sent as AddToCart with currency, value and the added product in custom_data.

Event
{
  "name": "product add",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420,
    "quantity": 1,
    "currency": "EUR"
  },
  "context": {
    "shopping": [
      "intent",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n",
    "ip": "192.0.2.1",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "83e860384d50953f",
  "trigger": "click",
  "entity": "product",
  "action": "add",
  "timestamp": 1700000000000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "browser",
    "platform": "web",
    "url": "https://www.example.com/",
    "referrer": "https://www.walkeros.io/"
  }
}
Mapping
{
  "name": "AddToCart",
  "data": {
    "map": {
      "custom_data": {
        "map": {
          "currency": {
            "key": "data.currency",
            "value": "EUR"
          },
          "value": "data.price",
          "content_type": {
            "value": "product"
          },
          "contents": {
            "set": [
              {
                "map": {
                  "id": "data.id",
                  "quantity": {
                    "key": "data.quantity",
                    "value": 1
                  },
                  "item_price": "data.price"
                }
              }
            ]
          }
        }
      },
      "user_data": {
        "map": {
          "external_id": "user.id"
        }
      }
    }
  }
}
Out
sendServer("https://graph.facebook.com/v22.0/1234567890/events", "{\"data\":[{\"event_name\":\"AddToCart\",\"event_id\":\"83e860384d50953f\",\"event_time\":1700000000,\"action_source\":\"website\",\"custom_data\":{\"currency\":\"EUR\",\"value\":420,\"content_type\":\"product\",\"contents\":[{\"id\":\"ers\",\"quantity\":1,\"item_price\":420}]},\"user_data\":{\"client_ip_address\":\"192.0.2.1\",\"client_user_agent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64)\",\"external_id\":\"273f9a3cb7d30a28b5e1a1040f4f0becae0bb574fab1f05e5653e78e93d2eb69\"},\"event_source_url\":\"https://www.example.com/\"}]}", {
  "headers": {
    "Authorization": "Bearer s3cr3t"
  }
})

Page view

A page view is sent to the Meta Conversions API as PageView with the request IP, user agent and a hashed external id.

Event
{
  "name": "page view",
  "data": {
    "domain": "www.example.com",
    "title": "walkerOS documentation",
    "referrer": "https://www.walkeros.io/",
    "search": "?foo=bar",
    "hash": "#hash",
    "id": "/docs/"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "pagegroup": "docs"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n",
    "ip": "192.0.2.1",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "f0cc5f6fec3d8eeb",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000000000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "browser",
    "platform": "web",
    "url": "https://www.example.com/",
    "referrer": "https://www.walkeros.io/"
  }
}
Mapping
{
  "name": "PageView",
  "data": {
    "map": {
      "user_data": {
        "map": {
          "external_id": "user.id"
        }
      }
    }
  }
}
Out
sendServer("https://graph.facebook.com/v22.0/1234567890/events", "{\"data\":[{\"event_name\":\"PageView\",\"event_id\":\"f0cc5f6fec3d8eeb\",\"event_time\":1700000000,\"action_source\":\"website\",\"user_data\":{\"client_ip_address\":\"192.0.2.1\",\"client_user_agent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64)\",\"external_id\":\"273f9a3cb7d30a28b5e1a1040f4f0becae0bb574fab1f05e5653e78e93d2eb69\"},\"event_source_url\":\"https://www.example.com/\"}]}", {
  "headers": {
    "Authorization": "Bearer s3cr3t"
  }
})

Purchase

An order complete is sent as Purchase with value, currency, order id and one content per product in custom_data.

Event
{
  "name": "order complete",
  "data": {
    "id": "0rd3r1d",
    "currency": "EUR",
    "value": 462,
    "tax": 73.76,
    "shipping": 5.22,
    "total": 467.22
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n",
    "ip": "192.0.2.1",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
  },
  "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": "235d0d7bd7a213f2",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000000000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "browser",
    "platform": "web",
    "url": "https://www.example.com/",
    "referrer": "https://www.walkeros.io/"
  }
}
Mapping
{
  "name": "Purchase",
  "data": {
    "map": {
      "custom_data": {
        "map": {
          "currency": {
            "key": "data.currency",
            "value": "EUR"
          },
          "value": "data.value",
          "order_id": "data.id",
          "content_type": {
            "value": "product"
          },
          "contents": {
            "loop": [
              "nested",
              {
                "condition": {
                  "$code": "e=>\"object\"==typeof e&&null!==e&&\"entity\"in e&&\"product\"===e.entity"
                },
                "map": {
                  "id": "data.id",
                  "quantity": {
                    "key": "data.quantity",
                    "value": 1
                  },
                  "item_price": "data.price"
                }
              }
            ]
          }
        }
      },
      "user_data": {
        "map": {
          "external_id": "user.id"
        }
      }
    }
  }
}
Out
sendServer("https://graph.facebook.com/v22.0/1234567890/events", "{\"data\":[{\"event_name\":\"Purchase\",\"event_id\":\"235d0d7bd7a213f2\",\"event_time\":1700000000,\"action_source\":\"website\",\"custom_data\":{\"currency\":\"EUR\",\"value\":462,\"order_id\":\"0rd3r1d\",\"content_type\":\"product\",\"contents\":[{\"id\":\"ers\",\"quantity\":1,\"item_price\":420},{\"id\":\"cc\",\"quantity\":1,\"item_price\":42}]},\"user_data\":{\"client_ip_address\":\"192.0.2.1\",\"client_user_agent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64)\",\"external_id\":\"273f9a3cb7d30a28b5e1a1040f4f0becae0bb574fab1f05e5653e78e93d2eb69\"},\"event_source_url\":\"https://www.example.com/\"}]}", {
  "headers": {
    "Authorization": "Bearer s3cr3t"
  }
})

View content

A product view is sent as ViewContent with currency, value and the product in custom_data.

Event
{
  "name": "product view",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420,
    "currency": "EUR"
  },
  "context": {
    "shopping": [
      "detail",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n",
    "ip": "192.0.2.1",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "db22fb16c70f663d",
  "trigger": "load",
  "entity": "product",
  "action": "view",
  "timestamp": 1700000000000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "browser",
    "platform": "web",
    "url": "https://www.example.com/",
    "referrer": "https://www.walkeros.io/"
  }
}
Mapping
{
  "name": "ViewContent",
  "data": {
    "map": {
      "custom_data": {
        "map": {
          "currency": {
            "key": "data.currency",
            "value": "EUR"
          },
          "value": "data.price",
          "content_type": {
            "value": "product"
          },
          "contents": {
            "set": [
              {
                "map": {
                  "id": "data.id",
                  "quantity": {
                    "key": "data.quantity",
                    "value": 1
                  },
                  "item_price": "data.price"
                }
              }
            ]
          }
        }
      },
      "user_data": {
        "map": {
          "external_id": "user.id"
        }
      }
    }
  }
}
Out
sendServer("https://graph.facebook.com/v22.0/1234567890/events", "{\"data\":[{\"event_name\":\"ViewContent\",\"event_id\":\"db22fb16c70f663d\",\"event_time\":1700000000,\"action_source\":\"website\",\"custom_data\":{\"currency\":\"EUR\",\"value\":420,\"content_type\":\"product\",\"contents\":[{\"id\":\"ers\",\"quantity\":1,\"item_price\":420}]},\"user_data\":{\"client_ip_address\":\"192.0.2.1\",\"client_user_agent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64)\",\"external_id\":\"273f9a3cb7d30a28b5e1a1040f4f0becae0bb574fab1f05e5653e78e93d2eb69\"},\"event_source_url\":\"https://www.example.com/\"}]}", {
  "headers": {
    "Authorization": "Bearer s3cr3t"
  }
})

How it works​

Every event becomes one POST request to {url}/{pixelId}/events, with the access token in an Authorization: Bearer header. The default url is https://graph.facebook.com/v22.0, and a trailing slash is optional. The destination does not batch events.

The server event is built from the walkerOS event:

FieldValue
event_nameThe walkerOS event name, such as order complete. Set name in a mapping rule to send a Meta event name such as Purchase.
event_idThe walkerOS event.id. If the Meta Pixel tracks the same event in the browser, send the same ID and the same event name (set name in the rule, such as Purchase). Meta then deduplicates the two when it receives them within 48 hours.
event_timeThe event timestamp converted from milliseconds to seconds.
action_sourcesettings.action_source, or website if it is not set.
event_source_urlevent.source.url, added only when action_source is website.

Keys returned by data mappings are added to the top level of the server event exactly as mapped. Only the customer information keys of user_data listed below are normalized and hashed, so an email or phone number mapped anywhere else leaves your server in clear text. Map personal data only under user_data. Meta documents the business data of an event (value, currency, contents, order_id, content_type, num_items) as custom data in the custom_data object and does not list them among the top-level parameters of a server event, so map those keys under custom_data. The destination does not check or move them. user_data combines settings.user_data with the user_data mapped in the destination config.data and in the rule's data. When the same key is mapped in more than one place, the rule's value wins.

If user_data contains fbclid, the destination replaces it with fbc in the format fb.1.{creationTime}.{fbclid}. The creation time is the session start in milliseconds when the collector has a session, and the event timestamp otherwise.

A Purchase rule that puts the order into custom_data:

An order complete is sent as Purchase with value, currency, order id and one content per product in custom_data.

Event
{
  "name": "order complete",
  "data": {
    "id": "0rd3r1d",
    "currency": "EUR",
    "value": 462,
    "tax": 73.76,
    "shipping": 5.22,
    "total": 467.22
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n",
    "ip": "192.0.2.1",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
  },
  "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": "235d0d7bd7a213f2",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000000000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "browser",
    "platform": "web",
    "url": "https://www.example.com/",
    "referrer": "https://www.walkeros.io/"
  }
}
Mapping
{
  "name": "Purchase",
  "data": {
    "map": {
      "custom_data": {
        "map": {
          "currency": {
            "key": "data.currency",
            "value": "EUR"
          },
          "value": "data.value",
          "order_id": "data.id",
          "content_type": {
            "value": "product"
          },
          "contents": {
            "loop": [
              "nested",
              {
                "condition": {
                  "$code": "e=>\"object\"==typeof e&&null!==e&&\"entity\"in e&&\"product\"===e.entity"
                },
                "map": {
                  "id": "data.id",
                  "quantity": {
                    "key": "data.quantity",
                    "value": 1
                  },
                  "item_price": "data.price"
                }
              }
            ]
          }
        }
      },
      "user_data": {
        "map": {
          "external_id": "user.id"
        }
      }
    }
  }
}
Out
sendServer("https://graph.facebook.com/v22.0/1234567890/events", "{\"data\":[{\"event_name\":\"Purchase\",\"event_id\":\"235d0d7bd7a213f2\",\"event_time\":1700000000,\"action_source\":\"website\",\"custom_data\":{\"currency\":\"EUR\",\"value\":462,\"order_id\":\"0rd3r1d\",\"content_type\":\"product\",\"contents\":[{\"id\":\"ers\",\"quantity\":1,\"item_price\":420},{\"id\":\"cc\",\"quantity\":1,\"item_price\":42}]},\"user_data\":{\"client_ip_address\":\"192.0.2.1\",\"client_user_agent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64)\",\"external_id\":\"273f9a3cb7d30a28b5e1a1040f4f0becae0bb574fab1f05e5653e78e93d2eb69\"},\"event_source_url\":\"https://www.example.com/\"}]}", {
  "headers": {
    "Authorization": "Bearer s3cr3t"
  }
})

If test_event_code is set, it is added to the request body.

A response outside the 2xx range, a network error, or no answer within 5 seconds fails the event: the push answers failed with the code transport (with the HTTP status) or timeout, the event goes to the dead-letter queue, and the collector logs one ERROR line without the response body. The destination does not retry. Without accessToken or pixelId the destination does not start: every push answers failed with the code config, and the collector logs destination init failed.

Customer information hashing​

user_data keys must be Meta's parameter names from Meta's customer information parameters, such as em for email and ph for phone. fbclid is also accepted and becomes fbc. The settings schema and the TypeScript types list only these parameter names, so a key like email is rejected by this package's schema and by type checking. Any other key that reaches user_data, for example through a data mapping, is dropped before the request is sent, and the push still answers done. The only report is a WARN line (Unknown Meta user_data keys dropped) that names no key and does not show at the default log level, so map only Meta's parameter names.

The destination normalizes and SHA-256 hashes these keys. Arrays are handled item by item.

KeyNormalization before hashing
emTrim and lowercase.
phKeep only digits and drop leading zeros. The destination cannot add a country code, so the mapped value must include one.
fn, lnLowercase, remove punctuation, and trim. Accented and non-Latin letters are kept.
dbOnly year-first dates are normalized: 1997-02-16 becomes 19970216. Other formats such as 02/16/1997 are only trimmed and cannot match, so map dates as YYYYMMDD. The destination writes a WARN line (not shown at the default log level) when a date is not 8 digits after normalization.
geFirst letter, lowercased (Female becomes f).
ct, stLowercase and remove everything except letters and digits. Full state names are not converted to codes.
zpLowercase and remove spaces and dashes. U.S. ZIP+4 codes such as 94035-1234 or 940351234 keep the first 5 digits.
countryTrim and lowercase. Map the ISO 3166-1 alpha-2 code, since country names are not converted.
external_idNone. The value is hashed as it is.

The other parameters, such as client_ip_address, client_user_agent, fbc, or fbp, are sent unchanged. If a value is already hashed, add its key to doNotHash and the destination sends it exactly as mapped.

Client IP and user agent​

The destination sends the client IP as user_data.client_ip_address and the user agent as user_data.client_user_agent by default. The ip and userAgent settings resolve against { ingest, event } and default to ["ingest.ip", "event.user.ip"] and ["ingest.userAgent", "event.user.userAgent"], so they fill in whenever the source provides them (see the config.ingest recipe on the Express source). A value your mapping sets for user_data.client_ip_address or user_data.client_user_agent wins. A value that resolves to nothing is not sent. Set either setting to false to turn it off, or to another mapping value to read it elsewhere.

The quickstart sets no config.consent, so Meta receives every event, whatever consent the event carries. To send only events with consent, add consent: { marketing: true } to config, next to settings (with several keys listed, one granted key is enough). An event without that consent is skipped or queued, depending on the collector's consentDenied. Server flows built by the CLI skip it and count it in skipped. With startFlow it waits in the destination's queue by default: a later event that carries consent does not release it, and only a walker consent command does, which then sends the waiting events of every user at once. Pass consentDenied: 'skip' to startFlow to skip such events instead (see Gate a destination with consent and consent-denied events on a server).

💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)