إحصائيات الرسائل

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

messages:list

يعرض قائمة الرسائل المرسلة.

POST https://api.pushwoosh.com/api/v2/messages:list

ترويسات

الاسم	مطلوب	الوصف
`Authorization`	نعم	رمز API للخادم. يجب توفيره بالتنسيق التالي: `Authorization: Api <Server Key>`.

معلمات نص الطلب

الاسم	مطلوب	النوع	الوصف
`platforms`	لا	Array	منصات الرسائل. القيم الممكنة: `"IOS"`, `"ANDROID"`, `"OSX"`, `"WINDOWS"`, `"AMAZON"`, `"SAFARI"`, `"CHROME"`, `"FIREFOX"`, `"IE"`, `"EMAIL"`, `"HUAWEI_ANDROID"`, `"SMS"`.
`date_range`	لا	Object	فترة التقرير، مفلترة حسب تاريخ إنشاء الرسالة. يجب أن يتبع `date_from` و `date_to` تنسيق `YYYY-MM-DD` (على سبيل المثال، `"2000-01-01"`)؛ يتم تضمين كلا اليومين بالكامل، لذا فإن تعيين `date_from` و `date_to` على نفس التاريخ يعيد ذلك اليوم بأكمله. يتم تفسير التواريخ بتوقيت UTC، وليس في المنطقة الزمنية لحسابك.
`campaign`	لا	String	رمز الحملة
`filters`	نعم	Object	فلاتر الرسائل.
`source`	لا	String	مصدر الرسالة. على سبيل المثال: `AB_TEST`, `API`, `AUTO_PUSH`, `CP`, `CSV`, `CUSTOMER_JOURNEY`, `EMAIL_API`, `EMAIL_CP`, `GEO_ZONE`, `PUSH_ON_EVENT`, `RSS`.
`messages_codes`	لا	Array	رموز الرسائل التي تم الحصول عليها من استجابات واجهة برمجة التطبيقات `/createMessage`.
`messages_ids`	لا	Array	معرفات الرسائل التي تم الحصول عليها من سجل الرسائل
`message_type`	لا	String	فلتر نوع تدفق الرسائل. القيم الممكنة: `"TRANSACTIONAL"`, `"BROADCAST"`, `"ALL"`. القيمة الافتراضية `"ALL"` عند عدم تحديده.
`params`	لا	Object	حدد ما إذا كنت تريد إظهار تفاصيل الرسالة ومقاييسها. اضبط `with_details: true` لتضمين كائن `"details"` و `with_metrics: true` لتضمين كائن `"metrics"` في الاستجابة.
`application`	نعم	String	رمز تطبيق Pushwoosh.
`per_page`	لا	Integer	عدد النتائج لكل صفحة، من `1` إلى `499`. احذف المعلمة للحصول على حجم الصفحة الافتراضي وهو 500 نتيجة؛ يتم رفض تمرير `500` أو أكثر بشكل صريح مع `400`.
`page`	لا	Integer	رقم الصفحة المستند إلى الصفر للترقيم. انظر حد الترقيم العميق أدناه.

يرفض messages:list الطلبات حيث يتجاوز page × per_page 100000 نتيجة. قم بتضييق date_range أو استخدم per_page أصغر للبقاء ضمن الحد.

total هو العدد الدقيق للرسائل التي تطابق الفلاتر بينما يكون هذا الرقم عند أو أقل من 100000، ويتوقف عند 100001 فوق ذلك — أكثر مما يمكن لهذه النقطة النهائية تصفحه. لا تقم بحجم حلقة صفحة تتجاوز هذا الحد: يتم رفض الصفحات التي تتجاوزه، وليست فارغة. لسحب فترة تحتوي على رسائل أكثر من ذلك، قم بتضييق date_range لكل طلب، أو استخدم التصدير غير المتزامن، الذي يكتب الفترة بأكملها إلى ملف CSV واحد دون ترقيم.

message_type يحدد أيضًا مدى رجوع الطلب الذي لا يحتوي على تاريخ.

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

{
    "filters": {
      "platforms": [],                  // IOS, ANDROID, OSX, WINDOWS, AMAZON, SAFARI, CHROME, FIREFOX, IE, EMAIL, HUAWEI_ANDROID, SMS
      "date_range": {
        "date_from": "string",          // Required format: 2000-01-01
        "date_to": "string"             // Required format: 2000-01-01
      },
      "source": "API",                  // AB_TEST, API, AUTO_PUSH, CP, CSV, CUSTOMER_JOURNEY, EMAIL_API, EMAIL_CP, GEO_ZONE, PUSH_ON_EVENT, RSS
      "campaign": "string",             // Campaign code
      "messages_ids": [],               // Message IDs
      "messages_codes": [],             // Message codes
      "message_type": "ALL",            // TRANSACTIONAL, BROADCAST, ALL (default)
      "application": "string"           // Pushwoosh application code
    },
    "params": {
      "with_details": true,             // Add message details to the response ("details" object)
      "with_metrics": true              // Add message metrics to the response ("metrics" object)
    },
    "per_page": 20,                     // <= 499
    "page": 0
}

رموز الاستجابة والأمثلة

