Визуализация метрик аккаунта WhatsApp в вашем приложении

API WhatsApp Business Management обеспечивает доступ к метрикам и аналитической информации о вашем аккаунте WhatsApp Business (WABA). Для своего аккаунта вы можете получить данные двух типов:

• Аналитика для сообщений: число отправленных и доставленных сообщений с разбивкой по телефонным номерам, связанным с определенным аккаунтом WhatsApp Business, за указанный период.
• Аналитика для переписок: информация о переписках и стоимости для сообщений, отправленных в указанный период.

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

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

https://graph.facebook.com/v14.0/{whatsapp-business-account-ID}
      ?fields=analytics
      .{filtering-parameters}
      &{access-token}

В этом примере мы указали, что хотим получить аналитику сообщений для номеров телефона, которые связаны с аккаунтом WhatsApp Business, имеющим уникальный ID. Более подробная информация о получении ID WhatsApp Business и маркера доступа содержится в нижеприведенном разделе "Требования".

Кроме того, отправляя запрос, вы можете применить параметры фильтрации и получить более точные результаты. Всего конечная точка API Business Management поддерживает 6 параметров фильтрации. У вас должны быть следующие параметры:

• start: если вы укажете начальную дату, ответ не будет содержать сообщения, отправленные до этой даты.

• end: если вы укажете конечную дату, ответ не будет содержать сообщения, отправленные после этой даты.

• granularity: насколько детальной должна быть полученная аналитика? Возможными значениями могут быть HALF_HOUR, DAY и MONTH.

Для поля conversation_analyticsвам доступны 9 параметров фильтрации, из которых 3 — start, end и granularity — являются обязательными.

Требования

Для работы с этим руководством вам необходимо:

• Установить Python и pip на локальное устройство, которое используется для разработки.*

• Зарегистрировать аккаунт разработчика на сайте Meta for Developers, создать бизнес-приложение и добавить в него аккаунт WhatsApp Business.

• Выполнить настройку — на странице "Добавить продукты в ваше приложение" нажмите кнопку Настроить для WhatsApp.

После создания бизнес-приложения WhatsApp Business вы получите ID WhatsApp Business и временный маркер доступа. Оба ключа вам понадобятся для дальнейшей работы с этим руководством, поэтому сохраните их.

Для отправки вы можете добавить свой личный номер WhatsApp или использовать тестовый номер телефона, предоставленный WhatsApp.

Создание приложения Python для визуализации данных

Настройте среду разработки Python и установите необходимые пакеты.

Создайте папку, присвойте ей имя, а затем перейдите в эту папку с использованием инструмента командной строки. В этом сообщении блога мы будем использовать библиотеку запросов для отправки запросов HTTP и популярную библиотеку Matplotlib для создания статичных, анимированных и интерактивных визуализаций. Для их установки запустите следующую команду:

pip install requests matplotlib

Теперь вы сможете использовать запросы Python, чтобы запрашивать у API данные аналитики из WhatsApp, а затем использовать библиотеку Matplotlib, чтобы визуализировать метрики путем создания графика с точками данных, полученными от API.

Визуализация числа сообщений, отправленных за день

Начните с запроса данных аналитики. Для этого в папке своего приложения создайте файл с именем sent.py и импортируйте зависимости, необходимые для этой задачи:

import datetime
import requests
import matplotlib.pyplot as plt

Затем создайте запрос API GET для получения аналитики с использованием вашего ID WhatsApp Business и маркера доступа. Эти значения можно найти на панели вашего аккаунта разработчика на сайте Meta for Developer. Код для запроса GET выглядит следующим образом:

key = 'put-your-access-token-here'
waba_id = 'put-your-waba-id-here'

res = requests.get(f'https://graph.facebook.com/v14.0/{waba_id}?fields=analytics.start(1662174000).end(1662548446).granularity(DAY)&access_token={key}')

dict = res.json() 
print(dict)

В приведенном выше запросе начальная дата представлена в формате UNIX, как это необходимо для API. Вы можете использовать этот бесплатный инструмент для преобразования, чтобы переводить метки времени из понятной для человека формы в форматом UNIX и обратно. Этот код преобразовывает ответ в формат JSON в последней строке и представляет его в печатном виде.

