API Conversions pour messagerie professionnelle

L’API Conversions permet aux annonceurs d’envoyer des évènements Web, d’application, de boutique physique et de messagerie professionnelle à Meta via un seul point de terminaison, plutôt que plusieurs sources. Cette consolidation simplifie la pile technologique des annonceurs et leur offre une vision plus complète dans le Gestionnaire d’évènements Meta grâce à l’utilisation d’ensembles de données.

La présente documentation explique comment intégrer des évènements de messagerie professionnelle dans l’API Conversions. L’utilisation de l’API Conversions pour messagerie professionnelle apporte de nombreux avantages. En voici quelques-uns :

Affichage des performances directement dans les rapports du Gestionnaire de publicités : les annonceurs peuvent facilement interpréter les performances importantes des campagnes de type Clic pour envoyer un message (par exemple, le nombre d’achats et le coût par achat, plutôt que les conversations démarrées), directement sur les plateformes Meta.
Simplification de l’intégration de données : cette API unique prend en charge l’ingestion et le partage des données provenant de multiples plateformes de messagerie (Messenger, WhatsApp) et canaux (site Web, application, boutiques, messagerie).
Amélioration des mesures des partenaires : l’attribution des campagnes de type Clic pour envoyer un message peut s’effectuer directement sur les tableaux de bord des partenaires via l’API Ads Insights.

Conditions requises

Ensemble de données

Les évènements de messagerie professionnelle envoyés par l’API Conversions doivent être associés à un ensemble de données.

Les ensembles de données permettent aux annonceurs d’associer les données des évènements Web, d’application, de boutique et de messagerie professionnelle à l’API Conversions, et de les gérer. Les ensembles de données peuvent contenir des données d’évènement provenant de n’importe quelle intégration configurée :

Pixel Meta (évènements de site Web)
API App Events (évènements d’application, y compris le SDK Facebook pour iOS ou Android et les partenaires de mesure mobile)
API Offline Conversions (ancienne API de Meta pour les évènements hors ligne)

Les ensembles de données permettent de visualiser toutes les activités liées à la clientèle à partir d’une interface unique. Ils facilitent également la création et la gestion de plusieurs intégrations d’API.

Selon le type d’évènement à envoyer, le Gestionnaire d’évènements propose différentes options pour créer un ensemble de données. Vous pouvez également créer votre propre ensemble de données dans le Gestionnaire d’évènements par association lors de la création d’un ensemble d’évènements hors ligne, via une application mobile existante ou lors de la création d’un ensemble d’évènements de messagerie. Notez que chaque ensemble de données doit être associé à une application avant de pouvoir envoyer des évènements d’application mobile à l’API Conversions et qu’il ne peut être associé qu’à une seule application. En savoir plus et consulter les instructions

Autorisations

Pour mettre en œuvre une intégration directe en tant qu’annonceur, suivez ces instructions pour connaître les critères à respecter et les autorisations à obtenir.
L’intégration d’une plateforme partenaire nécessite les éléments suivants :
- Accès avancé aux autorisations ads_read, ads_management, pages_messaging, whatsapp_business_messaging, pages_show_list et instagram_manage_messages
- Fonctionnalité Accès standard au Gestionnaire de publicités
- Accès avancé à l’autorisation page_events (pour les évènements Messenger ou WhatsApp) ou instagram_manage_events (pour les évènements Instagram Direct)

Intégration de partenaires

Pour effectuer une intégration de partenaire en tant que plateforme, vous pouvez utiliser soit Facebook Login for Business (recommandé), soit l’Extension Meta Business.

Veuillez consulter les guides de l’API Conversions pour messagerie professionnelle afin d’obtenir des instructions d’intégration détaillées.

API Dataset pour Messenger et WhatsApp

L’API Dataset permet d’obtenir le dataset_id associé à une page. Cet identifiant dataset_id sera utilisé ultérieurement dans l’API Conversions. Pour que vous puissiez utiliser l’API Dataset, votre client·e doit avoir accordé l’autorisation page_events à votre application pour les évènements Messenger ou WhatsApp à l’aide de Facebook Login for Business ou de l’extension Meta Business.