{
  "total": 0,
  "items": [{
    "id": 0,
    "code": "string",
    "created_date": "string",
    "send_date": "string",
    "status": "string",
    "platforms": [],
    "source": "string",
    "push_info": {
      "details": {
        "title": "string",
        "filter_name": "string",
        "filter_code": "string",
        "content": {
          "key": "value"
        },
        "platform_parameters": {
          "android_header": "string",
          "android_root_params": {
            "key": "value"
          },
          "ios_title": "string",
          "ios_subtitle": "string",
          "ios_root_params": {
            "key": "value"
          },
          "chrome_header": "string",
          "chrome_root_params": {
            "key": "value"
          },
          "firefox_header": "string",
          "firefox_root_params": {
            "key": "value"
          },
          "conditions": [               // tag conditions (see /developer/api-reference/messages-api/#tag-conditions)
            TAG_CONDITION1,
            TAG_CONDITION2,
            ...,
            TAG_CONDITIONN
          ],
          "conditions_operator": "AND", // logical operator for conditions arrays; possible values: AND, OR
          "data": {
            "key": "value"
          }
        },
        "follow_user_timezone": true
      },
      "metrics": [{
        "sends": 0,
        "opens": 0,
        "deliveries": 0,
        "inbox_opens": 0,
        "unshowable_sends": 0,
        "errors": 0,
        "platform": 0
      }]
    },
    "email_info": {
      "details": {
        "template": "string",
        "filter_name": "string",
        "filter_code": "string",
        "subject": {
          "key": "value"
        },
        "from_name": "string",
        "from_email": "string",
        "reply_name": "string",
        "reply_email": "string",
        "follow_user_timezone": true,
        "conditions": [              // tag conditions (see Messages-api - tag-conditions)
          TAG_CONDITION1,
          TAG_CONDITION2,
          ...,
          TAG_CONDITIONN
        ],
        "conditions_operator": "AND" // logical operator for conditions arrays; possible values: AND, OR
      },
      "metrics": [{
        "sends": 0,
        "opens": 0,
        "deliveries": 0,
        "hard_bounces": 0,
        "soft_bounces": 0,
        "rejects": 0,
        "confirmed_sends": 0,
        "unsubs": 0,
        "complaints": 0,
        "errors": 0
      }]
    }
  }]
}

date_range يمتد لأكثر من 30 يومًا:

{
  "error": "exceeded the maximum date interval. Max interval: 30 days"
}

page × per_page يتجاوز حد الترقيم العميق:

{
  "error": "requested result window is too large, narrow the date range"
}

{
  "error": "account not found"
}

totalsByIntervals

يعيد المقاييس وبيانات التحويل بناءً على رمز الرسالة، مجمعة حسب الساعة.

POST https://api.pushwoosh.com/api/v2/statistics/messages/totalsByIntervals

التفويض

يتم التعامل مع التفويض عبر رمز الوصول إلى API في ترويسة الطلب.

معلمات نص الطلب

اسم المعلمة	النوع	الوصف	مطلوب
`message_code`	string	رمز الرسالة الذي تم الحصول عليه من استجابات واجهة برمجة التطبيقات `/createMessage`.	نعم
`platforms`	[int]	المنصات	لا

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

{
  "message_code": "XXXXX-XXXXXXXXX-XXXXXXXX", // required. Unique message identifier
  "platforms": [1, 3, 7, 10, 11, 12]          // optional. List of platform codes
}

حقول الاستجابة

الاسم	النوع	الوصف
`metrics`	array	يحتوي على مصفوفة من مقاييس الرسائل
`timestamp`	string	وقت المقياس.
`platform`	int	رمز المنصة (مثل iOS، Android).
`sends`	string	عدد الرسائل المرسلة.
`opens`	string	عدد الرسائل المفتوحة.
`deliveries`	string	عدد الرسائل المسلمة.
`inbox_opens`	string	عدد مرات فتح البريد الوارد.
`unshowable_sends`	string	عدد الرسائل المقبولة للأجهزة التي تم إيقاف تشغيل الإشعارات فيها في إعدادات نظام التشغيل. لا يتم عرض أي لافتة، ولكن الرسالة لا تزال تصل إلى التطبيق، وتظهر في صندوق الوارد للرسائل إذا كان الإرسال يحتوي على حفظ الرسالة في صندوق الوارد ممكّنًا. تُحتسب كإرسالات ناجحة، وليس كأخطاء.
`errors`	string	عدد الأخطاء.
`conversion`	object	يحتوي على بيانات التحويل
`sends`	string	إجمالي عدد الرسائل المرسلة.
`opens`	string	إجمالي عدد الرسائل المفتوحة.
`events`	array	مصفوفة من الأحداث مع إحصائياتها
`name`	string	اسم الحدث (على سبيل المثال، إضافة إلى السلة).
`hits`	string	عدد مرات الوصول.
`conversion`	float	معدل التحويل بالنسبة لعمليات الفتح.
`revenue`	float	الإيرادات (فقط للأحداث التي تحتوي على سمات `__amount` و `__currency`).

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

{
  "metrics": [{
    "timestamp": "2024-08-03 15:00:00",  // Timestamp of the metrics in "YYYY-MM-DD HH:MM:SS" format
    "platform": 3,                       // Platform code
    "sends": "55902",                    // Number of messages sent
    "opens": "382",                      // Number of messages opened
    "deliveries": "22931",               // Number of messages delivered
    "inbox_opens": "0",                  // Number of messages opened in the inbox
    "unshowable_sends": "2",             // Sent to devices with notifications turned off, no banner shown
    "errors": "0"                        // Number of errors encountered
  }],
  "conversion": {
    "sends": "55902",                    // Total number of messages sent
    "opens": "772",                      // Total number of messages opened
    "events": [{
      "name": "cart_add",                // Name of the event
      "hits": "96",                      // Number of hits for the event
      "conversion": 0.12,                // Conversion rate relative to opens
      "revenue": 0                       // Revenue generated by the event (only for events with amount/currency attributes)
    }]
  }
}

قمع التسليم

استخدم قمع التسليم لمعرفة في أي مرحلة فقدت الرسالة أو الحملة جمهورها (أخطاء، عدم تسليم، عدم فتح) ولماذا. على عكس totalsByIntervals، الذي يُرجع الإجماليات بالساعة، يقسّم القمع الجمهور حسب المرحلة وسبب الخروج، بسجل واحد لكل قناة، مع تفصيل حسب المنصة. يختلف تسلسل المراحل حسب القناة: راجع stage ضمن حقول GetDeliveryFunnelResponse أدناه لمعرفة المراحل التي تحملها كل قناة. تتطلب كلتا الطريقتين رمز API للخادم.

تُرجع كلتا الطريقتين نفس شكل الاستجابة، GetDeliveryFunnelResponse، الموصوف مرة واحدة أدناه.

getDeliveryFunnel

يُرجع قمع رسالة واحدة.

POST https://api.pushwoosh.com/api/v2/statistics/messages/getDeliveryFunnel

الرؤوس

