WhatsApp Konversionsereignisse senden in AWS Nachrichten für Endbenutzer in sozialen Netzwerken

Wenn Sie Kampagnen mit der Option „WerbeanzeigenMeta, auf die geklickt wird WhatsApp“ schalten, können Sie Konversionsereignisse (wie Käufe, Leads oder Aufrufe von Inhalten) Meta zur Anzeigenzuweisung und -optimierung zurücksenden. Senden Sie diese Ereignisse direkt über Social Media für AWS Endnutzer, ohne die Meta Graph-API aufrufen zu müssen.

AWS End User Messaging Social bietet zwei APIs für diesen Workflow:

• CreateWhatsAppDataset— Erstellt den Conversion-Datensatz für Ihr WhatsApp Geschäftskonto (WABA) (oder ruft ihn ab). Ein Datensatz wird vom Container Meta verwendet, um Ihre Konversionsereignisse zu empfangen und zuzuordnen.

• SendWhatsAppConversionEvent— Sendet ein oder mehrere Konversionsereignisse an die Meta Conversion-API, wo sie dem Anzeigenklick zugeordnet werden, mit dem die WhatsApp Konversation gestartet wurde.

So funktioniert das Tracking von Konversionsereignissen

Der durchgängige Arbeitsablauf ist:

1. Ein Kunde klickt auf Ihre „Click to WhatsApp“ -Anzeige Meta und beginnt eine Konversation mit Ihrem Unternehmen.

2. Die eingehende Nachricht kommt an Ihrem konfigurierten Event-Ziel an (Amazon SNS-Thema EventBridge, Amazon oder Amazon Connect). Sie enthält eine ctwa_clid (Click-to-Click-ID), die den WhatsApp Anzeigenklick identifiziert. Ihre Anwendung muss diesen Wert erfassen und speichern.

3. Wenn eine Konvertierung stattfindet (z. B. wenn der Kunde einen Kauf tätigt), wird Ihre Anwendung SendWhatsAppConversionEvent mit den Ereignisdetails ctwa_clid und aufgerufen.

4. AWS End User Messaging Social leitet das Ereignis zur Zuordnung an die Meta Conversions-API weiter.

Das ctwa_clid ist im referral Objekt der Webhook-Nutzlast für eingehende Nachrichten enthalten, wenn ein Kunde eine Konversation über eine Anzeige beginnt. Das folgende Beispiel zeigt den relevanten Teil der Webhook-Nachricht:

{
  "messages": [
    {
      "from": "12345678",
      "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
      "referral": {
        "body": "This is a great product",
        "ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a",
        "headline": "Our new product",
        "source_id": "1234567890",
        "source_type": "ad",
        "source_url": "https://fb.me/AAAAA"
      },
      "text": {
        "body": "Can I learn more about your business?"
      },
      "timestamp": "1678189586",
      "type": "text"
    }
  ]
}

Speichern Sie den ctwa_clid Wert aus dem referral Objekt. Übergeben Sie ihn bei jedem Konversionsereignis, das Sie für diese Konversation senden. user_data Weitere Informationen zum Referral-Webhook finden Sie in der Meta Entwicklerdokumentation unter Webhooks-Komponenten.

Voraussetzungen

Bevor Sie Konvertierungsereignisse senden, benötigen Sie Folgendes:

• Ein WhatsApp Geschäftskonto (WABA), das mit Ihrem AWS Konto verknüpft ist.

• Eine aktive „Ads that Click to WhatsApp“ -Kampagne aufMeta.

• Ihre Anwendung muss den Webhook ctwa_clid aus dem Webhook für eingehende Nachrichten erfassen, wenn ein Kunde durch einen Klick auf eine Anzeige eine Konversation beginnt. Dieser Wert wird von generiert Meta und kann nicht erzeugt werden.

Wichtig

Wenn Sie Ihr WhatsApp Unternehmenskonto (WABA) vor dem 6. August 2026 verknüpft haben, müssen Sie den Anmeldevorgang wiederholen, um AWS End User Messaging Social die Erlaubnis zu erteilen, Konversionsereignisse zu senden. Folgen Sie den Schritten 1 bis 14 unter „Über die Konsole anmelden“ unter „Registrierung für“ und wählen Sie die vorhandene WABA und Telefonnummer aus WhatsApp, die bereits mit Ihrem Konto verknüpft sind. AWS Sie können dann die verbleibenden Schritte überspringen.

