التحليلات

يشرح هذا المستند كيفية الحصول على تحليلات المراسلة والمحادثة والقالب، مثل عدد الرسائل المرسلة من رقم هاتف نشاط تجاري وعدد المحادثات وتكاليفها في حساب واتساب للأعمال (WABA) أو عدد مرات قراءة قالب معين.

لن يتم تضمين سوى أدوات القياس لأرقام هواتف وقوالب النشاط التجاري المرتبطة بحساب واتساب للأعمال وقت الطلب في الاستجابات.

الحصول على البيانات

استخدم نقطة نهاية حساب واتساب للأعمال للحصول على التحليلات.

بنية الاستعلام

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>
  ?fields=<FIELDS>.<FILTERING_PARAMETER>

معلمات سلسلة الاستعلام

تحليلات المراسلة

يوفر الحقل analytics نوع وعدد الرسائل التي تم إرسالها وتسليمها بواسطة أرقام الهواتف المرتبطة بحساب واتساب للأعمال محدد، وبالنسبة لأدوات قياس المحادثة، راجع تحليلات المحادثات. عند استدعاء /{whatsapp-business-account-ID}?fields=analytics.{filtering-parameters}، يمكنك إرفاق المعلمات التالية.

معلمات التحليلات

مثال

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

الحل المقترح:قم بتجميع عنوان URL الذي تريد استدعاؤه وتضمين معلمات الفلترة التالية: start وend وgranularity. ومن ثم، قم بإجراء الطلب GET إلى عنوان URL هذا:

curl -i -X GET \ 
"https://graph.facebook.com/v19.0/{whatsapp-business-account-ID}
      ?fields=analytics
      .start(1543543200)
      .end(1544148000)
      .granularity(DAY)
      &access_token={access-token}"

تعمل الاستجابة الناجحة على إرجاع كائن analytics يتضمن البيانات التي طلبتها:

{
  "analytics": {
    "phone_numbers": [
      "16505550111",
      "16505550112",
      "16505550113"
    ],
    "country_codes": [
      "US",
      "BR"
    ],
    "granularity": "DAY",
    "data_points": [
      {
        "start": 1543543200,
        "end": 1543629600,
        "sent": 196093,
        "delivered": 179715
      },
      {
        "start": 1543629600,
        "end": 1543716000,
        "sent": 147649,
        "delivered": 139032
      },
      {
        "start": 1543716000,
        "end": 1543802400,
        "sent": 61988,
        "delivered": 58830
      },
      {
        "start": 1543802400,
        "end": 1543888800,
        "sent": 132465,
        "delivered": 124392
      }
      # more data points
    ]
  },
  "id": "102290129340398"
}

تحليلات المحادثات

يوفر الحقل conversation_analyticsمعلومات حول المحادثة والتكلفة في حساب واتساب للأعمال محدد. عند استدعاء /{whatsapp-business-account-ID}?fields=conversation_analytics.{filtering-parameters}، يمكنك إرفاق المعلمات التالية.

معلمات تحليلات المحادثات

أمثلة

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

الحصول على بيانات شهرية، واستخدام كل التقسيمات

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

الحل المقترح:قم بتجميع عنوان URL الذي تريد استدعاؤه وتضمين معلمات الفلترة التالية:

• start: بداية النطاق الزمني لديك. في هذه الحالة، ستكون بداية الشهر الذي تريد الحصول على أدوات القياس خلاله.
• end: نهاية النطاق الزمني لديك. في هذه الحالة، ستكون نهاية الشهر الذي تريد الحصول على أدوات القياس خلاله.
• granularity: مستوى الدقة الذي ترغب في الحصول على نقاط البيانات من خلاله. في المثال التالي، نستخدم MONTHLY، لذلك كل نقطة بيانات ستمثل قيمة شهرية من البيانات.
• phone_numbers: أرسل مصفوفة فارغة، وسيتم إرجاع المعلومات الخاصة بكل أرقام الهواتف المرتبطة بحساب واتساب للأعمال.
• dimensions: قم بتعيينه إلى كل التقسيمات المتوفرة: "CONVERSATION_CATEGORY" و"CONVERSATION_TYPE" و"COUNTRY" و"PHONE".

في هذه الحالة، لن تحتاج إلى تحديد country_codes وmetric_types وconversation_types وconversation_categories. إذا لم ترسل لنا أي شيء بخصوص تلك الحقول، فسيتم إرجاع كل الخيارات المتوفرة. بمجرد إعداد عنوان URL، قم بإجراء طلب GET:

curl -i -X GET
"https://graph.facebook.com/v19.0/{whatsapp-business-account-id}
  ?fields=conversation_analytics
  .start(1685602800).end(1688194800)
  .granularity(MONTHLY)
  .phone_numbers([])
  .dimensions(["CONVERSATION_CATEGORY","CONVERSATION_TYPE","COUNTRY","PHONE"])
  &access_token={access-token}"