الاسم	مطلوب	الوصف
`Authorization`	نعم	رمز API للخادم. يجب توفيره بالتنسيق التالي: `Authorization: Api <Server Key>`.

معاملات نص الطلب

الاسم	مطلوب	النوع	الوصف
`message_code`	نعم	نص	رمز الرسالة الذي تم الحصول عليه من استجابات API `/createMessage`.
`platforms`	لا	مصفوفة أعداد صحيحة	رموز المنصات لتصفية القمع. احذفه لإرجاع جميع المنصات التي أُرسلت إليها الرسالة.

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

{
  "message_code": "A444-AAABBBCC-00112233",  // رمز الرسالة من /createMessage
  "platforms": [1, 14]                        // اختياري. iOS، Email
}

حقول GetDeliveryFunnelResponse

الاسم	النوع	الوصف
`channels`	مصفوفة	سجل واحد لكل قناة أُرسلت إليها الرسالة.
`window_from`، `window_to`	نص أو null	الفترة التي يغطيها القمع، بناءً على البيانات المتاحة. تكون `null` عندما لا تكون `funnel_state` مساوية لـ `FUNNEL_STATE_READY`.
`funnel_state`	نص	`FUNNEL_STATE_READY`: القمع أدناه مُعبَّأ. `FUNNEL_STATE_NO_EVENTS`: لم يحدث شيء بعد لهذه الرسالة. `FUNNEL_STATE_EXPIRED`: أُرسلت الرسالة منذ زمن طويل جدًا. لم تعد بيانات القمع الخاصة بها متاحة. تكون `channels` فارغة في كلتا الحالتين غير `READY`. `message_code` غير معروف أو ينتمي لحساب آخر أو محذوف ليس واحدًا من هذه الحالات، انظر استجابة `404` أدناه.

channels[]

الاسم	النوع	الوصف
`channel`	نص	`CHANNEL_MOBILE_PUSH` (iOS، macOS، Android، Amazon، Huawei)، `CHANNEL_WEB_PUSH` (Safari، Chrome، Firefox)، `CHANNEL_EMAIL`، `CHANNEL_OTHER` (SMS، تطبيقات المراسلة، Wallet، Windows، Baidu، Xiaomi)، `CHANNEL_APP_INBOX`.
`funnel`	مصفوفة	مراحل القمع لهذه القناة، انظر `funnel[]` أدناه.
`deliveries_form`	نص	التفصيل الذي تحمله مرحلة `STAGE_DELIVERIES`: `DELIVERIES_FORM_PER_DEVICE` (أربعة صفوف منفصلة، مقسّمة حسب ما إذا كان الجهاز سيعرض تنبيهًا وما إذا كان قد أكّد) أو `DELIVERIES_FORM_BASIC` (صفان، دون تقسيم حسب حالة التنبيه).
`basic_form_reason`	نص	له معنى فقط عندما تكون `deliveries_form` مساوية لـ `DELIVERIES_FORM_BASIC`: `BASIC_FORM_REASON_RETENTION` (الرسالة قديمة جدًا بحيث لا يمكن تفصيلها حسب الجهاز)، `BASIC_FORM_REASON_UNAVAILABLE` (التفصيل حسب الجهاز غير متاح لهذا الحساب أو هذه الرسالة، مثل رسالة نظام)، `BASIC_FORM_REASON_NO_DELIVERIES` (لم يُقبَل شيء بعد)، `BASIC_FORM_REASON_NOT_APPLICABLE` (لا تملك القناة أي حالة تنبيه على الإطلاق، مثل البريد الإلكتروني أو App Inbox). وإلا فهي `BASIC_FORM_REASON_UNSPECIFIED`: تجاهل هذا الحقل ما لم تكن `deliveries_form` مساوية لـ `DELIVERIES_FORM_BASIC`.
`confirmed_deliveries`	كائن	`count` وتفصيل حسب `platforms` للتسليمات المؤكدة. غير مقيّد بحد عدد `STAGE_DELIVERIES`، لذا قد يختلف عنه.

funnel[] (مرحلة واحدة)

الاسم	النوع	الوصف
`stage`	نص	`STAGE_AUDIENCE` (كل من استهدفتهم الرسالة)، `STAGE_SENT` (تم قبولها من خدمة الدفع أو مزود البريد الإلكتروني)، `STAGE_ERRORS` (رُفضت قبل قبولها)، `STAGE_DELIVERIES` (مقبولة، مقسّمة حسب التأكيد)، `STAGE_OPENED` (الأجهزة الفريدة التي فتحت، أو بالنسبة لـ App Inbox العناصر التي نقر المستخدم لفتحها)، `STAGE_INTERACTIONS` (البريد الإلكتروني فقط: نقر، إلغاء اشتراك، شكوى)، `STAGE_REACHED`/`STAGE_READ` (App Inbox فقط، تحل محل `STAGE_DELIVERIES`).
`count`	نص	إجمالي المرحلة، كسلسلة رقمية.
`pieces`	مصفوفة	التفصيل الخاص بالمرحلة. فارغ في `STAGE_ERRORS`، الذي يستخدم `errors` بدلاً منه. يحتوي كل عنصر على `kind` (`KIND_PASSED` انتقل إلى المرحلة التالية، `KIND_REASON` لم ينتقل، `KIND_SUBSET` يتداخل مع الآخرين ولا يُجمع أبدًا)، و`category` (انظر قائمة القيم أدناه لكل مرحلة)، و`count`، وتفصيل حسب `platforms`.
`errors`	مصفوفة	لـ `STAGE_ERRORS` فقط: `category` (انظر قائمة القيم أدناه)، و`count`، و`platforms`، و`codes`: رموز أخطاء المزود الخام المجمّعة في هذه الفئة (`platform`، `code`، `name`، `count`). لمعرفة معنى كل `name` وكيفية إصلاحه، راجع أخطاء الإرسال.
`platforms`	مصفوفة	إجمالي المرحلة، مقسّمًا حسب المنصة.

قيم category

STAGE_AUDIENCE:

