Conversions API for Business Messaging

The Conversions API enables advertisers to send web, app, physical store and business messaging events to Meta through a single endpoint rather than across multiple sources. This consolidation can simplify an advertiser’s tech stack and create a more comprehensive view within Meta Events Manager by using datasets..

This documentation provides guidance for integrating business messaging events to the Conversions API. The benefits of using the Conversions API for business messaging include (but are not limited to):

See outcomes directly in Ads Manager reporting: Advertisers can easily understand click to message campaign results based on the outcomes that matter directly on Meta surfaces, for example, number of purchases and cost per purchase, rather than conversations started.
Simplify data integration: One API to ingest and share data across multiple messaging platforms (Messenger, WhatsApp) and channels (website, app, stores, messaging).
Improve partner measurement: Enable click to message campaign attribution directly on partner dashboards through Ads Insights API.

Prerequisites

Dataset

Business messaging events sent through the Conversions API must be associated with a dataset.

Datasets allow advertisers to connect and manage event data from web, app, store and business messaging event sources to the Conversions API. Datasets may show event data from any of these integrations that you choose to set up:

Meta Pixel (website events)
App Events API (app events, including Facebook SDK for iOS or Android, mobile measurement partners (MMPs))
Offline Conversions API (Meta’s legacy API for offline events)

Datasets enable you to view all customer activities from a single interface. They also allow you to reduce the effort to build and maintain multiple API integrations.

In Events Manager, advertisers have different options to create a dataset depending on their starting point. Or you can create a brand new dataset in Events Manager by linking during offline event set creation or through an existing mobile app or during messaging event set creation information. Note that linking a dataset to an application is required before sending mobile app events to the Conversions API and only one application can be linked to a dataset. See more details and instructions here.

Permissions

To implement a direct integration as an advertiser, please follow the instructions here for prerequisites and permissions.
To implement a partner platform integration, you need to have:
- Advanced access to ads_read, ads_management, pages_messaging, whatsapp_business_messaging, pages_show_list and instagram_manage_messages permissions.
- Ads Management Standard Access feature.
- Depending on event types, you need to have advanced access to page_events permission for Messenger or WhatsApp events or instagram_manage_events for Instagram Direct.

Partner Onboarding

If you are implementing a partner integration as a platform, you can use either the Facebook Login for Business (recommended) or Meta Business Extension onboarding methods.

Please refer to the Conversions API for Business Messaging Guidebooks, containing integration guides with step-by-step instructions.

Dataset API for Messaging and WhatsApp

The Dataset API is used to retrieve the dataset_id that is attached to the given page. This dataset_id is used later in the Conversions API. To be able to use the Dataset API, you will need page_events permission for Messenger or WhatsApp events granted to your app by your client through Facebook Login for Business or Meta Business Extension.

In order to retrieve the dataset_id, you need to make a GET call to the Dataset API with the page_id and access_token. See the sample call below:

https://graph.facebook.com/v16.0/{PAGE_ID}/dataset?access_token={TOKEN}

The response will be an id, which represents the dataset_id. Using this and the access token received previously, you can now call the Conversions API to send messaging events to Meta.

Dataset API for Instagram

The Dataset API is used to retrieve the dataset_id that is attached to the given page. This dataset_id is used later in the Conversions API. To be able to use the Dataset API, you will need instagram_manage_events permission granted to your app by your client through Facebook Login for Business or Meta Business Extension.

In order to retrieve the dataset_id, you need to make a GET call to the Dataset API with the ig_user_id and access_token. Here's a sample call:

https://graph.facebook.com/v16.0/{IG_USER_ID}/dataset?access_token={TOKEN}

The response will be an id, which represents the dataset_id. Using this and the access token received previously, you can now call the Conversions API to send messaging events to Meta.

Configuration

Set Up Business Messaging Event Parameters

You can refer here to the current set of parameters that can be sent over the Conversions API. For sending business messaging events, the following fields can be shared in the User Data payload for different messaging platforms:

