كيفية عرض أدوات قياس حساب واتساب في التطبيق

تمنحك API إدارة حساب واتساب للأعمال إمكانية الوصول إلى أدوات القياس والتحليلات حول حساب واتساب للأعمال (WABA). يمكنك الحصول على نوعين من البيانات حول حسابك:

• تحليلات الرسائل: عدد الرسائل التي تم إرسالها وتسليمها بواسطة أرقام الهواتف المرتبطة بحساب واتساب للأعمال محدد خلال فترة معينة.
• تحليلات المحادثات: معلومات حول المحادثة والتكلفة للرسائل المرسلة خلال فترة معينة.

عند الاستعلام عن نقطة نهاية API، يتعين عليك تحديد ما إذا كنت تريد الحصول على تحليلات حول الرسائل أو المحادثات عن طريق إضافة analytics أو conversation_analytics كمعلمة لعنوان URL.

على سبيل المثال، هذه عينة من الطلب إذا كنت تريد الحصول على تحليلات الرسائل حول الحساب:

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

في هذه العينة، حددنا أننا نريد استرداد تحليلات الرسائل لأرقام الهواتف المرتبطة بحساب واتساب للأعمال الذي يحتوي على معرف حساب واتساب للأعمال فريد. ستتعرف على المزيد حول الحصول على معرف حساب واتساب للأعمال ورمز الوصول في قسم "المتطلبات" فيما بعد.

بالإضافة إلى ذلك، عند إجراء طلب، يمكنك تطبيق معلمات الفلترة لتحسين النتيجة. تدعم نقطة نهاية API إدارة الأعمال ستة معلمات فلترة إجمالاً. يجب أن يتوفر لديك ما يلي:

• start: إذا حددت تاريخ بدء، فلن تتضمن الاستجابة الرسائل المرسلة قبل التاريخ المحدد.

• end: إذا حددت تاريخ النهاية، فلن تتضمن الاستجابة الرسائل المرسلة بعد التاريخ المحدد.

• granularity: إلى أي مدى تريد أن تكون التحليلات التي يتم استردادها تفصيلية؟ تتضمن القيم المحتملة HALF_HOUR وDAY وMONTH.

بالنسبة إلى conversation_analytics، يكون لديك تسعة معلمات فلترة، ومنها ثلاثة — startو endو granularity — مطلوبة.

المتطلبات

بالنسبة إلى هذا العرض التوضيحي، ستحتاج إلى:

• تثبيت Python وpip على جهاز المطوّر المحلي.*

• التسجيل للحصول على حساب مطوّر على Meta للمطوّرين، وإنشاء تطبيق من نوع الأعمال وإضافة حساب واتساب للأعمال إلى التطبيق.

• إعداد صفحة "إضافة المنتجات إلى التطبيق"، انقر على الزر إعداد في الخيار واتساب.

بعد إنشاء تطبيق واتساب للأعمال، ستحصل على معرف حساب واتساب للأعمال ورمز وصول مؤقت. ستحتاج إلى هذين المفتاحين لبقية هذا العرض التوضيحي، لذا احتفظ بهما.

يمكنك إضافة رقم واتساب الشخصي كمرسل أو استخدام رقم الهاتف الاختباري الذي يوفره تطبيق واتساب.

إنشاء تطبيق Python لعرض البيانات

يمكنك إعداد بيئة تطوير Python وتثبيت الحزم المطلوبة.

يمكنك إنشاء مجلد، وتسميته ثم الانتقال إلى المجلد باستخدام أداة سطر الأوامر. بالنسبة لهذه المدونة، سنستخدم مكتبة الطلبات لإرسال طلبات HTTP ومكتبة Matplotlib المعروفة لإنشاء التمثيلات المرئية الثابتة والمتحركة والتفاعلية. قم بتشغيل الأمر التالي لتثبيت المكتبات:

pip install requests matplotlib

والآن، ستتمكن من استخدام طلبات Python للاستعلام عن API والحصول على تحليلات البيانات من واتساب، ثم استخدام Matplotlib لعرض أدوات القياس عن طريق إنشاء رسم بياني يتضمن نقاط البيانات المستلمة من API.

