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.

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 permission.
  • Ads Management Standard Access feature.
  • Depending on event types, you need to have advanced access to page_events permission for Messenger or WhatsApp events.

Partner Onboarding

If you are partner integration as a platform, refer to the following developer document for the available onboarding methods.

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.

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:

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>"
}

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

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 Conversion 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.

See Also

• Conversions API Overview
• Using the Conversions API
• Conversions API Parameters
• Best Practices
• Messaging Events API
• WhatsApp Business Platform (On Premise or Cloud API) with Business API versions 2.45.1 and beyond