ELIGIBLE_AUDIENCE (اجتاز): غير مستبعد بأي من الأسباب أدناه.
FREQUENCY_CAPPING: تم تخطيه بسبب تحديد التكرار.
CONTROL_GROUP: تم استبقاؤه كمجموعة تحكم.
UNSUBSCRIBED: كان المستلم قد ألغى الاشتراك.
BOUNCED: كان عنوان المستلم قد ارتد سابقًا.
COMPLAINT: كان المستلم قد وضع علامة على رسالة كسبام سابقًا.
FILTERED_BY_CATEGORY: كان المستلم قد رفض هذه الفئة من الرسائل.

STAGE_ERRORS:

NO_TOKEN: لم يكن لدى الجهاز رمز دفع أو عنوان للإرسال إليه.
NO_DEVICE: لم يُعثر على جهاز مطابق.
PLATFORM_DISABLED: المنصة معطّلة لهذا التطبيق.
INVALID_TOKEN: رفض المزود رمز الجهاز أو العنوان باعتباره غير صالح.
QUOTA_EXCEEDED: قيّد المزود معدل الإرسال.
INVALID_CONTENT: تعذّر إرسال الرسالة كما تم تركيبها. غالبًا ما يفشل القالب نفسه في البناء، مثل كتلة Connected Content أو Liquid معطوبة، وليس رفض المزود لها.
INVALID_CONFIGURATION: إعداد المزود الخاص بالحساب معطوب، مثل بيانات اعتماد خاطئة، أو مشروع Firebase محذوف، أو topic غير مسموح به في APNs.
PROVIDER_ERROR: أعاد المزود خطأً خارج الفئات أعلاه.
INTERNAL_ERROR: فشل Pushwoosh في معالجة الإرسال.
UNCLASSIFIED_ERROR: خروج لا يطابق أيًا من الفئات أعلاه. من المتوقع أن يكون نادرًا.

STAGE_DELIVERIES، DELIVERIES_FORM_PER_DEVICE:

DISPLAYABLE_CONFIRMED (اجتاز): عرض الجهاز تنبيهًا وأكّد الاستلام.
DISPLAYABLE_NO_CONFIRMATION: كان الجهاز سيعرض تنبيهًا لكنه لم يؤكد الاستلام بعد.
NOT_DISPLAYABLE_CONFIRMED (اجتاز): أكّد push صامت الاستلام.
NOT_DISPLAYABLE_NO_CONFIRMATION: لم يؤكد push صامت الاستلام بعد.

STAGE_DELIVERIES، DELIVERIES_FORM_BASIC:

CONFIRMED_BY_DEVICE (اجتاز): أكّد الجهاز الاستلام.
NO_CONFIRMATION: لم يُؤكَّد بعد.

يضيف البريد الإلكتروني أيضًا، كمجموعة جزئية تتداخل مع CONFIRMED_BY_DEVICE:

BOUNCED_HARD (مجموعة جزئية): العنوان غير قابل للتسليم بشكل دائم.
BOUNCED_SOFT (مجموعة جزئية): العنوان غير قابل للتسليم مؤقتًا، مثل صندوق بريد ممتلئ.

يمكن أن ينقسم BOUNCED_HARD أيضًا إلى صفوف المجموعة الجزئية التالية:

BOUNCED_HARD_GENERAL: غير قابل للتسليم بشكل دائم، لا يوجد سبب أكثر تحديدًا متاح.
BOUNCED_HARD_MAILBOX_FULL: صندوق بريد المستلم ممتلئ.
BOUNCED_HARD_MAILBOX_INACTIVE: صندوق بريد المستلم لم يعد موجودًا.
BOUNCED_HARD_SUPPRESSED: أدرج المزود العنوان في القائمة السوداء.
BOUNCED_HARD_UNDETERMINED: غير قابل للتسليم بشكل دائم، السبب غير محدد.

يمكن أن ينقسم BOUNCED_SOFT أيضًا إلى صفوف المجموعة الجزئية التالية:

BOUNCED_SOFT_GENERAL: غير قابل للتسليم مؤقتًا، لا يوجد سبب أكثر تحديدًا متاح.
BOUNCED_SOFT_MAILBOX_FULL: كان صندوق بريد المستلم ممتلئًا وقت الإرسال.
BOUNCED_SOFT_CONTENT_REJECTED: رفض خادم بريد المستلم محتوى الرسالة.
BOUNCED_SOFT_SPAM: وضع خادم بريد المستلم علامة على الرسالة كسبام.
BOUNCED_SOFT_MESSAGE_TOO_LARGE: كانت الرسالة كبيرة جدًا بالنسبة لصندوق بريد المستلم.
BOUNCED_SOFT_ATTACHMENT_REJECTED: رفض خادم بريد المستلم مرفقًا.
BOUNCED_SOFT_CUSTOM_TIMEOUT_EXCEEDED: استغرق خادم بريد المستلم وقتًا طويلاً جدًا للرد.
BOUNCED_SOFT_UNDETERMINED: غير قابل للتسليم مؤقتًا، السبب غير محدد.
BOUNCED_UNDETERMINED: قبل خادم المستلم البريد الإلكتروني لكنه لم يؤكد التسليم مطلقًا؛ النتيجة غير معروفة والعنوان غير مدرج في قائمة القمع. يُحتسب كارتداد ناعم.

BOUNCED_UNCLASSIFIED هو ارتداد، صلب أو ناعم، لا يطابق أيًا من الأنواع الفرعية أعلاه. من المتوقع أن يكون نادرًا، وليس قيمة يُبنى عليها منطق.

STAGE_OPENED، البريد الإلكتروني فقط (تُبلّغ القنوات الأخرى عن count المرحلة بدون عناصر):

OPENED_BY_RECIPIENT (اجتاز): فتحه شخص.
MACHINE_OPENS_ONLY: فتحه ماسح آلي فقط.
OPEN_TYPE_UNKNOWN: تعذّر تصنيفه كشخص أو ماسح آلي.
MACHINE_OPENS_AMPP (مجموعة جزئية): يحل محل الصفوف الثلاثة أعلاه عندما لا يتوفر تقسيم شخص/ماسح لهذه الرسالة. يحتسب بدلاً من ذلك عدد الفتحات الآلية الخاص بـ Apple Mail Privacy Protection، ويتداخل مع إجمالي المرحلة.