Для запуска кода выполните следующую команду:

python app.py

Если номера телефонов, связанные с аккаунтом WhatsApp Business, используются для отправки сообщений в установленные временные рамки, мы получим объект словаря ответа, который имеет следующий вид:

{
  "analytics": {
    "phone_numbers": [
      "16505550111",
      "16505550112",
      "16505550113"
    ],
    "country_codes": [
      "US",

    ],
    "granularity": "DAY",
    "data_points": [
      {
        "start": 1662174000,
        "end": 1662260400,
        "sent": 199251,
        "delivered": 183001
      },
      {
        "start": 1662260400,
        "end": 1662346800,
        "sent": 162489,
        "delivered": 141234
      },
      {
        "start": 1662346800,
        "end": 1662433200,
        "sent": 67902,
        "delivered": 53902
      },
      {
        "start": 1662433200,
        "end": 1662519600,
        "sent": 129521,
        "delivered": 117832
      }
    ]
  },
  "id": "952305634918047"
}

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

Теперь, когда у вас есть данные, вы должны получить необходимую информацию. Поскольку мы хотим визуализировать число сообщений, отправляемых каждый день, мы должны получить значения start и sent из каждого словаря.

Чтобы сделать это, пройдите в цикле по точкам данных с использованием цикла for...in в Python. Преобразуйте начальное время из формата UNIX в человекочитаемую форму для каждого объекта данных. Затем получите только числовое значение дня месяца и добавьте его в список дней. Сохраните число отправленных сообщений в другом списке с именем no_of_msgs_sent:

days = []
no_of_msgs_sent = []

data_points = dict.get("analytics").get("data_points")

for point in data_points:
    
    # Get date in human readable format
    x = datetime.datetime.fromtimestamp(point.get('start'))
    
    # Get just the day in string format
    y = x.strftime("%d")
    
    days.append(y)
    
    # Add the number of sent messages to the list 
    no_of_msgs_sent.append(point.get('sent'))
    
print(days)
print(no_of_msgs_sent)

If you run the code, you get two lists:

['03', '04', '05', '06'] // days
[196093, 147649, 61988, 132465] // number of messages

Now that you have what you need, it's time to visualize it. Add the following code to app.py:

plt.plot(days, no_of_msgs_sent)

plt.title('Our Graph')
plt.xlabel('Days')
plt.ylabel('Number of messages sent')

plt.show()

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

Сохраните файл и запустите свой код. Если вы работаете на Linux и получаете следующее сообщение:

UserWarning: Matplotlib is currently using agg, which is a non-GUI backend, so cannot show the figure.

Проверьте, установлен ли у вас компонент tkinter. Если нет, запустите следующую команду для его установки:

sudo apt-get install python3-tk

Если вы запустите код, вы получите график, имеющий следующий вид:

Затем вы создадите график для визуализации числа доставленных сообщений.

Визуализация информации для определенного номера WhatsApp

В предыдущем разделе мы не включали в запрос номера телефонов. В результате API возвращал информацию для всех телефонных номеров, связанных с аккаунтом WhatsApp Business, в рамках указанных начальных и конечных дат.

Однако, если вам необходимо получить аналитические данные лишь для одного или нескольких номеров телефонов, а не для всех, вы должны поместить соответствующие номера в массив и передать его в метод .phone_numbers при создании запроса:

res = requests.get(f'https://graph.facebook.com/v14.0/{waba_id}?fields=analytics.start(1662174000).end(1662548446).phone_numbers([16505550111, // others]).granularity(DAY)&access_token={key}')

Остальной код в файле sent.py остается без изменений. Выполнив этот код, вы получите аналитику только для указанных номеров телефонов.

Визуализация числа сообщений, доставленных за день

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

Создайте новый файл и присвойте ему имя delivered.py. Затем скопируйте код из файла sent.py в файл delivered.py.

После этого внесите несколько изменений в код в файле delivered.py. Сначала измените имя переменной в верхней части с no_of_msgs_sent на no_of_msgs_del для указания типа данных, которые вы сохраняете.

Затем в цикле for...in измените значение в методе point.get с sent на delivered. Вот фрагмент того, как должен выглядеть ваш код после внесения указанных изменений:

