Conversions API for CRM: Integrate as a Platform

Partners may consider offering Conversions API for CRM events as a service. This allows your clients to upload lead events generated via their Facebook/Instagram lead ads (instant forms) from their respective CRM systems, and use the Conversion Leads performance goal in ads which may yield higher quality leads that are more likely to convert.

Prerequisites

To plan your project, you may use the estimated timeline as a guideline. Note:

1. Integration stage, or the actual development on the partner side, may take about 3-7 weeks. Post integration, for an advertiser to get onboarded till running fully optimized Conversions Lead Ads campaigns, it may take 3-4 weeks.
2. The below timeline is based on historical data. The actual timeline may vary based on available resources, speed of issue resolution, etc.

*Advertisers may run Conversions Leads performance campaigns during the learning period, but will not benefit from the full performance lift until it is complete.

Integration Guide

Step 1: Prerequisites

If you have not yet been offering the Conversions API as a service for web, app, offline or business messaging events, please ensure that you have set up the below assets:

• Business Manager
• A Meta app. Please note that your app needs to go through App Review. During that process, you must obtain Advanced Access for ads_management, pages_read_engagement, ads_read, pages_show_list, business_management and Ads Management Standard Access. Please find below for more guidance on how to do so
• Meta CRM Dataset (previously referred to as pixel). A CRM dataset is required for the Conversions API for CRM integration. The CRM dataset will inform the system that CRM events will be uploaded to it and add a Conversion Leads performance workflow to the dataset which optimizes for lead quality.

Step 2: Authentication

Partners have the following two authentication options for datasets not managed by you:

Option 1 - Meta Business Extension (MBE, preferred)

MBE provides an endpoint to retrieve system user access tokens created in the advertiser’s Business Manager. Complete all the requirements for implementing MBE.

Ensure that you:

• obtain manage_business_extension for your app — This is a private permission that requires your Meta representative to add your app to the allow list
• set the value of the channel parameter in setup configuration object as CONVERSIONS_API
• are able to receive the webhook response at the completion of onboarding
• use the access token returned via MBE and convert it into a System User Access Token by making an additional API call
• save a copy of external_business_id, pixel_id (that is, the dataset ID), business_id and system user access token in your system
• get approval for your MBE integration

Option 2 - Client System User Access Token

With this option, partners may have the advertisers:

• manually create a system user access token via the Conversions API inside Settings in Meta Events Manager (EM)
• share pixel_id (that is, the dataset ID), business_id and system user access token with the partner and save a copy of it

Step 3: API integration

Partners then call the Conversions API endpoint to send the event payload. Key steps to take note of:

Send Lead ID (preferred) or Custom Parameters

lead_id is a predefined ID associated with leads that are generated from lead ads campaigns run on Facebook or Instagram. There are various ways to find lead ID from Meta. Partners are recommended to use Webhook or Graph API bulk read for finding lead ID.

Add partner_agent string for attribution

Send a unique partner_agent string together with the payload. If applicable, work with your dedicated Meta representative to decide on a suitable agent string. Use the same agent string if you are already sending one via Conversions API for web, offline, app or business messaging events.

Example

If your platform identifier is datapartner, this would be a sample event payload sent on behalf of your client:

{
    "event_name": "my lead stage",
    "event_time": 1617693833,
    "user_data": {
        "lead_id": 1234567890123456
    },
    "action_source": "system_generated",
    "custom_data": {
        "lead_event_source": "Salesforce",
        "event_source": "crm"
    },
   "partner_agent": "datapartner"
}

Alternatively, if you are not able to find lead_id, you may use customer parameters instead and below would be a sample event payload sent on behalf of your client:

{
    "event_name": "my lead stage",
    "event_time": 1617693833,
    "user_data": {
        "em": 62a14e44f765419d10fea99367361a727c12365e2520f32218d505ed9aa0f62f
        "ph": e323ec626319ca94ee8bff2e4c87cf613be6ea19919ed1364124e16807ab3176
        "fbc": fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890
    },
    "action_source": "system_generated",
    "custom_data": {
        "lead_event_source": "Salesforce",
        "event_source": "crm"
    },
   "partner_agent": "datapartner"
}

Use the Correct Event Payload

For Conversions API for CRM integration, partners should use the above structure for event payload to ensure events can be successfully received. Note that this is different from Conversions API for web, offline, app or business messaging events.