Schritt 1: Erstellen Sie einen Conversion-Datensatz

Bevor Sie Konversionsereignisse senden können, müssen Sie einen Conversion-Datensatz für Ihre WABA erstellen. Jede WABA hat genau einen Datensatz (dies wird von erzwungen). Meta Die Operation ist idempotent: Wenn ein Datensatz bereits existiert, wird die vorhandene Datensatz-ID zurückgegeben.

Im folgenden Beispiel wird der Datensatz für eine WABA erstellt oder abgerufen. waba-idErsetzen Sie es durch den ARN Ihres verknüpften WhatsApp Geschäftskontos (WABA) (z. B.). arn:aws:social-messaging:us-east-1:123456789012:waba/a1b2c3d4e5example

aws socialmessaging create-whatsapp-dataset \
    --region us-east-1 \
    --id waba-id

Die Antwort enthält die Datensatz-ID. Speichern Sie diesen Wert. Sie übergeben ihn jedes Mal als datasetId Parameter, wenn Sie ein Konvertierungsereignis senden.

{
    "datasetId": "123456789012345"
}

Schritt 2: Konvertierungsereignisse senden

Nachdem Sie einen Datensatz erstellt haben, können Sie Meta mithilfe der SendWhatsAppConversionEvent API Konversionsereignisse an ihn senden. Bei jedem Aufruf werden ein oder mehrere Ereignisse zur Zuordnung an die Meta Conversion-API übermittelt.

Der Eventinhalt, den Sie im event-data Parameter senden, folgt dem Meta Serverereignisformat der Conversions API. AWS End User Messaging Social leitet diesen Inhalt weiter an. Meta Eine vollständige Liste der Ereignisfelder finden Sie in der Referenz zu den Meta Serverereignisparametern in der Meta Entwicklerdokumentation.

Senden Sie ein Ereignis zur Kaufkonversion

Das folgende Beispiel meldet eine Purchase Konversion. Ersetzen Sie die Platzhalterwerte durch Ihre eigenen.

aws socialmessaging send-whatsapp-conversion-event \
    --region us-east-1 \
    --id waba-id \
    --dataset-id dataset-id \
    --event-data '{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": 1720000000,
            "action_source": "business_messaging",
            "messaging_channel": "whatsapp",
            "user_data": {
                "whatsapp_business_account_id": "meta-waba-id",
                "ctwa_clid": "click-id"
            },
            "custom_data": {
                "currency": "USD",
                "value": 99.99
            }
        }
    ]
}'

Die Antwort enthält eine Anforderungs-ID, die Ihre Einreichung identifiziert:

{
    "requestId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
}

Senden Sie ein Event zur Lead-Konvertierung

Non-purchase Ereignistypen wie „LeadSubmittedNicht erforderlichcustom_data“.

aws socialmessaging send-whatsapp-conversion-event \
    --region us-east-1 \
    --id waba-id \
    --dataset-id dataset-id \
    --event-data '{
    "data": [
        {
            "event_name": "LeadSubmitted",
            "event_time": 1720000000,
            "action_source": "business_messaging",
            "messaging_channel": "whatsapp",
            "user_data": {
                "whatsapp_business_account_id": "meta-waba-id",
                "ctwa_clid": "click-id"
            }
        }
    ]
}'

Senden Sie mehrere Ereignisse in einer Anfrage

Das data Array akzeptiert mehrere Ereignisse in einem einzigen Aufruf. Metaerlaubt bis zu 1.000 Ereignisse pro Anfrage.

aws socialmessaging send-whatsapp-conversion-event \
    --region us-east-1 \
    --id waba-id \
    --dataset-id dataset-id \
    --event-data '{
    "data": [
        {
            "event_name": "ViewContent",
            "event_time": 1720000000,
            "action_source": "business_messaging",
            "messaging_channel": "whatsapp",
            "user_data": {
                "whatsapp_business_account_id": "meta-waba-id",
                "ctwa_clid": "click-id"
            }
        },
        {
            "event_name": "Purchase",
            "event_time": 1720000500,
            "action_source": "business_messaging",
            "messaging_channel": "whatsapp",
            "user_data": {
                "whatsapp_business_account_id": "meta-waba-id",
                "ctwa_clid": "click-id"
            },
            "custom_data": {
                "currency": "USD",
                "value": 149.00
            }
        }
    ]
}'