STAGE_INTERACTIONS، البريد الإلكتروني فقط:

CLICKED_ONLY (اجتاز): نقر على رابط، وبقي مشتركًا.
CLICKED_AND_UNSUBSCRIBED: نقر على رابط وألغى الاشتراك.
CLICKED_AND_COMPLAINED: نقر على رابط ووضع علامة على الرسالة كسبام.
UNSUBSCRIBED_WITHOUT_CLICK: ألغى الاشتراك دون نقر.
COMPLAINED_WITHOUT_CLICK: وضع علامة على الرسالة كسبام دون نقر.

STAGE_REACHED، App Inbox فقط:

REACHED (اجتاز): تم جلب العنصر بواسطة التطبيق مرة واحدة على الأقل.
NOT_FETCHED_YET: لم يُجلب بعد.

STAGE_READ، App Inbox فقط:

READ (اجتاز): تم وضع علامة عليه كمقروء.
DISMISSED_UNREAD: حذفه المستخدم دون قراءته.
UNREAD: لا يزال غير مقروء في صندوق الوارد.
EXPIRED_UNREAD: نفس UNREAD، لكن العنصر انتهت صلاحيته منذ ذلك الحين وخرج من صندوق الوارد.
DISMISSED (مجموعة جزئية): كل عنصر محذوف، سواء قُرئ أم لا. يتداخل مع READ وDISMISSED_UNREAD.

رموز الاستجابة

{
  "channels": [{
    "channel": "CHANNEL_MOBILE_PUSH",
    "funnel": [
      { "stage": "STAGE_AUDIENCE", "count": "10000", "pieces": [
        { "kind": "KIND_PASSED", "category": "ELIGIBLE_AUDIENCE", "count": "10000", "platforms": [{ "platform": 1, "count": "10000" }] }
      ], "errors": [], "platforms": [{ "platform": 1, "count": "10000" }] },
      { "stage": "STAGE_SENT", "count": "9820", "pieces": [], "errors": [], "platforms": [{ "platform": 1, "count": "9820" }] },
      { "stage": "STAGE_ERRORS", "count": "180", "pieces": [], "errors": [
        { "category": "INVALID_TOKEN", "count": "180", "platforms": [{ "platform": 1, "count": "180" }], "codes": [
          { "platform": 1, "code": 1002, "name": "BadDeviceToken", "count": "180" }
        ] }
      ], "platforms": [{ "platform": 1, "count": "180" }] },
      { "stage": "STAGE_DELIVERIES", "count": "9820", "pieces": [
        { "kind": "KIND_PASSED", "category": "DISPLAYABLE_CONFIRMED", "count": "8000", "platforms": [{ "platform": 1, "count": "8000" }] },
        { "kind": "KIND_REASON", "category": "DISPLAYABLE_NO_CONFIRMATION", "count": "820", "platforms": [{ "platform": 1, "count": "820" }] },
        { "kind": "KIND_PASSED", "category": "NOT_DISPLAYABLE_CONFIRMED", "count": "900", "platforms": [{ "platform": 1, "count": "900" }] },
        { "kind": "KIND_REASON", "category": "NOT_DISPLAYABLE_NO_CONFIRMATION", "count": "100", "platforms": [{ "platform": 1, "count": "100" }] }
      ], "errors": [], "platforms": [{ "platform": 1, "count": "9820" }] },
      { "stage": "STAGE_OPENED", "count": "3120", "pieces": [], "errors": [], "platforms": [{ "platform": 1, "count": "3120" }] }
    ],
    "deliveries_form": "DELIVERIES_FORM_PER_DEVICE",
    "basic_form_reason": "BASIC_FORM_REASON_UNSPECIFIED",
    "confirmed_deliveries": { "count": "8900", "platforms": [{ "platform": 1, "count": "8900" }] }
  }],
  "window_from": "2026-09-01T00:00:00Z",
  "window_to": "2026-09-01T00:05:00Z",
  "funnel_state": "FUNNEL_STATE_READY"
}

مصفوفة channels فارغة مع funnel_state: "FUNNEL_STATE_NO_EVENTS" تعني أنه لم يحدث شيء بعد لهذه الرسالة. هذا ليس خطأً. message_code أُرسل منذ زمن طويل جدًا بحيث لم تعد بيانات القمع متاحة يُرجع أيضًا 200، مع مصفوفة channels فارغة وfunnel_state: "FUNNEL_STATE_EXPIRED".

message_code غير معروف، ينتمي لحساب آخر، أو تم حذفه منذ ذلك الحين:

{
  "error": "message not found"
}

{
  "error": "invalid auth token"
}

getCampaignDeliveryFunnel

يجمع getDeliveryFunnel عبر رسائل حملة ما. تُحسب الأعداد الفريدة لكل رسالة على حدة: يُحتسب المشترك الذي وصلته عدة رسائل في الحملة مرة واحدة لكل رسالة.

POST https://api.pushwoosh.com/api/v2/statistics/messages/getCampaignDeliveryFunnel

الرؤوس

الاسم	مطلوب	الوصف
`Authorization`	نعم	رمز API للخادم. يجب توفيره بالتنسيق التالي: `Authorization: Api <Server Key>`.

معاملات نص الطلب

الاسم	مطلوب	النوع	الوصف
`campaign_code`	نعم	نص	رمز الحملة.
`platforms`	لا	مصفوفة أعداد صحيحة	رموز المنصات لتصفية القمع. احذفه لإرجاع جميع المنصات التي أُرسلت إليها الحملة.

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

{
  "campaign_code": "AAAAA-XXXXX",  // رمز الحملة
  "platforms": [1, 14]             // اختياري. iOS، Email
}

الاستجابة

نفس شكل GetDeliveryFunnelResponse أعلاه.

رموز الاستجابة

جمهور فارغ لـ campaign_code وplatforms المحددين يُرجع أيضًا 200 مع مصفوفة channels فارغة وfunnel_state: "FUNNEL_STATE_NO_EVENTS". حملة أُرسلت منذ زمن طويل جدًا بحيث لم تعد بيانات القمع متاحة تُرجع أيضًا 200، مع مصفوفة channels فارغة وfunnel_state: "FUNNEL_STATE_EXPIRED". لا يُعد أي منهما خطأً.

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

