Facebook Conversions Destination

Updated

About this integration

The Facebook Conversions API enables businesses to send events that are linked to a pixel and processed in the same manner as browser pixel events directly to Facebook. These events help you measure, report, and optimize activities so you gain valuable insights into user behavior and can improve the effectiveness of your Facebook marketing efforts.

Getting started

To set up the Facebook Conversions API destination, you’ll need a Facebook user access token from your business account. See the section below for help creating or getting a token.

  1. Go to the Data Pipelines tab and click Connections.

  2. Click Add New under Destinations.

  3. Select the Facebook Conversions API destination.

  4. (Optional) Select the sources that you want to connect to this destination. You can always connect sources to your destination later. We’ll only show you eligible sources.

  5. Configure your destination.

    1. Pixel Id: Your Facebook Pixel ID. Note: You may also use a dataset ID here if you have configured a dataset in your Facebook Events Manager.

    2. System User Access Token: The access token for the system user, obtained in the Facebook Business account. Learn more about obtaining the access token

    3. Test Event Code: Use this field to specify that events should be test events rather than actual traffic. You can find your Test Event Code in your Facebook Events Manager under the "Test events" tab. You'll want to remove your Test Event Code when sending real traffic through this integration.

    Setup your destination
    Setup your destination

  6. Click Enable Destination.

Get your Facebook system user access token

To send offline conversions with a system user access token, you must first create a system user in Facebook. You can create a system user in the Business Settings section of your Facebook Business Manager account.

  1. Go to your Facebook Business account.
  2. Go to Business Settings > Users > System users.
  3. Click Generate New Token, select your app from the dropdown, and select the ads_management permission.
  4. Click Generate Token
  5. Copy this token to the System User Access Token field in your destination settings.

Actions

When you’re done setting up your destination, you can go to the Actions tab to see how we map source events to your destination.

You may need to add actions for this destination

While we often have default triggers for actions, we don't always add those actions as defaults. You may need to add actions to make sure that you're sending all the data that you want to send to your destination. See our actions page for help setting up actions.

ActionDefault TriggerDescription
Purchase

type = “track” and
event = “Order Completed”

Send event when a user completes a purchase
Initiate Checkout

type = “track” and
event = “Checkout Started”

Send event when a user enters the checkout flow
Add to Cart

type = “track” and
event = “Product Added”

Send event when a user adds a product to the shopping cart
View Content

type = “track” and
event = “Product Viewed”

Send event when a user views content or a product
Search

type = “track” and
event = “Products Searched”

Send event when a user searches content or products
Page View

type = “page”

Send a page view event when a user lands on a page
Custom EventSend a custom event

Data Structure

You’ll need to set up the data structure you will send with each action. On an action page, locate the section titled Data Structure. The first field you need to map is called Action Source.

A screenshot of the top of an Action page. At the top, the action selected is Purchase. Under that, the trigger specifies type is track and track event name is order completed. Under that is Data Structure. The first value field on the left is blank, and this is where you'd specify the value of the Action Source, the field on the right. The value and field are highlighted in a red rectangle.
A screenshot of the top of an Action page. At the top, the action selected is Purchase. Under that, the trigger specifies type is track and track event name is order completed. Under that is Data Structure. The first value field on the left is blank, and this is where you'd specify the value of the Action Source, the field on the right. The value and field are highlighted in a red rectangle.

The Action Source takes a variety of values, like app or website (Scroll down to action_source for options). Each source requires a different set of parameters for you to send data to Facebook’s Conversion API. For instance, if your action source is app, you’ll need to configure these fields. You can find required fields for all sources in Facebook’s Conversion API docs.

FAQ & Troubleshooting

Other Standard Events

If you want to send Facebook standard events that we don’t have ready-made actions for, you can use the Custom Event action. For example, if you want to send a CompleteRegistration event, you would create a custom event action, set up your trigger criteria for completed registrations, and enter “CompleteRegistration” as the Event Name. When you set up custom actions, you can add fields you expect to send in events, like content_name and currency.

Mapped Data and Automatically Hashed Fields (PII)

We automatically map user data fields to their corresponding parameters as expected by the Conversions API before we send data to Facebook. Facebook uses shorthands for these fields in their API. We use the full names for clarity, but we map to the appropriate fields in Facebook. For example we use Email to represent em in Facebook.

Facebook (Meta) requires that you hash personally identifiable information (PII) before sending it to the Conversions API. We automatically hash appropriate data for you before we send data to Facebook.

Customer.io Data FieldFacebook Conversions API ParameterAutomatically Hashed
External IDexternal_id
Emailem
Phoneph
Genderge
Date of Birthdb
Last Nameln
First Namefn
Cityct
Statest
Zip Codezp
client_ip_addressclient_ip_address
client_user_agentclient_user_agent
fbcfbc
fbpfbp

 We automatically hash the External ID

Facebook recommends that you hash external IDs, so that external IDs match across Facebook Pixel and Facebook Conversions API if you use external IDs for deduplication.

Server Event Parameter Requirements

Facebook requires the action_source event parameter, which specifies where conversions occur, for all events sent to the Facebook Conversions API. If action_source is set to website, then the client_user_agent and the event_source_url parameters are also required. Events sent to the Conversions API that don’t meet this requirement may not be available for optimization, targeting, or measurement.

Verify Events in Facebook

When you start sending events, you should start seeing them within twenty minutes. To confirm that Facebook received your events:

  1. Go to the Events Manager.
  2. Click the pixel corresponding to your conversion events.
  3. In the Overview tab, look for events where the Connection Method is Server.
Copied to clipboard!
  Contents
Is this page helpful?