تعمل الاستجابة الناجحة على إرجاع كائن conversation_analytics يتضمن البيانات التي طلبتها. في المثال التالي، يحتوي حساب واتساب للأعمال على رقم هاتف واحد فقط.

{
  "conversation_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1558,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_direction": "UNKNOWN",
            "conversation_category": "AUTHENTICATION",
            "cost": 15.58
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 2636,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_category": "MARKETING",
            "cost": 26.36
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 2238,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_category": "SERVICE",
            "cost": 22.38
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1782,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_category": "UTILITY",
            "cost": 17.82
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1568,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_TIER",
            "conversation_category": "AUTHENTICATION",
            "cost": 15.68
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 2716,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_TIER",
            "conversation_category": "MARKETING",
            "cost": 27.16
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 2180,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_TIER",
            "conversation_category": "SERVICE",
            "cost": 21.8
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1465,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_TIER",
            "conversation_category": "UTILITY",
            "cost": 14.65
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1433,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_ENTRY_POINT",
            "conversation_category": "SERVICE",
            "cost": 14.33
          }
        ]
      }
    ]
  },
  "id": "102290129340398",
}

الحصول على بيانات لرقم هاتف محدد، واستخدام كل التقسيمات ومستوى دقة ضمن نصف ساعة

السيناريو: خلال نطاق زمني محدد، تريد استرداد كل معلومات التكلفة والمحادثة لرقم هاتف محدد مرتبط بحساب واتساب للأعمال. وترغب في استخدام كل التقسيمات الممكنة ضمن النتائج. كما يجب أن تمثل كل نقطة بيانات ما يعادل نصف ساعة من البيانات.

الحل المقترح:قم بتجميع عنوان URL الذي تريد استدعاؤه وتضمين معلمات الفلترة التالية:

• start: بداية النطاق الزمني لديك.
• end: نهاية النطاق الزمني لديك.
• granularity: مستوى الدقة الذي ترغب في الحصول على نقاط البيانات من خلاله. في المثال التالي، نستخدم HALF_HOUR، لذلك تمثل كل نقطة بيانات ما يعادل نصف ساعة من البيانات.
• phone_numbers: رقم الهاتف التي تريد الحصول على معلومات حوله.
• dimensions: قم بتعيينه إلى كل التقسيمات المتوفرة: CONVERSATION_CATEGORY وCONVERSATION_TYPE وCOUNTRY وPHONE.

في هذه الحالة، لن تحتاج إلى تحديد country_codes أو metric_types أو conversation_types أو conversation_categories. إذا لم ترسل لنا أي شيء بخصوص تلك الحقول، فسيتم إرجاع كل الخيارات المتوفرة. بمجرد إعداد عنوان URL، قم بإجراء طلب GET:

curl -i -X GET \
"https://graph.facebook.com/v19.0/{whatsapp-business-account-id}
  ?fields=conversation_analytics
  .start(1685602800)
  .end(1685689200)
  .granularity(HALF_HOUR)
  .phone_numbers(["19195552584"])
  .dimensions(["CONVERSATION_CATEGORY","CONVERSATION_TYPE","COUNTRY,PHONE"])
  &access_token=your-access-token"

تعمل الاستجابة الناجحة على إرجاع كائن conversation_analytics يتضمن البيانات التي طلبتها:

{
  "conversation_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1685602800,
            "end": 1685604600,
            "conversation": 4,
            "phone_number": "19195552584",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_direction": "UNKNOWN",
            "conversation_category": "SERVICE",
            "cost": 0.0232
          },
          {
            "start": 1685602800,
            "end": 1685604600,
            "conversation": 4,
            "phone_number": "19195552584",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_direction": "UNKNOWN",
            "conversation_category": "MARKETING",
            "cost": 0.0232
          },
         # ... more data points
        ]
      }
    ]
  },
  "id": "102290129340398"
}

الحصول على البيانات الشهرية، واستخدام تقسيمات نوع المحادثة

السيناريو: خلال نطاق زمني محدد، تريد استرداد كل معلومات التكلفة والمحادثة لكل أرقام الهواتف المرتبطة بحساب واتساب للأعمال. وضمن النتائج، ترغب في التقسيم حسب نوع المحادثة.

الحل المقترح:قم بتجميع عنوان URL الذي تريد استدعاؤه وتضمين معلمات الفلترة التالية:

