API Messaging Insights

Ce document vous explique comment obtenir par programmation les indicateurs des messages envoyés et reçus par votre entreprise. L’API Messaging Insights est une extension de l’API Pages Insights qui vous permet d’obtenir les informations affichées dans l’onglet Statistiques de Page de votre Page Facebook.

Avant de commencer

Pour afficher les indicateurs d’une Page Facebook dont vous êtes propriétaire ou sur laquelle vous pouvez effectuer la tâche ANALYZE, votre application nécessite les éléments suivants :

• L’ID de Page de la Page Facebook dont vous souhaitez voir les indicateurs

  • Pour la messagerie Instagram, il s’agit de la Page Facebook liée au compte professionnel Instagram
• Un token d’accès de Page
• Vous aurez également besoin des autorisations suivantes :

  • pages_messaging
  • pages_read_engagement
  • pages_show_list
  • read_insights
• Accès standard

Pour afficher les indicateurs d’une Page Facebook dont vous n’êtes pas propriétaire ou sur laquelle vous ne pouvez pas effectuer la tâche ANALYZE, votre application nécessite les éléments suivants :

• L’ID de la Page Facebook dont vous souhaitez voir les indicateurs

  • Pour la messagerie Instagram, il s’agit de la Page Facebook liée au compte professionnel Instagram
• Un token d’accès de Page demandé par une personne autorisée à effectuer la tâche ANALYZE sur la Page
• Les autorisations suivantes via Facebook Login :

  • pages_messaging
  • pages_read_engagement
  • pages_show_list
  • read_insights
• Accès avancé

Limites

• Pour qu’une nouvelle conversation soit comptabilisée, une personne doit avoir effectué une action, comme envoyer une réponse à votre entreprise. Tant que la personne n’effectue pas d’action, elle est la seule à voir la conversation et cette dernière n’est pas comptabilisée.

Lire les indicateurs de statistiques

Pour lire des informations concernant un ou plusieurs indicateurs, envoyez une requête GET au point de terminaison /PAGE-ID/insights, avec le paramètre metric contenant une liste des indicateurs que vous souhaitez voir, séparés par une virgule.

Exemple de requête

curl -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/insights
    ?metric=page_messages_new_conversations_unique,page_messages_blocked_conversations_unique 
    &access_token=PAGE-ACCESS-TOKEN"

En cas de succès, l’application reçoit la réponse JSON ci-dessous :

{ 
  "data": [ 
    { 
      "name": "page_messages_new_conversations_unique", 
      "period": "day", 
      "values": [ 
        { 
          "value": "42", 
          "end_time": "1665175977" 
        }, 
      ]
    },
    { 
      "name": "page_messages_blocked_conversations_unique", 
      "period": "day", 
      "values": [ 
        { 
          "value": "0", 
          "end_time": "1665175977" 
        }, 
      ]
    } 
  ],
}

Exemple de requête de période totale

La requête suivante permet de trouver le nombre total de nouvelles conversations uniques au cours d’une période donnée avec le paramètre period défini sur total_over_range et la période définie par les paramètres since et until dans l’appel d’API.

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/insights/
    ?metric=page_messages_new_conversations_unique
    &since=UNIX-TIMESTAMP-START
    &until=UNIX-TIMESTAMP-STOP
    &period=total_over_range
    &access_token=PAGE-ACCESS-TOKEN"

En cas de réussite, votre application reçoit la réponse JSON suivante avec le nombre de nouvelles conversations uniques et la fin de la période :

{
  "data": [
    {
      "name": "page_messages_new_conversations_unique",
      "period": "total_over_range",
      "values": [
        {
          "value": 27
          "end_time": "1665175977"
        }
      ],
    }
  ]
}

Exemple de requête de répartition

L’exemple suivant permet de trouver le nombre total de tokens de notifications récurrentes au cours d’une période spécifique, regroupés par sujet et par fréquence.

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/insights/
    ?metric=recurring_notifications_tokens   
    &since=UNIX-TIMESTAMP-START
    &until=UNIX-TIMESTAMP-STOP
    &period=total_over_range
    &breakdown=recurring_notifications_topic,recurring_notifications_frequency 
    &access_token=PAGE-ACCESS-TOKEN"

En cas de réussite, votre application reçoit la réponse JSON suivante avec des tokens regroupés par sujet (« newproducts » et « 10percentsale »), et la fréquence de messages disponible pour chaque sujet (« daily », « weekly » et « monthly » pour « newproducts », et « weekly » pour « 10percentsale ») :

{
  "data": [
    {
      "name": "recurring_notifications_tokens",
      "period": "total_over_range",
      "values": [ 
        {
          "value": 3,
          "end_time": "1665175977",
          "recurring_notifications_topic": "newproducts",
          "recurring_notifications_frequency": "daily"
        },
        {
          "value": 15,
          "end_time": "1665175977",
          "recurring_notifications_topic": "newproducts",
          "recurring_notifications_frequency": "weekly"
        },
        {
          "value": 8,
          "end_time": "1665175977",
          "recurring_notifications_topic": "newproducts",
          "recurring_notifications_frequency": "monthly"
        },
        {
          "value": 17,
          "end_time": "1665175977",
          "recurring_notifications_topic": "10percentsale",
          "recurring_notifications_frequency": "daily"
        },
        {
          "value": 14,
          "end_time": "1665175977",
          "recurring_notifications_topic": "10percentsale",
          "recurring_notifications_frequency": "weekly"
        },
      ]
    }
  ]
}

Paramètres de statistiques

Indicateurs disponibles

Les indicateurs suivants sont disponibles via l’API Messaging Insights :

En savoir plus sur les indicateurs en cours de développement.

Propriétés de la réponse

Les informations suivantes peuvent être renvoyées lors d’un appel à l’API Insights.

Voir aussi

• En savoir plus sur les statistiques de Page
• En savoir plus sur la référence sur les statistiques d’objet