API de Insights sobre Mensagens

Este documento explica como obter métricas de forma programática sobre mensagens que a sua empresa enviou ou recebeu. A API de Insights sobre Mensagens é uma extensão da API de Insights sobre a Página que permite obter as mesmas informações exibidas na aba "Insights da Página" no Facebook.

Antes de começar

Para ver as métricas de uma Página do Facebook que pertence a você ou na qual você pode executar a tarefa ANALYZE, o app precisará dos seguintes itens:

• A identificação da Página do Facebook cujas métricas você quer consultar

  • Para Mensagens do Instagram, essa deve ser a Página conectada à sua conta profissional do Instagram.
• Um token de acesso à Página
• Estas permissões:

  • pages_messaging
  • pages_read_engagement
  • pages_show_list
  • read_insights
• Acesso padrão

Para ver as métricas de uma Página do Facebook que não é sua ou na qual você não pode executar a tarefa ANALYZE, o app precisará destes itens:

• A identificação da Página do Facebook cujas métricas você quer consultar

  • Para Mensagens do Instagram, essa deve ser a Página conectada à sua conta profissional do Instagram.
• Um token de acesso à Página solicitado por uma pessoa que possa executar a tarefa MANAGE na Página
• As seguintes permissões pelo Login do Facebook:

  • pages_messaging
  • pages_read_engagement
  • pages_show_list
  • read_insights
• Acesso avançado

Limitações

• Para que uma conversa nova seja contabilizada, a pessoa precisa ter realizado uma ação, como enviar uma resposta à empresa. Antes disso, a conversa ficará visível apenas para a pessoa e não será contabilizada.

Consultar métricas de insights

Para ver informações sobre uma ou mais métricas, envie uma solicitação GET ao ponto de extremidade /PAGE-ID/insights com o parâmetro metric definido como a lista de métricas a serem consultadas separadas por vírgula.

Exemplo de solicitação

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"

Se ela for bem-sucedida, o app receberá a seguinte resposta 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" 
        }, 
      ]
    } 
  ],
}

Exemplo de solicitação para intervalo

O exemplo a seguir recupera o número total de conversas novas e únicas em um período específico ao incluir o parâmetro period definido como total_over_range com o intervalo de tempo determinado por since e until na chamada de 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"

Se ela for bem-sucedida, o app receberá a seguinte resposta JSON com o número de conversas novas e únicas e o término do intervalo:

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

Exemplo de solicitação de detalhamento

O exemplo a seguir recupera o número total de tokens de notificações recorrentes agrupados por tópico e frequência durante um período específico.

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"

Se ela for bem-sucedida, o app receberá a seguinte resposta JSON com tokens agrupados por tópico ("newproducts" e "10percentsale") e a frequência de mensagens disponível para cada tópico ("daily", "weekly" e "monthly" para "newproducts"; e "daily" e "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

Métricas disponíveis

As seguintes métricas estão disponíveis na API de Insights sobre Mensagens:

Saiba mais sobre as métricas em desenvolvimento.

Propriedades de resposta

As informações a seguir podem ser retornadas em uma chamada da API de Insights.

Veja também

• Obter insights sobre a Página
• Page Insights