Connect Meta

Connecting Meta lets RetaFunnel send what happens on your pages straight to your Meta ad account, server to server: Lead, Schedule and Purchase events, one event per behaviour segment (so you can build an audience of "watched half the video, did not opt in"), and Custom Audience lists of identified people. This guide walks through every click, from the Business settings to the first retargeting audience in Ads Manager, and ends with the errors you are most likely to meet and how to fix them.

What you need before starting#

• A Business Portfolio (Meta still calls it Business Manager in places) at business.facebook.com, and you are an admin of it. You cannot create system users or tokens as an employee.
• A Pixel, which Meta now calls a Dataset. It is in Events Manager under Data sources. If you do not have one, Events Manager → Connect data sources → Web → name it → create (you do not need to install the Pixel code to use RetaFunnel, but keep it if it is already on your pages).
• An ad account that uses that dataset, owned by (or shared with) the same Business Portfolio.
• About fifteen minutes, and the RetaFunnel dashboard open in another tab at Integrations.

Two words that come up a lot:

• Conversions API (CAPI): Meta's way of receiving events from a server instead of from the browser. Ad blockers and iOS do not affect it.
• System user: a "robot" user inside your Business Portfolio. It owns a token that never expires, so your connection does not break when a human changes their password or leaves the team.

Step 1: create a system user#

1. Open business.facebook.com/settings. If you manage several portfolios, make sure the right one is selected at the top left.
2. In the left menu click Users → System users.
3. Click Add.
4. System username: RetaFunnel.
5. System user role: Admin. (Employee also works, but then every asset must be assigned with full control in the next step; Admin saves you the mistakes.)
6. Click Create system user. Accept the terms if Meta asks.

Step 2: give the system user access to the dataset and the ad account#

Still on the system user you just created:

1. Click Add assets (or Assign assets).
2. In the dialog choose Datasets (older interfaces say Pixels). Tick your dataset. On the right switch on Manage dataset (full control). Click Save changes.
3. Click Add assets again, choose Ad accounts, tick your ad account, switch on Manage campaigns (or Full control). Save.