• start: بداية النطاق الزمني لديك.
• end: نهاية النطاق الزمني لديك.
• granularity: مستوى الدقة الذي ترغب في الحصول على نقاط البيانات من خلاله. في المثال التالي، نستخدم MONTHLY، لذلك تمثل كل نقطة بيانات ما يعادل نصف شهر من البيانات.
• phone_numbers: أرسل مصفوفة فارغة، وسيتم إرجاع المعلومات الخاصة بكل أرقام الهواتف المرتبطة بحساب واتساب للأعمال.
• dimensions: قم بتعيينها إلى CONVERSATION_TYPE.

في هذه الحالة، لن تحتاج إلى تحديد country_codes أو metric_types أو conversation_types أو conversation_directions أو conversation_categories. إذا لم ترسل لنا أي شيء بخصوص تلك الحقول، فسيتم إرجاع كل الخيارات المتوفرة. بمجرد إعداد عنوان URL، قم بإجراء طلب GET:

curl -i -X GET
"https://graph.facebook.com/v19.0/{whatsapp-buiness-account-id}
      ?fields=conversation_analytics
      .start(1643702400).end(1646121600)
      .granularity(MONTHLY)
      .phone_numbers([])
      .dimensions([CONVERSATION_TYPE])
      &access_token={access-token}"

تعمل الاستجابة الناجحة على إرجاع كائن conversation_analytics يتضمن البيانات التي طلبتها:

{
  "data": [
    {
      "data_points": [
        {
          "start": 1643702400,
          "end": 1646121600,
          "conversation": 8500,
          "conversation_type": "REGULAR",
          "cost": 88.1010
        },
        {
          "start": 1643702400,
          "end": 1646121600,
          "conversation”: 1000,
          "conversation_type": "FREE_TIER",
          "cost": 0.0000
        }
        {
          "start": 1643702400,
          "end": 1646121600,
          "conversation”: 250,
          "conversation_type": "FREE_ENTRY_POINT",
          "cost": 0.0000
        }
      ]
    }
  ]
}

تقسيم نصف ساعة من البيانات حسب فئة المحادثة

الطلب:

curl -i -X GET \
 "https://graph.facebook.com/v19.0/{whatsapp-buiness-account-id}
  ?fields=conversation_analytics
  .start(1685527200)
  .end(1685613600)
  .granularity(HALF_HOUR)
  .conversation_categories(["MARKETING","AUTHENTICATION"])
  .dimensions(["CONVERSATION_CATEGORY"])
  &access_token={access-token}"  

الاستجابة:

{
  "conversation_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1685529000,
            "end": 1685530800,
            "conversation": 2,
            "conversation_category": "AUTHENTICATION",
            "cost": 0.0128
          },
          {
            "start": 1685527200,
            "end": 1685529000,
            "conversation": 3,
            "conversation_category": "MARKETING",
            "cost": 0.0432
          }
        ]
      }
    ]
  },
  "id": "102290129340398"
}

### تقسيم نصف ساعة من البيانات حسب نوع المحادثة وفئة المحادثة

الطلب:

curl -i -X GET \
 "https://graph.facebook.com/v19.0/{whatsapp-buiness-account-id}
  ?fields=conversation_analytics
  .start(1685527200)
  .end(1685613600)
  .granularity(HALF_HOUR)
  .conversation_categories(["MARKETING","AUTHENTICATION"])
  .dimensions(["CONVERSATION_CATEGORY","CONVERSATION_TYPE"])
  &access_token={access-token}"  

الاستجابة:

{
  "conversation_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1685527200,
            "end": 1685529000,
            "conversation": 3,
            "conversation_type": "REGULAR",
            "conversation_category": "MARKETING",
            "cost": 0.0432
          },
          {
            "start": 1685529000,
            "end": 1685530800,
            "conversation": 2,
            "conversation_type": "REGULAR",
            "conversation_category": "AUTHENTICATION",
            "cost": 0.0128
          }
        ]
      }
    ]
  },
  "id": "102290129340398"
}

تحليلات القالب

تصف تحليلات القالب عدد مرات إرسال القالب واستلامه وقراءته وعدد مرات النقر على أزرار عنوان URL أو أزرار الرد السريع في القالب.

يتم إرجاع البيانات بتفاصيل يومية في النطاق الزمني UTC بنطاق سجل يصل إلى 90 يومًا. يمكن أيضًا العثور على تحليلات القالب في اللوحة مدير واتساب > قوالب الرسالة > تفاصيل القالب > الرؤى.

التقييدات

• لا تتوفر تحليلات القوالب إلا لـ API داخل المواقع فقط إذا لم يكن الحساب مشتركًا في تحليلات قوالب API السحابة.
• تخضع تحليلات قوالب API داخل المواقع لإرشادات التجميع وإخفاء معلومات الهوية، والتي تتطلب وجود 1000 حدث كحد أدنى قبل عرض العدد للمستخدم.
• لا تتوفر تحليلات النقر على الزر إلا للقوالب التي تم تصنيفها كـ MARKETING أو UTILITY.
• لا يتم دعم حسابات واتساب للأعمال المملوكة أو التي تتم مشاركتها مع حسابات Meta للأعمال في الاتحاد الأوروبي أو المملكة المتحدة أو اليابان أو تلك التي لديها رقم هاتف نشاط تجاري بكود اتصال بالبلد من أي من هذه البلدان أو المناطق.

