API Messaging Insights

В этом документе описано, как с помощью программных средств получать метрики сообщений, которые отправила и получила ваша компания. API Messaging Insights — это расширение компонента API Pages Insights, которое позволяет получать информацию, доступную на вкладке "Статистика Страницы" вашей Страницы Facebook.

Прежде чем начать

Чтобы посмотреть метрики для Страницы Facebook, которая принадлежит вам или на которой вы можете выполнять задачу ANALYZE, вашему приложению потребуются:

• ID Страницы Facebook, метрики которой вы хотите просмотреть

  • если вы отправляете сообщения в Instagram, укажите ID Страницы Facebook, связанной с профессиональным аккаунтом Instagram;
• маркер доступа к Странице;
• следующие разрешения:

  • pages_messaging;
  • pages_read_engagement;
  • pages_show_list;
  • read_insights;
• стандартный доступ.

Чтобы посмотреть метрики для Страницы Facebook, которая вам не принадлежит или на которой вы не можете выполнять задачу ANALYZE, вашему приложению потребуются:

• ID Страницы Facebook, метрики которой вы хотите просмотреть

  • если вы отправляете сообщения в Instagram, укажите ID Страницы Facebook, связанной с профессиональным аккаунтом Instagram;
• маркер доступа к Странице, запрошенный пользователем, который может выполнять задачу ANALYZE на этой Странице;
• следующие разрешения при использовании входа через Facebook:

  • pages_messaging;
  • pages_read_engagement;
  • pages_show_list;
  • read_insights;
• расширенный доступ.

Ограничения

• Чтобы новая переписка была учтена, человек должен выполнить действие, например, ответить на сообщение вашей компании. До этого момента переписка будет видна только этому человеку и не будет учитываться.

Чтение метрик статистики

Чтобы просмотреть информацию об одной или нескольких метриках, отправьте в конечную точку /PAGE-ID/insights запрос GET, указав для параметра metric список нужных метрик через запятую.

Пример запроса

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"

В случае успеха приложение получит следующий ответ в формате 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" 
        }, 
      ]
    } 
  ],
}

Пример запроса общего количества переписок за диапазон времени

Этот запрос позволяет узнать общее количество новых уникальных переписок за определенный период времени. В этот вызов API нужно добавить параметр period, задать для него значение total_over_range, а также ограничить диапазон времени параметрами since и until согласно примеру ниже.

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"

Если операция будет успешной, ваше приложение получит такой ответ в формате JSON с количеством новых уникальных переписок и указанием конца диапазона времени (см. пример ниже):

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

Пример запроса разбивки

Этот запрос позволяет узнать общее количество маркеров регулярных уведомлений за определенный период времени, а также сгруппировать их по теме и частоте, как в примере ниже.

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"

Если операция будет успешной, ваше приложение получит ответ в формате JSON, в котором маркеры будут сгруппированы по темам (newproducts и 10percentsale) и доступной для них частоте отправки уведомлений (daily, weekly и monthly — для темы newproducts; daily и weekly — для темы 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"
        },
      ]
    }
  ]
}

Параметры статистики

Доступные метрики

Ниже перечислены метрики, доступные в API Messaging Insights.

Подробнее о метриках, которые находятся в разработке

Свойства ответа

Ниже приведена информация, которая может вернуться в вызове API Insights.

Дополнительная информация

• О статистике Страницы
• О получении объектов статистики