Conversions API für Business-Messaging
Mit der Conversions API können Werbetreibende Web-Events, App-Events, Events in physischen Stores und Business-Messaging-Events über einen einzigen Endpunkt statt über mehrere Quellen an Meta senden. Diese Konsolidierung kann die technischen Anforderungen für Werbetreibende vereinfachen. Außerdem wird mit der Verwendung von Datensätzen eine umfassendere Ansicht im Meta Events Manager erstellt.
Diese Dokumentation enthält eine Anleitung zur Integration von Business-Messaging-Events in die Conversions API. Die Nutzung der Conversions API für Business-Messaging bietet unter anderem die folgenden Vorteile:
- Ergebnisse direkt in Werbeanzeigenmanager-Berichten sehen: Werbetreibende können die Ergebnisse von Click-to-Message-Kampagnen leicht verstehen, da relevante Ergebnisse direkt in Meta-Oberflächen angezeigt werden, z. B. Anzahl der Käufe und Kosten pro Kauf, statt gestartete Unterhaltungen.
- Datenintegration vereinfachen: Eine API, um Daten über mehrere Messaging-Plattformen (Messenger, WhatsApp) und Kanäle (Website, App, Stores, Messaging) hinweg zu erfassen und zu teilen.
- Partnermessungen verbessern: Click-to-Message-Kampagnen können über die Ads Insights API direkt in Partner-Dashboards zugeordnet werden.
Voraussetzungen
Datensatz
Über die Conversions API gesendete Business-Messaging-Events müssen mit einem Datensatz verbunden sein.
Datensätze ermöglichen es Werbetreibenden, Event-Daten aus Web-, App-, Store- und Business-Messaging-Event-Quellen mit der Conversions API zu verbinden und zu verwalten. Datensätze können Event-Daten aus allen folgenden Integrationen anzeigen, die du einrichten kannst:
- Meta-Pixel (Website-Events)
- App Events API (App-Events, einschließlich Facebook-SDK für iOS oder Android, Mobile Measurement Partner (MMPs))
- Offline Conversions API (Metas alte API für Offline-Events)
Datensätze ermöglichen es dir, alle Aktivitäten von Kund*innen in einer einzigen Oberfläche anzuzeigen. Außerdem reduzieren sie den Aufwand, der mit dem Aufbau und der Pflege mehrere API-Integrationen verbunden ist.
Im Events Manager haben Werbetreibende abhängig von ihrem Ausgangspunkt verschiedene Optionen zum Erstellen eines Datensatzes. Alternativ kannst du einen brandneuen Datensatz im Events Manager erstellen, und zwar durch Verlinken beim Erstellen von Offline-Event-Sets oder über eine vorhandene mobile App oder während der Erstellung von Messaging-Event-Sets. Beachte, dass die Verknüpfung eines Datensatzes mit einer Anwendung erforderlich ist, bevor mobile App-Events an die Conversions API gesendet werden, und dass nur eine Anwendung mit einem Datensatz verknüpft werden kann. Weitere Details und Anweisungen findest du hier.
Berechtigungen
Um als Werbetreibender eine direkte Integration zu implementieren, befolge bitte die Anweisungen hier zu den Voraussetzungen und Berechtigungen.
Um eine Partnerplattform-Integration zu implementieren, benötigst du Folgendes:
- Erweiterten Zugriff auf die Berechtigungen
ads_read,ads_management,pages_messaging,whatsapp_business_messaging,pages_show_listundinstagram_manage_messages - Das Feature Standardzugriff für das Anzeigenmanagement
- Je nach Event-Typ benötigst du erweiterten Zugriff auf die Berechtigung
page_eventsfür Messenger- oder WhatsApp-Events oderinstagram_manage_eventsfür Instagram Direct.
Partner-Onboarding
Wenn du deine Partnerintegration als Plattform implementierst, kannst du entweder die Onboarding-Methode Facebook Login for Business (empfohlen) oder Meta Business Extension verwenden.
Bitte lies die Conversions API for Business Messaging Guidebooks, die Integrationsanleitungen mit Schritt-für-Schritt-Anweisungen enthalten.
Dataset API für Messaging und WhatsApp
Die Dataset API wird verwendet, um die dataset_id abzurufen, die an die angegebene Seite angehängt ist. Diese dataset_id wird später in der Conversions API verwendet. Um die Dataset API verwenden zu können, müssen Kund*innen deiner App über Facebook Login for Business oder die Meta Business Extension die Berechtigung page_events für Messenger- oder WhatsApp-Events erteilen.
Um die dataset_id abzurufen, musst du einen GET-Aufruf mit der page_id und dem access_token an die Dataset API senden. Nachstehend findest du einen Beispielaufruf:
https://graph.facebook.com/v16.0/{PAGE_ID}/dataset?access_token={TOKEN}
Die Antwort ist eine ID, die die dataset_id repräsentiert. Mit dieser ID und dem zuvor erhaltenen Zugriffsschlüssel kannst du jetzt die Conversions API aufrufen, um Messaging-Events an Meta zu senden.
Dataset API für Instagram
Die Dataset API wird verwendet, um die dataset_id abzurufen, die an die angegebene Seite angehängt ist. Diese dataset_id wird später in der Conversions API verwendet. Um die Dataset API verwenden zu können, müssen Kund*innen deiner App über Facebook Login for Business oder die Meta Business Extension die Berechtigung instagram_manage_events erteilen.
Um die dataset_id abzurufen, musst du einen GET-Aufruf mit der ig_user_id und dem access_token an die Dataset API senden. Hier ein Beispielaufruf:
https://graph.facebook.com/v16.0/{IG_USER_ID}/dataset?access_token={TOKEN}
Die Antwort ist eine ID, die die dataset_id repräsentiert. Mit dieser ID und dem zuvor erhaltenen Zugriffsschlüssel kannst du jetzt die Conversions API aufrufen, um Messaging-Events an Meta zu senden.
Konfiguration
Parameter für Business-Messaging-Events einrichten
Hier findest du den aktuellen Satz von Parametern, die über die Conversions API gesendet werden können. Zum Senden von Business-Messaging-Events können die folgenden Felder in der Nutzungsdaten-Payload für verschiedene Messaging-Plattformen geteilt werden:
| Plattform | Parameter | Beschreibung |
|---|---|---|
Messenger |
| Erforderlich für Messenger Facebook-Seiten-ID, die mit dem Unternehmen verknüpft ist. |
Messenger | Erforderlich für Messenger Nutzer*innen, die mit Seiten interagieren, werden durch seitenspezifische Nutzungs-IDs (Page-Scoped User ID, PSID) identifiziert. Die PSID kann von diesem Webhook abgerufen werden. | |
| Erforderlich für WhatsApp Facebook-Seiten-ID, die mit dem WhatsApp-Unternehmen verknüpft ist. | |
| Erforderlich für WhatsApp Die | |
| Erforderlich für Instagram Instagram-Konto-ID, die mit dem Unternehmen verknüpft ist. | |
| Erforderlich für Instagram Nutzer*innen, die mit Instagram interagieren, werden durch Instagram-spezifische Nutzungs-IDs (Instagram-Scoped User ID, IGSID) identifiziert. Die IGSID kann von diesem Webhook abgerufen werden. |
Senden von Events
Um neue Events zu senden, stelle aus diesem Pfad eine POST-Anfrage an die Conversions API:
https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}
Wenn du in dieser Edge postest, erstellt Meta neue Business-Messaging-Events. Mehr dazu findest du im folgenden Entwicklungsdokument.
Hier findest du eine Übersicht dazu, wie sich die Parameter in das Gesamtschema in der Payload einfügen.
Für 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>"
}Für 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>"
}Für Instagram-Events:
CTD-CAPI-Beispielanfrage
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>"
}Problembehebung
Verwende das Tool zum Testen von Events im Events Manager, um Tests durchzuführen:
- Rufe den Events Manager auf und wähle einen mit der Seite verknüpften Datensatz aus.
- Klicke auf den Tab „Events testen“.
- Wähle den Marketingkanal und den Messaging-Kanal aus.
- Klicke auf den Button Graph API Explorer.
- Graph API Explorer wird mit der vorgefertigten Payload gefüllt.
- Klicke auf den Button „Senden“.
Video-Anleitung
In diesem Video wird die Implementierung einer Integration Schritt für Schritt erläutert.
Häufig gestellte Fragen
Welche Art von Messaging-Events unterstützt die Conversions API für Business-Messaging?
A: Die Conversions API für Business-Messaging unterstützt derzeit nur gesendete Leads und Kauf-Events für Business-Messaging. Bitte beachte, dass Messaging-Events nur Kund*innen-Interaktionen repräsentieren sollten, die im Messaging-Thread stattfinden, und nicht Conversions, die auf anderen Kanälen wie Websites stattfinden. Du kannst deine Events leicht unterscheiden, indem du während des Integrationsprozesses die entsprechende Handlungs-Quelle auswählst.
Gibt es eine Empfehlung von Meta, ob für verschiedene Integrationen der Conversions API dieselbe App oder verschiedene Apps verwendet werden sollten?
A: Nach Möglichkeit sollten Partner nur eine App verwenden, damit Meta alle vom Partner gesendeten Events identifizieren kann. Wenn du ein Partner bist, der bereits mehrere Apps hat, stelle sicher, dass der Parameter „partner_agent“ auf den Namen des Partnermitarbeiters festgelegt ist, der dir zugewiesen wurde. Wende dich an deine*n gewählte*n Meta-Vertreter*in, wenn du dir unsicher bist.
Wie gebe ich Events an Meta weiter, wenn eine Conversion außerhalb des Messaging-Threads stattfindet (z. B. auf meiner Website oder in meiner App)?
A: Wenn eine Conversion außerhalb des Messaging-Threads stattfindet, solltest du dieses Event trotzdem mit dem entsprechenden Conversions API-Produkt an Meta zurücksenden. Wenn zum Beispiel eine Conversion auf deiner Website stattfindet, verwende die Conversions API für das Web. Wenn eine Conversion in deiner App stattfindet, verwende die Conversions API für App-Events. Das Event wird weiterhin der Klick-ID für die Conversions API für das Web zugeordnet. Die vollständige Liste der Parameter findest du hier.
Ermöglicht die Conversions API die Optimierung für Click-to-Message Ads?
A: Die Conversions API ermöglicht den Zugriff auf die Kaufoptimierung ausschließlich für Click-to-Messenger Ads. Die Optimierung von WhatsApp Ads ist derzeit nicht möglich. Für Click-to-WhatsApp Ads kannst du deine Werbekampagnen optimieren, um die Anzahl der Unterhaltungen zu steigern.
Kann ich den vorhandenen Datensatz für die Conversions API für Business-Messaging wiederverwenden?
A: Ja, wir unterstützen das Verlinken mit einem vorhandenen Datensatz. Sieh dir die verfügbaren Optionen an, um die richtige Option für dein Unternehmen zu ermitteln.
Wenn ich aktuell die Conversions API für Websites verwende, wird meine bestehende Integration dann durch das Hinzufügen von Business-Messaging zur selben Integration beeinträchtigt?
A: Es besteht kein Risiko, wenn du Business-Messaging zu deiner bestehenden CAPI-Integration hinzufügst. Die Attribution basiert auf der Seiten-/Datensatz-ID und steht in keinem Zusammenhang mit der App-ID.
Wie viele Datensätze können mit einer Seite verlinkt werden?
A: Du kannst nur einen Datensatz mit einer Seite verlinken.
Muss ich Events deduplizieren, bevor ich sie über die Conversions API für Business Messaging sende?
A: Meta bietet keine Unterstützung bei der Deduplizierung von Events für die Conversions API für Business Messaging. Daher raten wir Werbetreibende dringend, die Deduplizierung durchzuführen, bevor sie Events über die Conversions API für Business-Messaging senden.