Connect Meta Conversions API

Kalman sends your conversions to Meta from its servers, through the Conversions API. The PHI firewall builds every event from a fixed list of fields: hashed identifiers, the event, its time and a value. Only workspace owners and admins can change these settings.

Nothing goes to Meta, test events included, until your account's BAA is signed (see Sign your BAA).

1. Credentials

1. Go to Integrations. Under Ad platforms, choose Connect Meta Conversions API.
2. In Meta Events Manager, open your dataset (pixel) and go to Settings. Copy the Dataset ID into Dataset (pixel) ID.
3. On the same Settings page, generate a Conversions API access token and paste it into System-user access token. After you save, the field shows the token as saved. Paste a new one only when you want to replace it.
4. Optional: add the Ad account ID (optional, for spend). Use the number without act_. Kalman uses the same token to import spend, so that token needs ads_read on the ad account. The Getting your credentials panel walks you through setting this up.
5. Optional: add a Test event code (optional) from Events Manager → Test events.
6. Choose Connect Meta.

This step also has two privacy options:

• Send visitor user agent: off by default. Meta requires the visitor's browser user agent for website events (page views, leads, intake steps, checkouts and purchases). While it's off, those events are held, not sent. Refills, cancellations and other lifecycle events still go out.
• Send visitor IP address: off by default. It helps Meta match more events. IP addresses are personal data, so turn it on only if your BAA and privacy policy cover it.
• Leave the site URL out: Kalman only ever sends your site's root address (https://yourbrand.com/), never a page path. Meta also requires it for website events, so with this on, website events are held. If your site's address names a condition or treatment, this option starts switched on.

Kalman labels each event by where it really happened: site and checkout events as website, refills, cancellations and back-office events as system-generated. A privacy setting never changes the label. A held event shows in the Events log with the reason "Website event held: user agent or site URL turned off".

New connections start live. If you'd rather watch first, tick Start in shadow mode (see Shadow mode and going live).

2. Browser pixel

If the Meta pixel (fbq) is still on your site, Meta gets each conversion twice. The simplest fix is to remove the pixel. To keep it, create one id per event and give the same id to both:

var id = kalman.eventId();
kalman('track', 'purchase', { event_id: id, value: 199 });
fbq('track', 'Purchase', { value: 199, currency: 'USD' }, { eventID: id });

Also make the Meta event name in step 3 match the name the pixel uses.

3. Map events and values

For each Kalman event, choose Send, a Meta event and a Value. By default Kalman sends four events: Lead (as Lead, no value), Checkout started (InitiateCheckout), Purchase (Purchase) and Refill purchased (Repeat).

• Meta event: pick a standard event or type a custom name. Custom names can use letters, numbers and underscores, up to 40 characters. They can't name a condition, medication, body part or one of your brand terms.
• Value: Event value, Product projected LTV, Product average LTV, Blended (workspace average), Fixed amount or No value.
• Round values to the nearest $ (optional): an exact price can show which product someone bought. Round it, or use Blended.
• Provider approved and Provider declined are sent only after you tick the acknowledgement on that row. Use them only with opt-in consent.

Choose Save.

4. Preview and 5. Test event

• Show preview shows exactly what the firewall would send for your latest event of each mapped type, or a synthetic example. Identity shows only as "✓ hashed".
• Send test event sends a synthetic Lead whose only user data is a random hashed id. You see the HTTP status and Meta's reply.

While a test event code is saved, every event goes to Meta's Test Events tab only. When you finish testing, clear the field and choose Save.

6. Optimize

In Events Manager, create custom conversions for custom events such as Repeat. Then add Kalman's URL parameters to your ads so spend lines up with results (see Acquisition and spend).

Pausing and disconnecting

• Pause sending stops delivery for the whole workspace. Events are still recorded and wait as pending. When you choose Resume sending, they go out, except anything older than Meta's 7-day window, which is skipped.
• Download data-flow record exports a CSV with the allowlist, your mappings, the consent mode, delivery and skip counts, and settings changes.
• Disconnect removes the connection, and pending deliveries stop.

What Kalman never sends

Kalman never sends names, plain emails or phone numbers (only SHA-256 hashes), intake answers, page paths or titles, or anything that names a condition, medication or product. The page address is at most your site's root. Visitors who said no to ad sharing, or whose browser sends Global Privacy Control, are skipped (see Consent and GPC).

What Meta receives

For each event, Meta gets only these fields:

• event_name, event_time, event_id and action_source (website or system-generated, from where the event happened)
• event_source_url: your site's root address only, such as https://yourbrand.com/, never a page path
• user_data: hashed email, phone, external id, zip, city, state and country; the fbc and fbp click and browser ids; and, only if you turn them on, the visitor's user agent and IP address
• custom_data: value and currency only

No product id, SKU, product name, content_ids or content_name is ever sent. A product only changes the value.

Provider decisions are off until you turn them on

Provider approved and Provider declined are available but not mapped by default. To send one, map it and tick the acknowledgement that you're sending a provider's decision to Meta. Until then, those events are held as "Provider decision, not acknowledged".

Health policies still apply

Removing health terms, hashing identifiers and signing a BAA don't make an event eligible under Meta's health-data policies. If your brand treats a single condition, prefer opt-in consent. See Consent and Global Privacy Control.