Envoi d'événements de WhatsApp conversion dans AWS Messagerie à l'utilisateur final : réseaux sociaux

Si vous lancez des campagnes « Ads that Click to WhatsApp »Meta, vous pouvez renvoyer les événements de conversion (tels que les achats, les prospects ou les consultations de contenu) à des Meta fins d'attribution et d'optimisation des annonces. Envoyez ces événements directement via AWS la messagerie sociale des utilisateurs finaux, sans appeler l'API Meta Graph.

AWS End User Messaging Social fournit deux API pour ce flux de travail :

• CreateWhatsAppDataset— Crée (ou récupère) l'ensemble de données de conversions pour votre compte WhatsApp professionnel (WABA). Un ensemble de données est le conteneur Meta utilisé pour recevoir et attribuer vos événements de conversion.

• SendWhatsAppConversionEvent— Envoie un ou plusieurs événements de conversion à l'API Meta Conversions, où ils sont attribués au clic sur l'annonce qui a lancé la WhatsApp conversation.

Comment fonctionne le suivi des événements de conversion

Le flux de travail de bout en bout est :

1. Un client clique sur votre annonce WhatsApp « Cliquez pour » Meta et entame une conversation avec votre entreprise.

2. Le message entrant arrive à la destination de l'événement que vous avez configurée (rubrique Amazon SNS EventBridge, Amazon ou Amazon Connect). Il inclut un ctwa_clid (identifiant de clic) qui identifie le WhatsApp clic sur l'annonce. Votre application doit capturer et stocker cette valeur.

3. Lorsqu'une conversion se produit (par exemple, le client effectue un achat), votre application appelle pour vous SendWhatsAppConversionEvent communiquer ctwa_clid les détails de l'événement.

4. AWS End User Messaging Social transmet l'événement à l'API Meta Conversions pour attribution.

ctwa_clidIl est inclus dans l'referralobjet de la charge utile du webhook des messages entrants lorsqu'un client entame une conversation à partir d'une annonce. L'exemple suivant montre la partie pertinente du message du webhook :

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

Stockez la ctwa_clid valeur de l'referralobjet. Transmettez-le dans chaque événement user_data de conversion que vous envoyez pour cette conversation. Pour plus d'informations sur le webhook de référence, consultez la section Composants des Webhooks dans la documentation destinée aux Meta développeurs.

Conditions préalables

Avant d'envoyer des événements de conversion, vous devez disposer des éléments suivants :

• Un compte WhatsApp professionnel (WABA) lié à votre AWS compte.

• Une campagne « Ads that Click to WhatsApp » active surMeta.

• Votre application doit capturer le contenu ctwa_clid du webhook du message entrant lorsqu'un client entame une conversation en cliquant sur une annonce. Cette valeur est générée par Meta et ne peut pas être fabriquée.

Important

Si vous avez associé votre compte WhatsApp professionnel (WABA) avant le 6 août 2026, vous devez refaire le processus d'inscription pour autoriser l'utilisateur AWS final Messaging Social à envoyer des événements de conversion. Suivez les étapes 1 à 14 de la section « S'inscrire via la console » de la rubrique Inscription WhatsApp, puis sélectionnez le WABA existant et le numéro de téléphone déjà associés à votre AWS compte. Vous pouvez ensuite ignorer les étapes restantes.

Étape 1 : Création d'un jeu de données de conversions

Avant de pouvoir envoyer des événements de conversion, vous devez créer un jeu de données de conversions pour votre WABA. Chaque WABA possède exactement un ensemble de données (ceci est imposé parMeta). L'opération est idempotente : si un jeu de données existe déjà, son identifiant est renvoyé.

L'exemple suivant crée ou récupère l'ensemble de données pour une WABA. waba-idRemplacez-le par l'ARN de votre compte WhatsApp professionnel associé (WABA) (par exemple,arn:aws:social-messaging:us-east-1:123456789012:waba/a1b2c3d4e5example).

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

La réponse contient l'ID du jeu de données. Enregistrez cette valeur. Vous le transmettez comme datasetId paramètre chaque fois que vous envoyez un événement de conversion.

{
    "datasetId": "123456789012345"
}

Étape 2 : envoyer des événements de conversion

Après avoir créé un jeu de données, vous pouvez envoyer des événements de conversion à Meta l'aide de l'SendWhatsAppConversionEventAPI. Chaque appel transmet un ou plusieurs événements à l'API Meta Conversions pour attribution.