If you later see the error (#100) Missing permission or does not have permission, it is almost always this step that was skipped or done on the wrong dataset.

Step 3: generate the token#

1. On the system user page click Generate new token.
2. Select app: pick an app of your Business Portfolio. If the list is empty you need one app, created once:
   • developers.facebook.com/apps → Create app → type Business (or "Other" → "Business") → name it RetaFunnel → choose your Business Portfolio as the business account → create.
   • Back in Business settings the app now appears under Accounts → Apps (add it there with Add → Connect an app ID if it does not).
   • Return to the system user and Generate new token again.
3. Token expiration: Never. A 60-day token stops your syncs two months later, silently.
4. Permissions (tick exactly these three): ads_management, business_management, ads_read.
5. Click Generate token. Copy the long string that starts with EAA… and keep it somewhere safe for the next minute; Meta will not show it again. If you lose it, generate a new one.

Step 4: find the two ids#

Dataset (Pixel) id

1. business.facebook.com/events_manager → Data sources in the left bar.
2. Click your dataset. The id (15–16 digits) is printed under its name at the top of the page, and again on the Settings tab under Dataset ID.

Ad account id

Either of these:

• Open Ads Manager. The address bar contains act=1234567890. The number after act= is the id.
• Business settings → Accounts → Ad accounts → click your account; the Ad account ID is shown under the name.

RetaFunnel wants it written as act_1234567890 (the letters act_ followed by the number).

Step 5: paste everything into RetaFunnel#

1. RetaFunnel → Integrations → card Meta.
2. System user token: paste the EAA… token.
3. Pixel (dataset) id: the digits from Step 4.
4. Ad account id: act_ + the number.
5. Leave Test event code empty for now.
6. Click Save. The badge on the card turns to connected. The token is encrypted on our servers and is never displayed again; the field will show "Stored" from now on.

Step 6: send a test event and see it in Events Manager#

This proves the token, the dataset and the permissions in one go.

1. Events Manager → your dataset → tab Test events.
2. Under "Test server events" copy the code shown, something like TEST51342.
3. RetaFunnel → Integrations → Meta → paste it into Test event code → click Send test event.
4. A green message appears with the event id and events_received 1. Within a few seconds the Test events tab shows an event named RetaFunnelTest coming from "Server".
5. Important: now clear the Test event code field and click Save. While a test code is saved, every event RetaFunnel sends (Leads, Purchases, segment events) is marked as a test event: Meta shows it under Test events only and ignores it for audiences and optimisation. Keep the code only while you are testing.

If the message is red, read the error text and jump to "Common errors" below.

Step 7: turn a segment into a Meta audience#

A segment is a saved rule over behaviour: "visitors in the last 30 days who watched at least 50% of the video and did not become a lead". Funnel templates create the usual ones for you; you can build more under Segments.

7a. Switch on the sync#

1. Sidebar → Segments → open a segment, for example VSL 50% – no lead.
2. In the sync panel switch on Meta ("Conversions API segment events and a Custom Audience"). Save if asked.
3. Optional but recommended: click Dry run first. It shows how many people would be sent and a sample of the (hashed) payload, without sending anything.
4. Click Sync now, or wait: every segment with a sync enabled is refreshed and synced every 15 minutes.
5. The Audiences page shows every synced segment with its live size, the last sync time and the full log of calls to Meta. Errors appear there and on the Meta card.

7b. What arrives on the Meta side#

Two things, depending on who is in the segment:

• Anonymous visitors (anyone the tracker saw, even without an email) are sent as a Conversions API event named after the segment: Seg_ + the segment's slug, for example Seg_vsl_50_no_lead. The slug is shown on the segment page. Within a few minutes the event appears in Events Manager → your dataset → Overview (and under Custom events in the event list).
• Identified people (segments whose target is person: they have an email or phone hash) are also added to a Custom Audience named [RetaFunnel] <segment name>, created automatically in your ad account the first time the sync runs, and removed from it when they leave the segment.

7c. Create the retargeting audience in Ads Manager (for Seg_ events)#

1. Ads Manager → menu (All tools) → Audiences.
2. Create audience → Custom audience.
3. Source: Website → Next.
4. Source: pick your dataset (Pixel).
5. Events: open the dropdown. Under "From your events" (or by typing in the search box) select Seg_vsl_50_no_lead (your segment's event). The event only appears in this list after Meta has received it at least once, so do a Sync now first and wait a few minutes.
6. Retention: 30 days (match the segment's own window; up to 180 is allowed by Meta).
7. Audience name: RF · VSL 50% no lead. Click Create audience.

Meta then fills the audience as events arrive. It shows "Populating" for a while and Meta does not display sizes under 1,000 people. Use the audience in an ad set's Custom audiences field for retargeting, or in Exclude to stop showing an ad to people who already converted.

7d. Use the synced Custom Audience list (for identified people)#

Nothing to create: open Ads Manager → Audiences and look for [RetaFunnel] <segment name> of type Customer list. Add it to an ad set like any other audience. Typical uses: Leads without booking as a retargeting audience, customers segments as an exclusion. The first time you use customer lists Meta asks you to accept the Custom Audience Terms; accept them once and re-run the sync.

What RetaFunnel sends to Meta, and when#

Timing: a scheduled job runs every 15 minutes. It recomputes every synced segment, sends the new members, and sends the standard events for leads, bookings and purchases of the last three hours that were not sent yet. Events arrive with their real timestamp, not the sync time. Test sessions (anything opened with ?_rf_test=1, site test mode, simulations) are never sent.

Deduplication with your browser Pixel. Every server event carries an event_id built as <session id>:<event name>:<n>. Meta discards a browser event with the same name and the same event_id received within 48 hours, so you can keep your Pixel installed. For that to work the Pixel must send the same id: fbq('track', 'Lead', {}, { eventID: rf.sessionId + ':Lead:1' }). If your Pixel fires Lead or Purchase without an eventID, Meta counts both the browser and the server event. The simplest fix is to stop firing those two events from the browser and let RetaFunnel send them.

Spend and names. With the same token RetaFunnel also pulls campaign, ad set and ad names and daily spend every 6 hours for the ids it has seen in your traffic (the Ads page). That is why the token needs ads_read.

Rotating the token, and what happens when it stops working#

To rotate: generate a new token on the system user (Step 3), paste it into the System user token field, Save. The old token can then be revoked in Business settings. Nothing else changes.

Tokens with expiration "Never" do not expire by themselves, but they stop working when the system user is deleted, the app is removed from the portfolio, the asset assignment is removed, or Meta forces a reset after a security event. When that happens:

• The Meta card shows the badge error and a line "Last error: …" with Meta's message (usually Error validating access token or Invalid OAuth access token).
• Segment syncs and Custom Audience updates stop. The people who entered a segment in the meantime are remembered as pending and are sent at the first successful sync after you fix the token.
• Standard events (Lead, Schedule, Purchase) are only looked up three hours back, so what happened during a longer outage is not resent to Meta. Your RetaFunnel reports are unaffected; only Meta's optimisation misses those events.

Check the Audiences page once a week: the sync log is the quickest way to notice a broken connection.

Common errors and the fix#

Privacy#

• Emails and phone numbers are hashed (SHA-256 of the lowercase email, and of the phone in international format) in the visitor's browser before they reach RetaFunnel, and are sent to Meta hashed. Raw values are stored only if you switch on "Allow raw PII" on the site, and even then they never leave encrypted storage towards Meta.
• Meta's own ids (fbp, fbc), IP address and user agent are sent because Meta needs them to recognise a browser. Under consent mode auto or strict they exist only after the visitor accepts cookies; before that, the visit is measured anonymously and cannot be sent to Meta at all. Under implied they are captured from the first page view.
• Test sessions, dry runs and the demo workspace never reach Meta.
• Disconnecting (button at the bottom of the Meta card) deletes the token immediately. Audiences already created in your ad account stay there; delete them in Ads Manager if you want.

Technical reference for developers: Integrations.