API de estadísticas de mensajes

En este documento, se explica cómo obtener métricas programáticamente para mensajes que tu empresa envió o recibió. La API de estadísticas de mensajes es una extensión de la API de estadísticas de la página y te permite obtener la misma información que aparece en la pestaña "Estadísticas de la página" en Facebook.

Antes de empezar

En esta guía, se asume que leíste el Resumen de la plataforma de Messenger y que implementaste los componentes necesarios para enviar y recibir mensajes y notificaciones.

Para ver las métricas de una página de Facebook que te pertenece o en la que puedes realizar la tarea ANALYZE, necesitarás lo siguiente en tu app:

El identificador de la página de Facebook de la cual quieres ver las métricas.
- En el caso de los mensajes de Instagram, será la página de Facebook vinculada a la cuenta profesional de Instagram.
Un token de acceso a la página.
Los siguientes permisos:
- pages_messaging
- pages_read_engagement
- pages_show_list
- read_insights
Acceso estándar.

Para ver las métricas de una página de Facebook que no te pertenece o en la que no puedes realizar la tarea ANALYZE, tu app necesitará lo siguiente:

El identificador de la página de Facebook de la cual quieres ver las métricas.
- En el caso de los mensajes de Instagram, será la página de Facebook vinculada a la cuenta profesional de Instagram.
Un token de acceso a la página solicitado por una persona que pueda realizar la tarea ANALYZE en la página.
Los siguientes permisos a través del inicio de sesión con Facebook:
- pages_messaging
- pages_read_engagement
- pages_show_list
- read_insights
Acceso avanzado.

Limitaciones

Para que se cuente una nueva conversación, una persona debe haber realizado una acción, como enviar una respuesta a tu negocio. Mientras la persona no realice una acción, la conversación solo será visible para esa persona y no se contará.

Leer métricas de estadísticas

Para leer la información de una o más métricas, envía una solicitud GET al punto de conexión /PAGE-ID/insights con el parámetro metric configurado en una lista separada por comas de métricas que quieres ver.

Ejemplo de solicitud

El formato se modificó para facilitar la lectura.

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"

Si la operación se completa con éxito, la app recibirá la siguiente respuesta JSON:

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

Ejemplo de solicitud para ver la métrica "Total a lo largo del intervalo"

En el siguiente ejemplo, se puede ver la cantidad total de conversaciones únicas nuevas en un período específico. Para obtener ese valor, se incluye el parámetro period configurado como total_over_range y se usan los parámetros since y until para definir el intervalo de tiempo en la llamada a la API.

El formato se modificó para facilitar la lectura.

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"

Si la solicitud se procesa correctamente, tu app recibirá la respuesta JSON con la cantidad de conversaciones únicas nuevas y el final del intervalo de tiempo:

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

Solicitud "breakdown" de ejemplo

En el siguiente ejemplo, se solicita la cantidad total de tokens de notificaciones periódicas en un plazo específico y los resultados se agrupan por tema y frecuencia.

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"

Si la solicitud se procesa correctamente, tu app recibirá la siguiente respuesta JSON con los tokens agrupados por tema ("newproducts" correspondiente a productos nuevos y "10percentsale" correspondiente a oferta del 10%) y se indicará además una frecuencia de mensajes (diaria, semanal o mensual) en cada tema ("daily", "weekly" y "monthly" para "newproducts", y "daily" y "weekly" para "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"
        },
      ]
    }
  ]
}

Parámetros de estadísticas

Parámetro Descripción

breakdown

Dimensiones por las que se agrupa la respuesta. Puede ser una o más de las siguientes:

Nombre	Descripción
`campaign_id`	Consulta tus datos por número de identificador de campaña. Por ejemplo, "abc123", "Summer messaging campaign" y "Spring sale 2".
`engagement_source`	Consulta tus datos por tipo de interacción con notificaciones recurrentes. Por ejemplo, identificadores de llamada a la acción primarios y secundarios (en qué llamada a la acción se hizo clic).
`message_type`	Consulta tus datos por tipo de mensaje enviado por la empresa. Por ejemplo, mensajes de marketing.
`messaging_channel`	Consulta tus datos por el canal utilizado para enviar mensajes a los usuarios. Por ejemplo, Messenger e Instagram.
`recurring_notifications_entry_point`	Consulta tus datos por el punto de entrada a notificaciones recurrentes. Por ejemplo, en la conversación, plugin de chat, anuncios de clic a Messenger, plugin Checkbox, enlaces m.me o ig.me y página de Facebook.
`recurring_notifications_frequency`	Consulta tus datos por la frecuencia permitida por la aceptación de las notificaciones recurrentes. Por ejemplo, diaria, semanal y mensual.
`recurring_notifications_topic`	Consulta tus datos por los temas de las notificaciones recurrentes. Por ejemplo, mensajes promocionales, lanzamiento de productos y ofertas.

date_preset

Intervalo de fechas relativo que se puede usar en lugar de since y until. Puede ser last_week, last_month, last_quarter, entre otros. Puedes consultar más valores en la guía de estadísticas de la página.