الإبلاغ عن الأخطاء

للإبلاغ عن أخطاء في تحليلات القالب، أرسل تذكرة دعم مباشر بالتحديدات التالية:

• موضوع السؤال: WABiz: API السحابة
• نوع الطلب: خطأ أو مشكلة في التنفيذ

تأكيد تحليلات القالب

يجب تأكيد تحليلات القالب في حساب واتساب للأعمال قبل أن تتمكن من الحصول على تحليلات القالب. يمكنك تأكيد تحليلات القالب باستخدام مدير واتساب أو API. للتأكيد عبر API، أرسل الطلب التالي:

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>?is_enabled_for_insights=true

بمجرد التأكيد، سنبدأ بالتقاط تحليلات القالب في حساب واتساب للأعمال. بمجرد التأكيد، سيتعذر تعطيل تحليلات القالب.

عند نجاح العملية، ستستجيب API بمعرف حساب واتساب للأعمال. على سبيل المثال:

{                          
  "id": 102290129340398
}

معلمات تحليلات القالب

أمثلة

الحصول على كل تحليلات القالب

السيناريو: في فترة يومين، احصل على كل تحليلات القالب المتوفرة لقالب رسالة واحدة مرتبط بحساب واتساب للأعمال.

مثال على الطلب:

curl -g 'https://graph.facebook.com/v19.0/109259195336416/template_analytics?start=1689379200&end=1689552000&granularity=DAILY&metric_types=[%27SENT%27%2C%27DELIVERED%27%2C%27READ%27%2C%27CLICKED%27]&template_ids=[1924084211297547%2C954638012257287]' \
-H 'Authorization: Bearer EABN8...'

نموذج للاستجابة:

{
  "data": [
    {
      "granularity": "DAILY",
      "data_points": [
        {
          "template_id": "1924084211297547",
          "start": 1689379200,
          "end": 1689465600,
          "sent": 0,
          "delivered": 0,
          "read": 0,
          "clicked": [
            {
              "type": "quick_reply_button",
              "button_content": "Tell me more",
              "count": 3
            },
            {
              "type": "quick_reply_button",
              "button_content": "Get coupon",
              "count": 5
            }
          ]
        },
        {
          "template_id": "1924084211297547",
          "start": 1689465600,
          "end": 1689552000,
          "sent": 0,
          "delivered": 0,
          "read": 0,
          "clicked": [
            {
              "type": "quick_reply_button",
              "button_content": "Tell me more",
              "count": 73
            },
            {
              "type": "quick_reply_button",
              "button_content": "Get coupon",
              "count": 35
            }
          ]
        },
        {
          "template_id": "954638012257287",
          "start": 1689379200,
          "end": 1689465600,
          "sent": 0,
          "delivered": 0,
          "read": 0,
          "clicked": [
            {
              "type": "url_button",
              "button_content": "Visit Website",
              "count": 13
            }
          ]
        },
        {
          "template_id": "954638012257287",
          "start": 1689465600,
          "end": 1689552000,
          "sent": 0,
          "delivered": 0,
          "read": 0,
          "clicked": [
            {
              "type": "url_button",
              "button_content": "Visit Website",
              "count": 12
            }
          ]
        }
      ]
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MjQZD"
    }
  }
}

تعطيل تحليلات النقر على الزر

يمكنك تعطيل تتبع النقر على الزر في قالب منفرد عن طريق تعيين الحقل cta_url_link_tracking_opted_out على true. بمجرد التعطيل، لن تعمل API بعد على إرجاع الخاصية التي تم النقر عليها في تحليلات القالب أو لن تعرض النقرات/التفاعل مع الزر في مدير واتساب عند عرض رؤى القالب.

بنية الطلب

POST /<TEMPLATE_ID>
  ?cta_url_link_tracking_opted_out=<OPT_OUT>
  &category=<TEMPLATE_CATEGORY>

معلمات الطلب

مثال على الطلب

curl -X POST 'https://graph.facebook.com/v19.0/245435364965041?cta_url_link_tracking_opted_out=true&category=marketing' \
-H 'Authorization: Bearer EAAJB...'

مثال على الاستجابة

عند نجاح العملية، ستستجيب API بما يلي:

{
    "success": true
}

المرجع

للحصول على قائمة بكل القيم الممكنة لكل حقل، يمكنك الرجوع إلى مرجع واجهة Graph API في حقل تحليلات حساب واتساب للأعمال.