Make sure that you use the correct value for action_source of Conversions API for CRM events , that is, action_source = system_generated

Send All Lead Stages, Including Initial Lead Stage

Make sure to send all stages of leads as they are updated. This means, there would be multiple events on the same lead_id as the lead moves in the lead funnel stage.

Ensure that you send the first lead stage (that is, raw lead event) as it will let the system know that the lead was received and processed.

You should send a minimum of two stages for events from your sales funnel, including the raw lead event. It is recommended to send three stages or more if possible.

Mapping to CRM Lead Stages

If your advertisers are using different CRM systems, make sure you are able to map the parameters from different data sources to lead_id, event_name and event_time respectively.

One possible solution is to incorporate a UI/UX feature on your advertiser-facing portal to allow advertisers to map parameters from different CRMs to lead_id, event_name and event_time themselves.

Other best practices include the below:

1. Upload data at least once a day. Ideally upload data in real-time, but you may employ hourly or daily batching methods if a real-time integration is not feasible.
2. Each batch can include up to 1,000 events. If there is an error in the batch, the whole batch will be discarded so we highly recommend employing small batches and adding logic for retrying attempts.
3. You can backfill your data for up to 7 days in the past. The time difference is calculated between event_time and upload_time. Backfilling some data may speed up the training process.
4. Ensure that your event_time values are after the lead generation timestamp, otherwise your events may be discarded.
5. Log error messages from the CAPI call and create alerts if there are issues. Exception handling for these errors would also be a good idea.
6. Store lead_id whenever possible in your system together with other information such as the leads’ details, lead stage, etc.

Post Integration

After you have successfully completed the API integration, we recommend that you select some suitable advertisers to conduct tests first before opening your solution to all advertisers.

Select Suitable Advertisers

It is important that you select suitable advertisers to use the Conversions API for CRM. Below are some guidelines for such advertisers:

• Use Facebook/Instagram Lead Ads (Instant Forms)
• Generate at least 200 leads per month
• The lead stage the advertiser wants to optimize for
  • occurs within 28 days of leads being generated
  • has a conversion rate between 1% - 40%
• Care about lead quality

Guidelines for Your Advertisers

In order to onboard your advertisers successfully to Conversions API for CRM and serve them well post-onboarding, we recommended becoming familiar with the advertiser journey to be able to guide your advertisers through the process.

Step 1: Connect CRM

a) Create a CRM dataset: To verify if the CRM dataset is set up correctly, go to Events Manager > Datasource > Settings and you will see a Conversion Leads Section if it is a CRM dataset.

b) Connect to the partner system: Allow your advertiser to connect to your system and start sending in CRM events.

c) Send a CRM event: To pass Data Verification checks, the dataset must meet all of the requirements before proceeding to the next step. To confirm if this stage is successful, check in Events Manager if the status moves down to “Configure Sales Funnel”.

If an advertiser is not able to proceed beyond this step:

• Check for errors in the Events Manager Diagnostic tab for the CRM Dataset.
• Check that enough events are being uploaded to match with leads generated on Facebook. For example, if the advertiser generates 100 leads in one day we would expect all 100 leads to have uploaded events to match to them. You should reach at least 60% of lead coverage, which is defined as the percentage of leads that have matching events uploaded to Meta.
• Check that a minimum of two stages for events from the advertiser’s sales funnel is being sent, including the first lead stage (that is, raw lead event). However, we recommend at least three stages if possible. For example, only sending in the “Sale” event will not be enough; make sure the advertiser sends in previous stages as well.
• Make sure data has all the required parameters and in the correct format highlighted in this guide. Sending data in other formats will trigger an error.

Step 2. Configure sales funnel

Step 3. Funnel analysis and learning phase: An integration will need to meet the following criteria:

• An optimization stage with a conversion rate between 1-40%
• Conversion window of the optimization day is 28 days or less

After the integration is completed, there is a 3-4 week learning phase required where the model will need to use the data that is being sent back to optimize the model. Upon successful completion of the integration, a confirmation modal will appear in Events Manager to notify you that the process is complete.

Step 4: Run fully optimized Conversions Lead Ads campaigns via Ads Manager using the CRM dataset from above.

Note: Remind the advertiser not to change datasets after they have completed the integration. Changing datasets will start a new integration and restart the learning process.