عرض عدد الرسائل المرسلة في اليوم

ابدأ من خلال طلب بيانات التحليلات. لإجراء ذلك، قم بإنشاء ملف يُسمى sent.py في مجلد التطبيق وقم باستيراد التبعيات المطلوبة لهذه المهمة:

import datetime
import requests
import matplotlib.pyplot as plt

بعد ذلك، قم بإنشاء طلب GET لـ API للحصول على تحليلات باستخدام معرف حساب واتساب للأعمال ورمز الوصول. يمكنك العثور على هذه القيم في لوحة معلومات حساب المطوّر على Meta للمطوّرين. يكون رمز طلب 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

إذا تم استخدام أرقام الهواتف المرتبطة بحساب واتساب للأعمال لإرسال رسائل في إطار زمني محدد، فسنحصل على كائن قاموس الاستجابة على النحو التالي:

{
  "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 على أربعة قواميس. ويحتوي كل منها على عدد من الرسائل التي أرسلتها واستلمتها أرقام واتساب المرتبطة خلال نطاق تاريخ محدد.

والآن بعد الحصول على البيانات، يجب استرداد المعلومات الضرورية. بما أننا نريد عرض عدد الرسائل المرسلة كل يوم، يجب الحصول على القيم 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()

من هنا، يمكنك إنشاء رسم بياني بسيط يضم الأيام على طول المحور س وعدد الرسائل المرسلة على طول المحور ص.

احفظ الملف وقم بتشغيل الرمز. إذا كنت تستخدم نظام 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

إذا قمت بتشغيل الرمز، فستحصل على رسم بياني يبدو كما يلي:

بعد ذلك، يمكنك إنشاء رسم بياني لعرض عدد الرسائل المستلمة.

عرض المعلومات الخاصة برقم واتساب محدد

في القسم السابق، لم نقم بتضمين أرقام الهواتف في الطلب. نتيجةً لذلك، قامت API بإرجاع معلومات حول كل أرقام الهواتف المرتبطة بحساب واتساب للأعمال ضمن تواريخ البدء والانتهاء المحددة.

ومع ذلك، إذا أردت استرداد بيانات التحليلات لرقم هاتف واحد أو عدة أرقام، ولكن ليس كل الأرقام، فيجب وضع أرقام الهواتف في مصفوفة وإدخالها في الأسلوب 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 كما هو. ستحصل فقط على التحليلات حول أرقام الهواتف المحددة عند تنفيذه.

عرض عدد الرسائل التي يتم تسليمها في اليوم

في القسمين الأخيرين، قمنا بإنشاء رسم بياني لعرض عدد الرسائل المرسلة لكل يوم بواسطة أرقام الهواتف المرتبطة عبر واتساب. والآن، لننشئ رسمًا بيانيًا لعرض عدد الرسائل التي يتم تسليمها يوميًا.

يمكنك إنشاء ملف جديد وتسميته 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 إدارة حساب واتساب للأعمال.

الخلاصة

في هذا العرض التوضيحي، استخدمنا مكتبة عرض البيانات matplotlib لعرض البيانات التي تُظهر عدد الرسائل التي يتم إرسالها في اليوم وعدد الرسائل التي يتم تسليمها في اليوم وتكلفة كل محادثة رسائل.

توفر API إدارة حساب واتساب للأعمال معلمات الفلترة هذه وغير ذلك المزيد، والتي يمكنك استخدامها لتحديد أدوات القياس التي تريدها في كل طلب. للتعرف على المزيد، تحقق من وثائق API الكاملة.

بصفتك مطوّرا، توفر لك API إدارة حساب واتساب للأعمال المعلومات وأدوات القياس ذات الصلة من حساب واتساب للمستخدمين. على سبيل المثال، يمكنك عرض عدد رسائل واتساب التي أرسلها المستخدمين في يوم محدد في لوحة المعلومات لدى المستخدمين.

لا حدود للإمكانات!