API de insights de mensajes

En este documento se explica cómo obtener mediante programación métricas relacionadas con los mensajes que tu empresa haya enviado o recibido. La API de insights de mensajes es una extensión de la API de insights de página que te permite obtener la misma información que aparece en la pestaña “Insights de página” de la página de Facebook.

Antes de empezar

En esta guía se da por sentado que has leído la información general sobre la plataforma de Messenger e implementado los componentes necesarios para enviar y recibir mensajes y notificaciones.

Para ver las métricas de una página de Facebook de tu propiedad o en la que puedas realizar la tarea ANALYZE, la aplicación necesitará lo siguiente:

El identificador de la página de Facebook de la que quieres ver las métricas.
- Para los mensajes de Instagram, será la página de Facebook vinculada a tu cuenta profesional de Instagram.
Un identificador 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 sea de tu propiedad o en la que no puedas realizar la tarea ANALYZE, la aplicación necesitará lo siguiente:

El identificador de la página de Facebook de la que quieres ver las métricas.
- Para los mensajes de Instagram, será la página de Facebook vinculada a tu cuenta profesional de Instagram.
Un identificador de acceso a la página solicitado por un usuario que pueda realizar la tarea ANALYZE en dicha 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 una conversación nueva se incluya en el recuento, el usuario debe haber realizado una acción, como enviar una respuesta al negocio. Hasta ese momento, solo dicho usuario puede ver la conversación y no se incluye en el recuento.

Lectura de las métricas de las insights

Para leer la información de una o varias métricas, envía una solicitud GET al extremo /PAGE-ID/insights con el parámetro metric establecido como una lista separada por comas de las métricas que quieras ver.

Ejemplo de solicitud

Se ha aplicado formato para mejorar la legibilidad.

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"

Cuando esta operación se completa correctamente, la aplicación recibe la respuesta JSON siguiente:

{ 
  "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 de total a lo largo del intervalo

El siguiente ejemplo busca el número total de conversaciones nuevas y únicas en un periodo de tiempo específico; para ello, incluye el parámetro period establecido en total_over_range con el intervalo de tiempo definido por los parámetros since y until en nuestra llamada a la API.

Se ha aplicado formato para mejorar la legibilidad.

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"

Cuando esta operación se completa correctamente, la aplicación recibe la siguiente respuesta JSON con el número de conversaciones nuevas y únicas, y el final del intervalo de tiempo.

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

Ejemplo de solicitud de desglose

El siguiente ejemplo busca el número total de identificadores de notificaciones recurrentes en un periodo de tiempo específico, y agrupados 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"

Cuando esta operación se completa correctamente, la aplicación recibe la siguiente respuesta JSON con los identificadores agrupados por tema, “newproducts” y “10percentsale", así como la frecuencia de mensajes disponible para 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 insights

Parámetro Descripción

breakdown

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

Nombre	Descripción
`campaign_id`	Consulta los datos según el número de identificador de la campaña. Por ejemplo, “abc123”, “Summer messaging campaign” y “Spring sale 2”.
`engagement_source`	Consulta los datos según el tipo de interacción con las notificaciones recurrentes. Por ejemplo, el identificador primario y secundario de las llamadas a la acción (en qué llamada a la acción se hizo clic).
`message_type`	Consulta los datos según el tipo de mensaje que envió la empresa. Por ejemplo, mensajes de marketing.
`messaging_channel`	Consulta los datos según el canal que se usó para entregar los mensajes a los usuarios. Por ejemplo, Messenger e Instagram.
`recurring_notifications_entry_point`	Consulta los datos según el punto de entrada a las notificaciones recurrentes. Por ejemplo, desde la conversación, mediante un plugin de chat, anuncios de clic a Messenger, un plugin Checkbox, enlaces m.me o ig.me y una página de Facebook.
`recurring_notifications_frequency`	Consulta los datos según la frecuencia permitida por la suscripción voluntaria a notificaciones recurrentes. Por ejemplo, diaria, semanal y mensual.
`recurring_notifications_topic`	Consulta los datos según el tema de las notificaciones recurrentes. Por ejemplo, mensajes promocionales, lanzamientos de productos y ofertas.

date_preset

Intervalo de fechas relacionado que se puede utilizar en lugar de since y until. Puede ser last_week, last_month, last_quarter u otras opciones. Descubre más valores en la guía de insights de página.

metric

Obligatorio.Lista de métricas separadas por comas que se devuelven.

period

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

since

La fecha de inicio del intervalo de fechas para el que quieres ver los datos. Incluye los datos de la fecha establecida a partir de las 0:00. El formato del valor es YYYY-MM-DD. Un valor de 2022-01-31 proporcionaría los datos a partir del 31 de enero de 2022 a las 0:00.

until

La fecha de finalización del intervalo de fechas para el que quieres ver los datos. Excluye los datos de la fecha establecida a partir de las 0:00. El formato del valor es YYYY-MM-DD. Un valor de 2022-02-01 proporcionaría los datos hasta el 31 de enero de 2022 a las 23:59.

Métricas disponibles

Las siguientes métricas están disponibles mediante la API de insights de mensajes:

Nombre de la `metric`	Descripción
`page_messages_blocked_conversations_unique`	El número de conversaciones con la página que se han bloqueado.
`page_messages_engagement`	El número de veces que los clientes han interactuado con mensajes de marketing enviados desde la página de tu empresa tocando un botón de llamada a la acción. Valores posibles de `breakdown`: `campaign_id` `engagement_source` `message_type` `messaging_channel` `recurring_notifications_topic` Esta métrica está en desarrollo.
`page_messages_new_conversations_unique`	El número de conversaciones con mensajes en Messenger iniciadas por usuarios que nunca antes habían intercambiado mensajes con la empresa.
`page_messages_order_count`	El número de veces que has creado un pedido en conversaciones con mensajes o en aplicaciones o sitios web de terceros utilizados para administrar dichas conversaciones. Esta métrica está en desarrollo.
`page_messages_paid_order_earnings`	La cantidad de dinero aproximada que has ganado con pedidos creados mediante conversaciones con mensajes o con aplicaciones o sitios web de terceros utilizados para administrar dichas conversaciones. Los ingresos finales pueden diferir debido a la conversión de divisas. Esta métrica está en desarrollo.
`page_messages_read_ratio`	El número de mensajes de marketing leídos dividido entre el número de mensajes de marketing enviados por tu página. Puede que algunos mensajes leídos no figuren, por ejemplo, si un cliente ha desactivado las confirmaciones de lectura. Valores posibles de `breakdown`: `campaign_id` `message_type` `messaging_channel` `recurring_notifications_topic` Esta métrica está en desarrollo.
`page_messages_reported_conversations_unique`	El número de conversaciones de la página que alguien haya denunciado por ser spam o mostrar contenido inapropiado, entre otros motivos.
`page_messages_sent`	El número de mensajes de marketing que la página de tu negocio ha enviado a clientes. Valores posibles de `breakdown`: `campaign_id` `messsage_type` `messaging_channel` `recurring_notifications_topic` Esta métrica está en desarrollo.
`page_messages_total_messaging_connections`	Número de usuarios a los que tu empresa puede enviar mensajes. Esta métrica muestra el número de usuarios que alguna vez han enviado un mensaje a tu negocio en Messenger, sin incluir a los usuarios que han bloqueado o denunciado a tu empresa en Messenger. Puede haber algunas restricciones en tu capacidad para enviar mensajes a las conexiones, como en la cantidad de mensajes que puedes enviar durante ciertos intervalos de tiempo. Ten en cuenta que esta métrica solo incluye las conexiones realizadas a partir de octubre de 2016, momento en el que los datos empezaron a estar disponibles.
`page_messages_with_business_outcomes`	El número de conexiones de mensajes con al menos un pedido creado. Esta métrica está en desarrollo.
`recurring_notifications_tokens`	El número de veces que una cuenta se ha suscrito para recibir mensajes de marketing de tu negocio. Si una cuenta se ha suscrito a varios temas, se contará una vez por tema. Se calcula de la siguiente forma: la métrica hace un recuento del número de veces que las cuentas han aceptado recibir mensajes recurrentes menos el número de veces que las cuentas han anulado la suscripción. Valores posibles de `breakdown`: `messaging_channel` `recurring_notifications_frequency` `recurring_notifications_topic` Esta métrica está en desarrollo.

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

Propiedades de la respuesta

Una llamada a la API de insights puede devolver la siguiente información.

Propiedad	Descripción
`data` matriz de objetos	Lista de objetos de las métricas.
`name` cadena	Nombre de la métrica.
`period` cadena	Periodo de tiempo durante el que se han notificado datos.
`values` matriz de objetos	Lista de datos correspondientes a una métrica.
`value` entero	Recuento de la métrica solicitada durante el intervalo de fechas especificado.
`end_time` marca de tiempo unix	Marca de tiempo UTC de la hora de finalización de la métrica.