{
  "error": "campaign not found"
}

{
  "error": "invalid auth token"
}

getMessageLog

يعرض معلومات مفصلة حول الرسائل المرسلة.

POST https://api.pushwoosh.com/api/v2/statistics/getMessageLog

ترويسات

الاسم	مطلوب	الوصف
`Authorization`	مطلوب	رمز الوصول إلى API من لوحة تحكم Pushwoosh.

معلمات نص الطلب

الاسم	مطلوب	النوع	الوصف
`message_id`	لا	Integer	حدد أحداث الرسائل حسب معرف الرسالة الذي تم الحصول عليه من سجل الرسائل. مثال: `12345678900`.
`message_code`	لا	String	حدد أحداث الرسائل حسب رمز الرسالة الذي تم الحصول عليه من استجابات واجهة برمجة التطبيقات `/createMessage`. مثال: `"A444-AAABBBCC-00112233"`.
`campaign_code`	لا	String	حدد أحداث الرسائل حسب رمز الحملة المحدد في حمولة رسالتك. مثال: `"AAAAA-XXXXX"`.
`hwid`	لا	String or Array	حدد أحداث الرسائل حسب HWID (معرف الجهاز) أو مصفوفة من HWIDs.
`date_from`	مطلوب إذا لم يتم توفير `message_id` أو `message_code` أو `campaign_code`	Datetime	تاريخ البدء لتصفية الرسائل. التنسيق: `"YYYY-MM-DD HH:MM:SS"`. مثال: `"2000-01-25 00:00:00"`.
`date_to`	مطلوب إذا لم يتم توفير `message_id` أو `message_code` أو `campaign_code`	Datetime	تاريخ الانتهاء لتصفية الرسائل. التنسيق: `"YYYY-MM-DD HH:MM:SS"`. مثال: `"2000-01-26 00:00:00"`.
`limit`	لا	Integer	الحد الأقصى لعدد أحداث الرسائل التي يتم إرجاعها في استجابة واحدة. القيمة القصوى: `100000`.
`pagination_token`	لا	String	رمز الترقيم الذي تم الحصول عليه من استجابة `/getMessageLog` سابقة. استخدمه لاسترداد نتائج إضافية.
`user_id`	لا	String	حدد أحداث الرسائل حسب معرف المستخدم المخصص. انظر `/registerUser` لمزيد من التفاصيل.
`application_code`	نعم	String	حدد أحداث الرسائل حسب رمز تطبيق Pushwoosh
`actions`	لا	Array	تصفية النتائج حسب إجراءات رسائل محددة. القيم الممكنة: `"sent"`, `"delivered"`, `"opened"`, `"reject"`, `"create"`, `"inbox_delivered"`, `"inbox_read"`, `"inbox_opened"`, `"inbox_deleted"`. يتم استبعاد أحداث `"create"` من الاستجابة افتراضيًا. قم بتضمين `"create"` في هذه المصفوفة لرؤيتها. تتطلب أحداث `"delivered"` بالإضافة إلى ذلك تمكين إحصائيات التسليم على الحساب.
`platforms`	لا	Array	مصفوفة من المنصات المستهدفة لتصفية النتائج. القيم الممكنة: `"unknown"`, `"ios"`, `"blackberry"`, `"android"`, `"windows phone"`, `"osx"`, `"windows"`, `"amazon"`, `"safari"`, `"chrome"`, `"firefox"`, `"ie"`, `"email"`, `"fb messenger"`, `"baidu android"`, `"huawei android"`, `"sms"`, `"xiaomi"`, `"web"`, `"whatsapp"`, `"line"`, `"kakao"`, `"telegram"`, `"apple wallet"`, `"google wallet"`, `"viber"`.
`message_type`	لا	String	تصفية النتائج حسب تدفق الرسائل. `"all"` (الافتراضي إذا تم حذفه) يعيد كل شيء، `"broadcast"` يعيد فقط الرسائل الجماعية (`message_id != 0`)، `"transactional"` يعيد فقط الرسائل التي تحتوي على `message_id = 0`، بما في ذلك تلك المرسلة من Customer Journey.

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

curl --location --request POST 'https://api.pushwoosh.com/api/v2/statistics/getMessageLog' \
--header 'Authorization: Key API_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
   "pagination_token": "PAGINATION_TOKEN_FROM_PREVIOUS_RESPONSE",  // optional, token for pagination
   "limit": 1000,                                  // optional, the max number of entries for a single response
   "application_code": "XXXXX-XXXXX",              // Pushwoosh app code
   "message_code": "A444-AAABBBCC-00112233",       // optional, message code obtained from /createMessaage request
   "message_id": 1234567890,                       // optional, message ID obtained from Pushwoosh Control Panel
   "campaign_code": "AAAAA-XXXXX",                 // optional, code of a campaign to get the log for
   "hwid": "aaazzzqqqqxxx",                        // optional, hardware ID of a specific device targeted with a message
   "user_id": "user_123",                          // optional, ID of a user targeted with the message
   "date_from": "2000-01-25 00:00:00",             // optional, start of the stats period
   "date_to": "2000-02-10 23:59:59",               // optional, end of the stats period
   "actions": ["opened", "inbox_opened"],          // optional, used for results filtration. Possible values: "sent", "delivered", "opened", "reject", "create", "inbox_delivered", "inbox_read", "inbox_opened", "inbox_deleted". The response will include all the messages with the specified action(s).
   "platforms": ["ios", "chrome"],                 // optional, used for results filtration, lowercase only. Possible values: "unknown", "ios", "blackberry", "android", "windows phone", "osx", "windows", "amazon", "safari", "chrome", "firefox", "ie", "email", "fb messenger", "baidu android", "huawei android", "sms", "xiaomi", "web", "whatsapp", "line", "kakao", "telegram", "apple wallet", "google wallet", "viber"
   "message_type": "broadcast"                     // optional, "all" (default), "broadcast" (message_id != 0), or "transactional" (message_id = 0, includes Customer Journey sends)
}'