Pour récupérer le dataset_id, vous devez exécuter un appel GET vers l’API Dataset avec les valeurs page_id et access_token. Exemple d’appel :

https://graph.facebook.com/v16.0/{PAGE_ID}/dataset?access_token={TOKEN}

L’appel renvoie un ID qui représente le dataset_id. Grâce à cet ID et au token d’accès récupéré précédemment, vous pouvez maintenant appeler l’API Conversions afin d’envoyer les évènements de messagerie à Meta.

API Dataset pour Instagram

L’API Dataset permet d’obtenir le dataset_id associé à une page. Cet identifiant dataset_id sera utilisé ultérieurement dans l’API Conversions. Pour que vous puissiez utiliser l’API Dataset, votre client·e doit avoir accordé l’autorisation instagram_manage_events à votre application à l’aide de Facebook Login for Business ou de l’extension Meta Business.

Pour récupérer le dataset_id, vous devez exécuter un appel GET vers l’API Dataset avec les valeurs ig_user_id et access_token. Exemple d’appel :

https://graph.facebook.com/v16.0/{IG_USER_ID}/dataset?access_token={TOKEN}

L’appel renvoie un ID qui représente le dataset_id. Grâce à cet ID et au token d’accès récupéré précédemment, vous pouvez maintenant appeler l’API Conversions afin d’envoyer les évènements de messagerie à Meta.

Configuration

Configurer les paramètres des évènements de messagerie professionnelle

Consultez cette page pour connaître les paramètres qui peuvent actuellement être envoyés via l’API Conversions. Pour envoyer des évènements de messagerie professionnelle, les champs suivants peuvent être partagés dans la charge utile des données utilisateur·ice pour différentes plateformes de messagerie :

Plateforme	Paramètre	Description
Messenger	`page_id`	Obligatoire pour Messenger ID de la Page Facebook associée à l’entreprise.
Messenger	`page_scoped_user_id`	Obligatoire pour Messenger Les utilisateurs et utilisatrices qui interagissent avec les Pages sont identifié·es par des identifiants utilisateur·ice spécifiques à une Page (PSID). Le PSID peut être obtenu à partir de ce webhook.
WhatsApp	`page_id`	Obligatoire pour WhatsApp ID de la Page Facebook associée au compte WhatsApp Business.
WhatsApp	`ctwa_clid`	Obligatoire pour WhatsApp Le paramètre `ctwa_clid` est disponible uniquement à partir de l’objet referral sous le webhook messages dans l’API Business version 2.45.1 et ultérieures (On-Premises) ou l’API Cloud.
Instagram	`ig_account_id`	Obligatoire pour Instagram ID du compte Instagram associé à l’entreprise.
Instagram	`ig_sid`	Obligatoire pour Instagram Les utilisateurs et utilisatrices qui interagissent avec Instagram sont identifié·es par des identifiants utilisateur·ice spécifiques à Instagram (IGSID). L’IGSID peut être obtenu à partir de ce webhook.

Envoyer des évènements

Pour envoyer de nouveaux évènements, envoyez une requête POST à l’API Conversions à partir du chemin suivant :

https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}

Lorsque vous publiez dans cette arête, Meta crée des évènements de messagerie professionnelle. Pour en savoir plus, consultez ce document pour développeur·se.

Découvrez comment les paramètres s’intègrent dans la charge utile globale.

Pour les évènements Messenger :

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

Pour les évènements WhatsApp :

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

Pour les évènements Instagram :

Exemple de requête d’API Conversions CTD

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

Dépannage

Utilisez l’outil d’évènements de test du Gestionnaire d’évènements pour effectuer vos tests :