# Variables go here

for point in data_points:
    
    # Code for getting human readable date goes here    
    
    # Now add the number of delivered messages to the list  
    no_of_msgs_del.append(point.get('delivered'))

print(day)
print(no_of_msgs_del)

Finally, specify no_of_msgs_del in the plt.plot method and update the label shown on the y-axis:

plt.plot(days, no_of_msgs_del)

plt.title('Our Graph')
plt.xlabel('Days')
plt.ylabel('Number of messages delivered')

plt.show()

После того, как вы запустите код на своем терминале (с использованием python delivered.py), вы получите график, похожий на приведенный ниже.

Теперь, когда вы представили два комплекта данных аналитики для сообщений, следующим шагом будет представление стоимости сообщений с использованием поля conversation_analytics.

Визуализация стоимости сообщений, отправленных за день

Как и раньше, для этого раздела создайте новый файл и присвойте ему имя cost.py. Скопируйте код из файла sent.py в файл cost.py. Теперь давайте внесем несколько изменений.

Сначала измените код запроса. Поскольку вы получаете информацию о переписках, установите для параметра fields значение conversation_analytics и установите для параметра granularity на daily.

res = requests.get(f'https://graph.facebook.com/v14.0/{waba_id}?fields=conversation_analytics.start(1662174000).end(1662548446).granularity(DAILY).phone_numbers([])&access_token={key}')

Обратите внимание, что поле conversation_anaytics поддерживает несколько дополнительных параметров фильтрации для получения информации и других типов. Подробнее см. в полной документации.

После отправки вышеуказанного запроса вы должны получить объект ответа, очень похожий на следующий:

{
  "conversation_analytics": {
    'data': {
        "data_points": [
          {
            "start": 1662174000,
            "end": 1662260400,
            "conversation": 5250,
            "cost": 45.0532
          },
          {
            "start": 1662260400,
            "end": 1662346800,
            "conversation": 2250,
            "cost": 25.0290
          },
          {
            "start": 1662346800,
            "end": 1662433200,
            "conversation": 800,
            "cost": 0.0000
          },
          {
            "start": 1662433200,
            "end": 1662519600,
            "conversation": 3150,
            "cost": 33.2015
          }
        ]
    }
  },
}

Как видно выше, параметры data_points находятся внутри словаря данных. Для каждой точки данных в словаре указаны сумма преобразования и стоимость.

Затем в файле cost.pyизмените имя переменной в верхней части с no_of_msgs_del на cost_of_convo. В цикле for...in измените значение в методе point.get с delivered на cost. Вот фрагмент того, как должен выглядеть ваш код после внесения указанных изменений:

days = []
cost_of_convo = []

data_points = dict.get('conversation_analytics').get("data").get("data_points")

for point in data_points:
   
    x = datetime.datetime.fromtimestamp(point.get('start'))   
    y = x.strftime("%d")
    
    days.append(y)
    
    # Add the cost of messages in each data point
    cost_of_convo.append(point.get('cost'))

Now, to plot a graph visualizing it:

plt.plot(days, cost_of_convo)

plt.title('Our Graph')
plt.xlabel('Days')
plt.ylabel('Cost of messages sent')

plt.show()

Если вы запустите свой код на терминале (с использованием python cost.py), вы получите график, похожий на следующий:

Готово!

Если вы хотите пойти дальше, можете использовать этот же метод для визуализации других метрик, которые предоставляются API WhatsApp Business Management.

Заключение

В этом руководстве мы использовали библиотеку визуализации данных matplotlib, чтобы показать данные, демонстрирующие число сообщений, отправленных за день, число сообщений, доставленных за день, и стоимость каждой беседы, в которой используются сообщения.

API WhatsApp Business Management предлагает вам эти параметры фильтрации, как и многие другие, которые вы можете использовать для указания необходимых метрик в каждом запросе. Подробную информацию см. в полной документации по API.

Как разработчику API WhatsApp Business Management предоставляет вам соответствующую информацию и метрики из аккаунтов WhatsApp ваших пользователей. Например, вы можете показать своим пользователям число сообщений, которые они отправили в WhatsApp в тот или иной день, отобразив это значение на панели.

Возможности поистине безграничны!