رموز الاستجابة والأمثلة

{
  "pagination_token": "PAGINATION_TOKEN_FOR_NEXT_REQUEST",
  "data": [{
    "timestamp": "2000-01-25T11:18:47Z",
    "application_code": "XXXXX-XXXXX",
    "message_id": 12345678900,
    "message_code": "A444-AAABBBCC-00112233",
    "campaign_code": "AAAAA-XXXXX",
    "hwid": "aaazzzqqqqxxx",
    "user_id": "user_123",
    "platform": "android",
    "action": "sent",
    "status": "success",
    "push_alerts_enabled": "true"
  }, {
    "timestamp": "2000-01-25T11:18:49Z",
    "application_code": "XXXXX-XXXXX",
    "message_id": 12345678900,
    "message_code": "A444-AAABBBCC-00112233",
    "campaign_code": "AAAAA-XXXXX",
    "hwid": "aaazzzqqqqxxx",
    "user_id": "user_123",
    "platform": "android",
    "action": "delivered",
    "push_alerts_enabled": "true"
  }, {
    "timestamp": "2000-01-25T11:19:23Z",
    "application_code": "XXXXX-XXXXX",
    "message_id": 12345678900,
    "message_code": "A444-AAABBBCC-00112233",
    "campaign_code": "AAAAA-XXXXX",
    "hwid": "aaazzzqqqqxxx",
    "user_id": "user_123",
    "platform": "android",
    "action": "opened",
    "push_alerts_enabled": "true"
  }, {
    "timestamp": "2000-01-25T11:19:30Z",
    "application_code": "XXXXX-XXXXX",
    "message_id": 12345678900,
    "message_code": "A444-AAABBBCC-00112233",
    "campaign_code": "AAAAA-XXXXX",
    "hwid": "aaazzzqqqqxxx",
    "user_id": "user_123",
    "platform": "android",
    "action": "reject",
    "status": "failed",
    "error_reason": "invalid device token",
    "payload": "SOME_PAYLOAD_STRING"
  }]
}

{
  "error": "exceeded the maximum date interval. Max interval: 30 days"
}

{
  "error": "account not found"
}

يحمل كل إدخال في data أيضًا error_reason (سلسلة نصية، يتم ملؤها بسبب الفشل عندما تكون status هي "failed") و payload اختياري (سلسلة نصية).

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

إحصائيات البريد الإلكتروني

linksInteractions

يعرض إحصائيات حول نقرات الروابط في رسائل البريد الإلكتروني

POST https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractions

ترويسات

الاسم	مطلوب	الوصف
`Authorization`	نعم	رمز الوصول إلى API من لوحة تحكم Pushwoosh.

معلمات نص الطلب

الاسم	مطلوب	النوع	الوصف
`date_range`	لا	Object	يحدد فترة التقرير. يحتوي على `date_from` و `date_to`.
`filters`	نعم	Object	فلاتر البريد الإلكتروني.
`application`	نعم	String	رمز تطبيق Pushwoosh (بدلاً من ذلك، حدد `campaign` أو `messages_ids` أو `message_codes`).
`messages_codes`	نعم	Array	رموز الرسائل (بدلاً من ذلك، حدد `application` أو `campaign` أو `messages_ids`).
`campaign`	نعم	String	رمز الحملة (بدلاً من ذلك، حدد `application` أو `messages_ids` أو `message_codes`).
`messages_ids`	نعم	Array	معرفات الرسائل (بدلاً من ذلك، حدد `application` أو `campaign` أو `message_codes`).
`link_template`	مطلوب إذا تم تحديد `application` أو `campaign`.	String	يقوم بتصفية تفاعلات روابط البريد الإلكتروني حسب الكلمة الرئيسية. سيتم إرجاع الروابط التي تتضمن النص المحدد في عنوان URL الخاص بها فقط في استجابة API. على سبيل المثال، إذا كان بريدك الإلكتروني يحتوي على روابط مثل `https://example.com/news` و `https://example.com/shop`، فإن تعيين “link_template”: “shop” سيعيد التفاعلات لـ `https://example.com/shop` فقط.
`email_content_code`	لا	String	معرف فريد لمحتوى البريد الإلكتروني.
`params`	لا	Object	يحدد خيارات استجابة إضافية. يتضمن `with_full_links`، الذي يضيف قائمة بالروابط الكاملة مع الإحصائيات.

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

curl --location --request POST 'https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractions' \
--header 'Authorization: Api API_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
   "filters": {
      "date_range": {
         "date_from": "string",           // Required format: 2000-01-01
         "date_to": "string"              // Required format: 2000-01-01
      },
      "campaign": "string",               // Campaign code (you can specify application, messages_ids, or message_codes instead)
      "application": "string",            // Application code (you can specify campaign, messages_ids, or message_codes instead)
      "messages_ids": [],                 // Message IDs (you can specify application, campaign, or message_codes instead)
      "messages_codes": [],               // Message codes (you can specify application, campaign, or message_ids instead)
      "link_template": "string",          // Link template (required if application or campaign is specified)
      "email_content_code": "string"      // Unique identifier for the email content.
   },
   "params": {
      "with_full_links": true             // Specify whether to show detailed statistics. A list of full links with statistics will be passed in the full_links array.
   }
}'

رموز الاستجابة والأمثلة

{
  "items": [{
    "template": "string",
    "link": "string",
    "title": "string",
    "clicks": 0,
    "full_links": [{
      "full_link": "string",
      "clicks": 0
    }]
  }]
}

{
  "error": "exceeded the maximum date interval. Max interval: 30 days"
}

{
  "error": "account not found"
}

linksInteractionsDevices

يعرض المستخدمين الذين نقروا على الروابط في رسائل البريد الإلكتروني

POST https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractionsDevices

ترويسات

الاسم	مطلوب	الوصف
`Authorization`	نعم	رمز الوصول إلى API من لوحة تحكم Pushwoosh.

معلمات نص الطلب