Accédez au Gestionnaire d’évènements et sélectionnez un ensemble de données associé à la page.
Cliquez sur l’onglet Évènements de test.
Sélectionnez le canal marketing et le canal de messagerie.
Cliquez sur le bouton Explorateur de l’API Graph.
La charge utile est automatiquement indiquée dans l’Explorateur de l’API Graph.
Cliquez sur le bouton Envoyer.

Présentation vidéo

Cette vidéo explique de façon détaillée comment mettre en œuvre une intégration.

Une erreur s’est produite

Nous rencontrons des difficultés pour lire cette vidéo.

Questions/réponses

Quels sont les types d’évènements de messagerie pris en charge par l’API Conversions pour messagerie professionnelle ?

R : Actuellement, l’API Conversions pour messagerie professionnelle ne prend en charge que les évènements d’achat et d’envoi de prospects. Les évènements de messagerie doivent uniquement représenter des interactions avec la clientèle dans un fil de discussion, et non des conversions générées sur d’autres canaux (par exemple, un site Web). Vous pouvez distinguer facilement vos évènements en choisissant l’origine de l’action correspondante lors du processus d’intégration.

Est-ce que Meta recommande d’utiliser une ou plusieurs applications pour les différentes intégrations de l’API Conversions ?

R : Il est préférable d’utiliser une seule application afin que Meta puisse identifier tous les évènements envoyés par le partenaire. Si vous possédez déjà plusieurs applications, veillez à ce que le paramètre partner_agent soit défini sur le nom de l’agent partenaire qui vous a été attribué. En cas de doute, n’hésitez pas à contacter votre représentant Meta.

Si une conversion se produit en dehors du fil de discussion (par exemple, sur mon site Web ou dans mon application), comment transmettre les évènements à Meta ?

R : Dans cette situation, vous devez quand même renvoyer l’évènement à Meta en utilisant l’API Conversions appropriée. Par exemple, si une conversion se produit sur votre site Web, utilisez l’API Conversions pour le Web. Si la conversion se produit dans votre application, utilisez l’API Conversions pour les évènements d’application. L’évènement sera toujours attribué à l’ID de clic pour l’API Conversions pour le Web. Vous trouverez la liste complète des paramètres sur cette page.

L’API Conversions permet-elle d’activer l’optimisation des publicités Clic pour envoyer un message ?

R : L’API Conversions permet d’accéder à l’optimisation des achats pour les publicités Clic vers Messenger uniquement. Elle n’est pas disponible pour l’optimisation des publicités WhatsApp pour le moment. Pour les publicités Clic vers WhatsApp, vous pouvez optimiser vos campagnes publicitaires afin de lancer plus de conversations.

Puis-je réutiliser l’ensemble de données existant pour l’API Conversions pour messagerie professionnelle ?

R : Oui, il est possible d’associer l’ensemble de données existant. Vous pouvez consulter les options disponibles pour choisir celle qui est la plus adaptée à votre entreprise.

J’utilise actuellement l’API Conversions pour le Web. Est-ce que le fait d’ajouter la messagerie professionnelle à la même intégration interférera avec l’intégration existante ?

R : Il n’y a pas de risque à ajouter la messagerie professionnelle à votre intégration d’API Conversions existante. L’attribution est basée sur l’ID de la page ou de l’ensemble de données, pas sur l’ID de l’application.

Combien d’ensembles de données puis-je associer à une page ?

R : Vous pouvez associer un seul ensemble de données à une page.

Faut-il dédupliquer les évènements avant de les envoyer via l’API Conversions pour messagerie professionnelle ?

R : Meta n’aide pas les annonceurs à dédupliquer les évènements pour l’API Conversions pour messagerie professionnelle. C’est pourquoi nous les encourageons vivement à réaliser eux-mêmes cette opération avant d’envoyer les évènements.

Voir aussi

Premiers pas avec l’API Conversions
Utiliser l’API Conversions
Paramètres de l’API Conversions
Recommandations
Plateforme WhatsApp Business (On-Premises ou API Cloud) avec l’API Business version 2.45.1 et ultérieures
API Instagram Messaging