Referenz zum Konvertierungsereignis

Der event-data Parameter ist ein JSON-Objekt mit einem data Array, das ein oder mehrere Ereignisobjekte enthält. In den folgenden Tabellen werden die am häufigsten verwendeten Felder für Konversionen nach dem Prinzip „Werbung, zu der geklickt wird WhatsApp“ beschrieben. Metaist die Informationsquelle für Eventinhalte. Die vollständige Spezifikation finden Sie in der Referenz zu den Meta Serverereignisparametern in der Meta Entwicklerdokumentation.

Erforderliche Event-Felder

Feld	Typ	Description
event_name	Zeichenfolge	Die Art der Konvertierung. Case-sensitive. Zu den üblichen Werten gehören PurchaseLeadSubmitted, undViewContent.
event_time	Zahl	Der Zeitpunkt, zu dem die Konvertierung stattgefunden hat, als Unix-Zeitstempel in Sekunden. Muss innerhalb der letzten 7 Tage liegen und nicht in der Zukunft.
action_source	Zeichenfolge	Der Wert muss business_messaging sein.
messaging_channel	Zeichenfolge	Der Nachrichtenkanal. Verwenden Sie whatsapp.
user_data	Objekt	Informationen, die verwendet wurden, um das Ereignis dem Klick auf die Anzeige zuzuordnen. Siehe Erforderliche Felder vom Typ user_data.

Erforderliche Felder vom Typ user_data

In der folgenden Tabelle werden die erforderlichen Felder im user_data Objekt beschrieben.

Feld	Typ	Description
whatsapp_business_account_id	Zeichenfolge	Ihre numerische Meta WhatsApp Geschäftskonto-ID (aus den Meta Unternehmenseinstellungen).
ctwa_clid	Zeichenfolge	Die WhatsApp Click-to-Click-ID aus dem Webhook für eingehende Nachrichten der Konversation, die mit der Anzeige gestartet wurde. Metavalidiert diesen Wert; er kann nicht erfunden werden.

Wichtig

Wenn Sie personenbezogene Daten (PII) wie E-Mail-Adressen oder Telefonnummern angeben, müssen Sie die Werte als SHA-256 Hashes angeben. user_data Metalehnt ungehashte PII ab. Der ctwa_clid Wert ist nicht gehasht.

Das custom_data-Objekt

Für Purchase Ereignisse müssen Sie das custom_data Objekt mit den folgenden Feldern angeben:

Feld	Typ	Description
currency	Zeichenfolge	Der ISO-4217-Währungscode (z. B.USD).
value	Zahl	Der monetäre Wert der Umrechnung.

Fehlerbehandlung

Da AWS End User Messaging Social Ihre Veranstaltungsinhalte weiterleitetMeta, tauchen die meisten Probleme mit Veranstaltungsinhalten als solche auf. InvalidParametersException Die Fehlermeldung enthält den Grund, der gemeldet wurdeMeta, z. B. durch einen unbekannten Veranstaltungsnamen, eine Uhrzeit außerhalb des zulässigen Zeitfensters, fehlende Währung für einen Kauf, ungehashte personenbezogene Daten oder eine ungültige Angabe. ctwa_clid

Fehler	HTTP-Status	Bedeutung
InvalidParametersException	400	Die Anfrage oder der Veranstaltungsinhalt war ungültig. Die Fehlermeldung beschreibt das spezifische Problem.
ResourceNotFoundException	404	Die angegebene WABA oder der angegebene Datensatz konnte nicht gefunden werden.
AccessDeniedByMetaException	403	Metahat die Anfrage aufgrund von Berechtigungen abgelehnt (z. B. fehlt dem zugrunde liegenden Meta Zugriffstoken die erforderliche Berechtigung oder es ist ungültig).
ThrottledRequestException	429	Die Anforderungsrate hat das zulässige Limit überschritten. Versuchen Sie es erneut mit exponentiellem Backoff.
DependencyException	502	Eine Downstream-Abhängigkeit (Meta) hat einen Fehler zurückgegeben. Wiederholbar.
InternalServiceException	500	Es ist ein interner Fehler aufgetreten. Wiederholter Versuch möglich.