Platform	Parameter	Descriptoon
Messenger	`page_id`	Required for Messenger Facebook Page ID that is associated with the business.
Messenger	`page_scoped_user_id`	Required for Messenger Users who interact with Pages are identified by Page-Scoped User IDs (PSID). PSID can be obtained from this webhook.
WhatsApp	`page_id`	Required for WhatsApp Facebook Page ID that is associated with the Whatsapp business.
WhatsApp	`ctwa_clid`	Required for WhatsApp `ctwa_clid` is only available from the referral object under messages webhook on Business API versions 2.45.1 and beyond (On Premise) or Cloud API.
Instagram	`ig_account_id`	Required for Instagram Instagram Account ID that is associated with the business.
Instagram	`ig_sid`	Required for Instagram Users who interact with Instagram are identified by Instagram-Scoped User IDs (IGSID). IGSID can be obtained from this webhook.

Sending Events

To send new events, make a POST request to the Conversions API from this path:

https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}

When you post to this edge, Meta creates new business messaging events. For more details, please refer to the following developer document.

Here is an overview of how the parameters fit into the overall schema in the payload.

For Messenger events:

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "messenger",
      "user_data": {
        "page_id": <PAGE_ID>,
        "page_scoped_user_id": <PSID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

For WhatsApp events:

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "whatsapp",
      "user_data": {
        "page_id": <PAGE_ID>,
        "ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a", // <CLICK_TO_WHATSAPP_CLICK_ID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

For Instagram events:

Sample CTD CAPI Request

POST /{dataset_id}/events

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "instagram",
      "user_data": {
        "ig_account_id": <IG_ACCOUNT_ID>,
        "ig_sid": <IGSID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

Troubleshooting

Use the Test Events tool in Events Manager for testing:

Go to Events Manager, select a dataset linked with page
Click the Test Events tab
Select the marketing channel and messaging channel
Click the Graph API Explorer button
Graph API Explorer will be populated with the prefilled payload
Click Submit button

Video Walkthrough

See this video for a step-by-step explantion of how to implement an integration.

Something Went Wrong

We're having trouble playing this video.

Learn more

Frequently Asked Questions

What type of messaging events does the Conversions API for Business Messaging support?

A: The Conversions API for Business Messaging currently only supports leads submitted and purchase events for business messaging. Please note that messaging events should only represent customer interactions that occur in the messaging thread, not conversions that occur on other channels like websites. You can easily distinguish your events by choosing the corresponding action source during your integration process.

Is there guidance from Meta to keep the same or use different apps for different Conversions API integrations?

A: It is a best practice that a partner should use one app, so that Meta can identify all the events sent from the partner. If you are a partner who already has multiple apps, ensure the partner_agent is set to the partner agent name assigned to you. Speak with your Meta representative if you are unsure.

If a conversion occurs outside of the message thread (for example, on my website or app), how do we pass the events to Meta?

A: If a conversion happens outside of the messaging thread, you should still send that event back to Meta using the relevant Conversions API product. For instance, if a conversion happens on your website, use the Conversions API for web. If conversion happens on your app, use the Conversions API for app events. The event will still be attributed to the click ID for the Conversions API for web. The full list of parameters can be found here.

Does the Conversions API enable optimization for ads that click to message?

A: The Conversions API enables access to purchase optimization for ads that click to Messenger only, but is not available for WhatsApp ad optimization at this time. For ads that click to WhatsApp, you can optimize your ad campaigns to drive more conversations.

Can I reuse the existing dataset for the Conversions API for business messaging?

A: Yes, we support linking with existing dataset, you can refer to the available options to decide the right option for your business.

If I’m using Conversions API for Website today, will adding business messaging to the same integration interfere with my existing integration?

A: There is no risk to adding business messaging to your existing CAPI integration. Attribution is based on the page/dataset id and is not related to the app id.

How many datasets can be linked to a page?

A: You can only link one dataset to a page.

Do I need to deduplicate events before sending them over Conversions API for Business Messaging?

A: Meta does not assist with deduplicating events for Conversions API for Business Messaging so we highly encourage advertisers to perform deduplication before sending them over Conversions API for Business Messaging.