metric

Obligatorio. La lista de métricas separada por comas que se devolverá.

period

La agregación proporcionada dentro del intervalo since/until o date_preset. El valor total_over_range brinda un solo valor correspondiente a la métrica en el intervalo de fechas determinado. Puede ser day, week, month, days_28 o total_over_range.

since

La fecha de inicio del intervalo de fechas durante el cual quieres revisar los datos. Incluye datos de la fecha configurada a partir de las 12:00 a. m. El formato del valor es YYYY-MM-DD. El valor 2022-01-31 proporcionaría datos del 31 de enero de 2022 a partir de las 12:00 a. m.

until

La fecha de finalización del intervalo de fechas cuyos datos quieres ver. Excluye los datos de la fecha configurada a partir de las 12:00 a. m. El formato del valor es YYYY-MM-DD. El valor 2022-02-01 proporcionaría datos hasta el 31 de enero de 2022 a las 12:00 a. m.

Métricas disponibles

Las siguientes métricas están disponibles con la API de estadísticas de mensajes:

Nombre de `metric`	Descripción
`page_messages_blocked_conversations_unique`	La cantidad de conversaciones con la página que se bloquearon.
`page_messages_engagement`	La cantidad de veces que los clientes presionaron un botón de llamada a la acción para interactuar con mensajes de marketing enviados por la página de tu empresa. Posibles valores de `breakdown`: `campaign_id` `engagement_source` `message_type` `messaging_channel` `recurring_notifications_topic` Esta métrica se encuentra en desarrollo.
`page_messages_new_conversations_unique`	La cantidad de conversaciones conversación con mensajes en Messenger que comenzaron con personas que nunca habían enviado un mensaje a tu empresa.
`page_messages_order_count`	La cantidad de veces que creaste un pedido en conversaciones con mensajes o en apps o sitios web de terceros que usas para administrar conversaciones con mensajes. Esta métrica se encuentra en desarrollo.
`page_messages_paid_order_earnings`	El importe de dinero aproximado que ganaste a partir de pedidos creados mediante conversaciones con mensajes o apps o sitios web de terceros que usas para administrar conversaciones con mensajes. Los ingresos finales pueden variar debido a las conversiones de divisas. Esta métrica se encuentra en desarrollo.
`page_messages_read_ratio`	El número de mensajes de marketing leídos dividido por el número de mensajes de marketing enviados por tu página. Es posible que no se capturen algunas lecturas de mensajes, por ejemplo, cuando un cliente desactivó las confirmaciones de lectura. Posibles valores de `breakdown`: `campaign_id` `message_type` `messaging_channel` `recurring_notifications_topic` Esta métrica se encuentra en desarrollo.
`page_messages_reported_conversations_unique`	El número de conversaciones de tu página que las personas reportaron por considerarlas spam o de contenido inapropiado.
`page_messages_sent`	El número de mensajes de marketing que la página de tu empresa envió a los clientes. Posibles valores de `breakdown`: `campaign_id` `messsage_type` `messaging_channel` `recurring_notifications_topic` Esta métrica se encuentra en desarrollo.
`page_messages_total_messaging_connections`	El número de personas a la que tu empresa puede enviar mensajes. Esta métrica muestra la cantidad de personas que enviaron un mensaje a tu empresa en Messenger, pero no incluye a las personas que bloquearon o reportaron a tu empresa en Messenger. Puede haber algunas limitaciones en tu capacidad para enviar mensajes a conexiones, como limitaciones sobre la cantidad de mensajes que puedes enviar durante ciertos plazos. Además, esta métrica solo incluye conexiones realizadas desde octubre de 2016, cuando los datos comenzaron a estar disponibles.
`page_messages_with_business_outcomes`	El número de conexiones de mensajes con al menos un pedido creado. Esta métrica se encuentra en desarrollo.
`recurring_notifications_tokens`	El número de veces que una cuenta se suscribió para recibir mensajes de marketing de tu empresa. Si una cuenta se suscribió a varios temas, se contará otra vez por cada tema. Cómo se calcula: esta métrica cuenta la cantidad de veces que la cuenta aceptó recibir mensajes recurrentes menos la cantidad de veces que las cuentas anularon la suscripción. Posibles valores de `breakdown`: `messaging_channel` `recurring_notifications_frequency` `recurring_notifications_topic` Esta métrica se encuentra en desarrollo.

Obtén más información sobre métricas en desarrollo.

Propiedades de la respuesta

La siguiente información se puede devolver en una llamada a la API de estadísticas.

Propiedad	Descripción
`data` matriz de objetos	Una lista de objetos de la métrica.
`name` cadena	El nombre de la métrica.
`period` cadena	El período sobre el cual se reportaron los datos.
`values` matriz de objetos	Una lista de datos de una métrica.
`value` número entero	Recuento de la métrica solicitada durante el intervalo de fechas especificado.
`end_time` marca de tiempo de unix	Marca de tiempo UTC de la hora de finalización de la métrica.