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):
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:
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 .
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:
ads_read
, ads_management
, pages_messaging
, whatsapp_business_messaging
, pages_show_list
and instagram_manage_messages
permissions.page_events
permission for Messenger or WhatsApp events or instagram_manage_events
for Instagram Direct.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.
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_eventspermission 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 tokenreceived previously, you can now call the Conversions API to send messaging events to Meta.
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.
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 |
|
Required for Messenger Facebook Page ID that is associated with the business. |
Messenger |
Required for Messenger Users who interact with Pages are identified by Page-Scoped User IDs (PSID). PSID can be obtained from this webhook . |
|
|
|
Required for WhatsApp Facebook Page ID that is associated with the Whatsapp business. |
|
|
Required for WhatsApp |
|
|
Required for Instagram Instagram Account ID that is associated with the business. |
|
|
Required for Instagram Users who interact with Instagram are identified by Instagram-Scoped User IDs (IGSID). IGSID can be obtained from this webhook . |
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>" }
Use the Test Events tool in Events Manager for testing:
See this video for a step-by-step explantion of how to implement an integration.
What type of messaging events does the Conversions API for Business Messaging support?
A: The Conversions API for Business Messaging now supports the following types of 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.