Le contenu de l'événement que vous envoyez dans le event-data paramètre suit le format d'événement du serveur de l'API Meta Conversions. AWS End User Messaging Social transmet ce contenu àMeta. Pour obtenir la liste complète des champs d'événements, consultez la référence des paramètres Meta server-event dans la documentation destinée aux Meta développeurs.

Envoyer un événement de conversion d'achats

L'exemple suivant indique une Purchase conversion. Remplacez les valeurs des espaces réservés par les vôtres.

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
            }
        }
    ]
}'

La réponse contient un identifiant de demande qui identifie votre soumission :

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

Envoyer un événement de conversion de prospects

Non-purchase types d'événements tels que ceux qui LeadSubmitted ne sont pas nécessairescustom_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"
            }
        }
    ]
}'

Envoyer plusieurs événements en une seule demande

Le data tableau accepte plusieurs événements en un seul appel. Metaautorise jusqu'à 1 000 événements par demande.

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
            }
        }
    ]
}'

Référence de l'événement de conversion

Le event-data paramètre est un objet JSON avec un data tableau contenant un ou plusieurs objets d'événement. Les tableaux suivants décrivent les champs les plus couramment utilisés pour les conversions « Annonces vers lesquelles cliquer WhatsApp ». Metaest la source de vérité pour le contenu des événements ; consultez la référence des paramètres Meta server-event dans la documentation destinée aux Meta développeurs pour obtenir la spécification complète.

Champs d'événement obligatoires

Champ	Type	Description
event_name	Chaîne	Type de conversion. Case-sensitive. Les valeurs courantes incluent PurchaseLeadSubmitted, etViewContent.
event_time	Nombre	Heure à laquelle la conversion a eu lieu, sous forme d'horodatage Unix en secondes. Doit être au cours des 7 derniers jours et non dans le futur.
action_source	Chaîne	Doit indiquer business_messaging.
messaging_channel	Chaîne	Le canal de messagerie. Utilisez whatsapp.
user_data	Objet	Informations utilisées pour associer l'événement au clic sur l'annonce. Consultez Champs user_data obligatoires.

Champs user_data obligatoires

Le tableau suivant décrit les champs obligatoires de l'user_dataobjet.

Champ	Type	Description
whatsapp_business_account_id	Chaîne	Votre numéro de compte Meta WhatsApp professionnel numérique (depuis les paramètres Meta professionnels).
ctwa_clid	Chaîne	L'identifiant du clic pour WhatsApp cliquer figurant dans le webhook des messages entrants de la conversation entamée par l'annonce. Metavalide cette valeur ; elle ne peut pas être fabriquée.

Important

Si vous incluez des informations personnelles identifiables (PII)user_data, telles que des adresses e-mail ou des numéros de téléphone, vous devez fournir les valeurs sous forme de SHA-256 hachage. Metarejette les informations d'identification personnelles non hachées. La ctwa_clid valeur n'est pas hachée.

L'objet custom_data

Pour les Purchase événements, vous devez inclure l'custom_dataobjet dans les champs suivants :

Champ	Type	Description
currency	Chaîne	Le code de devise ISO 4217 (par exemple,USD).
value	Nombre	La valeur monétaire de la conversion.

Gestion des erreurs

Étant donné que AWS la messagerie des utilisateurs finaux sur les réseaux sociaux transmet le contenu de votre événement àMeta, la plupart des problèmes liés au contenu de l'événement apparaissent sous forme de. InvalidParametersException Le message d'erreur inclut la raison signaléeMeta, par exemple : un nom d'événement non reconnu, une heure d'événement en dehors de la fenêtre autorisée, une devise manquante pour un achat, des informations d'identification personnelles non hachées ou une erreur non valide. ctwa_clid

Erreur	Statut HTTP	Signification
InvalidParametersException	400	Le contenu de la demande ou de l'événement n'était pas valide. Le message d'erreur décrit le problème spécifique.
ResourceNotFoundException	404	Le WABA ou l'ensemble de données spécifié est introuvable.
AccessDeniedByMetaException	403	Metaa rejeté la demande en raison d'autorisations (par exemple, le jeton Meta d'accès sous-jacent ne dispose pas de l'autorisation requise ou n'est pas valide).
ThrottledRequestException	429	Le taux de demandes a dépassé la limite autorisée. Réessayez avec un backoff exponentiel.
DependencyException	502	Une dépendance en aval (Meta) a renvoyé une erreur. Réessayable.
InternalServiceException	500	Une erreur interne s’est produite. Réessayable.