Skip to content
adscapi
← Platforms
Real Conversions API

Meta setup

Set Meta’s tokens once. Then every ads.conversions.track() call fans the event out to Meta server-side — no per-platform code.

Setup guide

Overview

adscapi sends server-side events to the Meta Conversions API (Graph API /{dataset-id}/events). Email, phone, and IP are SHA-256 hashed before they leave your server; fbc/fbp click identifiers are forwarded when ad-personalization consent is set.

Prerequisites

  • A Meta Business account and a Meta ad account.
  • A dataset (formerly "pixel") in Events Manager.

1. Create an account

  1. Go to business.facebook.com and create a Business portfolio.
  2. In Events Manager, select Connect data source → Web and create a dataset. This is your pixel/dataset.

2. Get your credentials

Secret Where to get it
META_PIXEL_ID Events Manager → your dataset → Settings. The Dataset ID at the top is the pixel id.
META_CAPI_TOKEN Events Manager → your dataset → Settings → Conversions API → Generate access token. Copy it once — it is not shown again.
META_TEST_EVENT_CODE (optional) Events Manager → Test events tab. Use it to see events arrive live while you wire up.

The access token needs the ads_management permission on the dataset. A System User token (Business Settings → Users → System users) is the durable choice for production; the per-dataset generated token above is fine to start.

3. Configure adscapi

export META_PIXEL_ID="1330944745470743"
export META_CAPI_TOKEN="EAAG…"
# optional, while testing:
export META_TEST_EVENT_CODE="TEST12345"

4. Verify

adscapi verify --platform meta

Expected: [OK ] meta — dataset 1330944745470743 reachable. A 401/400 means the token can't read the dataset — see Troubleshooting.

5. Event mapping

Canonical Meta
page_view PageView
lead Lead
signup CompleteRegistration
checkout_created InitiateCheckout
purchase Purchase

Troubleshooting

  • HTTP 401 / 190 — token expired or lacks ads_management. Regenerate under Settings → Conversions API, or mint a System User token.
  • Events don't show — set META_TEST_EVENT_CODE and watch the Test events tab; without it, events land in the dataset but take minutes to aggregate.
  • Low match quality — pass more of user.email / user.phone; adscapi hashes them for you, so send the raw values, never pre-hashed.

1. Install adscapi

shell
npm install adscapi
# or run without installing:
npx adscapi platforms

2. Get Meta's tokens

Meta activates once all of these are set. Run npx adscapi platforms to see them, then get each value from Meta’s ads or events dashboard.

META_CAPI_TOKENMETA_PIXEL_ID

3. Set them for adscapi

Export the tokens in the environment that runs your server or the adscapi CLI.

shell
export META_CAPI_TOKEN="…"
export META_PIXEL_ID="…"

4. Verify

check confirms the secrets are present; verify calls Meta’s API to confirm they are valid.

shell
npx adscapi check
npx adscapi verify --platform meta

5. Track a conversion

One call, sent to Meta and every other configured platform. Pass raw email — adscapi hashes per platform. Consent is required.

ts
import { createAdscapi } from 'adscapi';

const ads = createAdscapi();

const results = await ads.conversions.track({
  name: 'purchase',
  value: 49,
  currency: 'USD',
  user: { email: 'buyer@example.com' },
  consent: { adUserData: true, adPersonalization: true },
});

See the exact request on the Meta payload preview.