الاسم	مطلوب	النوع	الوصف
`date_range`	لا	Object	يحدد فترة التقرير. يحتوي على `date_from` و `date_to`.
`filters`	نعم	Object	فلاتر البريد الإلكتروني.
`application`	نعم	String	رمز تطبيق Pushwoosh (بدلاً من ذلك، حدد `campaign` أو `messages_ids` أو `message_codes`).
`messages_codes`	نعم	Array	رموز الرسائل (بدلاً من ذلك، حدد `application` أو `campaign` أو `messages_ids`).
`campaign`	نعم	String	رمز الحملة (بدلاً من ذلك، حدد `application` أو `messages_ids` أو `message_codes`).
`messages_ids`	نعم	Array	معرفات الرسائل (بدلاً من ذلك، حدد `application` أو `campaign` أو `message_codes`).
`link_template`	مطلوب إذا تم تحديد `application` أو `campaign`.	String	يقوم بتصفية تفاعلات روابط البريد الإلكتروني حسب الكلمة الرئيسية. سيتم إرجاع الروابط التي تتضمن النص المحدد في عنوان URL الخاص بها فقط في استجابة API. على سبيل المثال، إذا كان بريدك الإلكتروني يحتوي على روابط مثل `https://example.com/news` و `https://example.com/shop`، فإن تعيين “link_template”: “shop” سيعيد التفاعلات لـ `https://example.com/shop` فقط.
`email_content_code`	لا	String	معرف فريد لمحتوى البريد الإلكتروني.
`page`	لا	Integer	رقم الصفحة للترقيم.
`per_page`	لا	Integer	عدد النتائج لكل صفحة (≤ 1000).

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

curl --location --request POST 'https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractionsDevices' \
--header 'Authorization: Api API_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
   "filters": {
      "date_range": {
         "date_from": "string",         // Required format: 2000-01-01
         "date_to": "string"            // Required format: 2000-01-01
      },
      "campaign": "string",             // Campaign code (you can specify application, messages_ids, or message_codes instead)
      "application": "string",          // Application code (you can specify campaign, messages_ids, or message_codes instead)
      "messages_ids": [],               // Message IDs (you can specify application, campaign, or message_codes instead)
      "messages_codes": [],             // Message codes (you can specify application, campaign, or message_ids instead)
      "link_template": "string",        // Link template (required if application or campaign is specified)
      "email_content_code": "string"    // Unique identifier for the email content.
   },
   "per_page": 100,
   "page": 0
}'

رموز الاستجابة والأمثلة

{
  "total": 0,
  "items": [{
    "timestamp": "string",
    "link": "string",
    "hwid": "string"
  }]
}

{
  "error": "exceeded the maximum date interval. Max interval: 30 days"
}

{
  "error": "account not found"
}

bouncedEmails

POST https://api.pushwoosh.com/api/v2/statistics/emails/bouncedEmails

يوفر بيانات حول شكاوى البريد الإلكتروني، والارتدادات الناعمة، والارتدادات الصلبة، بما في ذلك التاريخ وعنوان البريد الإلكتروني وسبب كل ارتداد.

التفويض

يتم التعامل مع التفويض عبر رمز الوصول إلى API في ترويسة الطلب.

معلمات نص الطلب

اسم المعلمة	النوع	الوصف	مطلوب
`application`	string	رمز تطبيق Pushwoosh	نعم
`message_code`	string	رمز الرسالة.	مطلوب إذا لم يتم توفير `date range` أو `campaign`
`campaign`	string	رمز الحملة.	مطلوب إذا لم يتم توفير `message_code` أو `date range`
`date_from`	string	تاريخ البدء للبيانات بالتنسيق `YYYY-MM-DDTHH:MM:SS.000Z` (معيار ISO 8601).	مطلوب إذا لم يتم توفير `message_code` أو `campaign`
`date_to`	string	تاريخ الانتهاء للبيانات بالتنسيق `YYYY-MM-DDTHH:MM:SS.000Z` (معيار ISO 8601).	مطلوب إذا لم يتم توفير `message_code` أو `campaign`
`per_page`	int	عدد الصفوف لكل صفحة، بحد أقصى 5000.	نعم
`page`	int	رقم الصفحة، بدءًا من الصفر.	نعم
`type`	string	نوع الارتداد: Complaint، Softbounce، Hardbounce.	لا

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

{
  "application": "XXXXX-XXXXX",               // required. Pushwoosh app code
  "message_code": "XXXXX-XXXXXXXXX-XXXXXXXX", // required if campaign or date range is not provided.
                                              //          Unique message identifier
  "campaign": "XXXXX-XXXXX",                  // required if message_code or date range is not provided.
                                              //          Campaign code
  "date_from": "2024-07-20T00:00:00.000Z",    // required if message_code or campaign is not provided.
                                              //          Start date in ISO 8601 format "YYYY-MM-DDTHH:MM:SS.SSSZ"
  "date_to": "2024-07-20T00:00:00.000Z",      // required if message_code or campaign is not provided.
                                              //          End date in ISO 8601 format "YYYY-MM-DDTHH:MM:SS.SSSZ"
  "per_page": 1000,                           // required. Number of results per page, maximum 5000
  "page": 5,                                  // optional. Page number, starting from zero
  "type": "Softbounce"                        // optional. The type of bounce: Complaint, Softbounce, Hardbounce
}

حقول الاستجابة

اسم الحقل	النوع	الوصف
`total`	int	العدد الإجمالي للصفوف.
`bounced_emails`	array	مصفوفة من تفاصيل البريد الإلكتروني المرتد.
├── `email`	string	عنوان البريد الإلكتروني الذي ارتد.
├── `date`	string	تاريخ الارتداد (التنسيق: `YYYY-MM-DDTHH:MM:SS.000Z`).
├── `reason`	string	سبب الارتداد.
└── `type`	string	نوع الارتداد: Complaint، Softbounce، Hardbounce.

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

{
  "total": 25,                             // Total count of rows.
  "bounced_emails": [{
    "email": "example@example.com",        // Email address that bounced
    "date": "2024-07-20T00:00:00.000Z",    // Bounce date in ISO 8601 format
    "reason": "Invalid recipient address", // Reason for the bounce
    "type": "Hardbounce"                   // Type of bounce: Complaint, Softbounce, Hardbounce
  }]
}