إشعار مجمع

POST https://api.pushwoosh.com/messaging/v2/notify/batch

يرسل عدة رسائل في استدعاء واحد. كل عنصر هو إشعار مستقل: يتم التحقق من صحته تمامًا مثل طلب Notify مستقل، ويحصل على نتيجته الخاصة.

اقرأ النتائج، وليس رمز الحالة

الاستدعاء نفسه يُرجع HTTP 200 طالما أن غلاف الدفعة صالح — حتى لو فشل كل عنصر على حدة. العنصر الفاشل لا يؤدي أبدًا إلى فشل الطلب بأكمله. تحقق دائمًا من results[] وعدادات succeeded / failed؛ لا تتعامل مع استجابة 200 على أنها تأكيد لإرسال الرسائل.

هذه ليست طريقة أسرع للإرسال

لا يرسل NotifyBatch الرسائل بشكل أسرع من استدعاء Notify مباشرة. إذا كان تكاملك يمكنه بالفعل إصدار طلبات بشكل متزامن، فإن تشغيل Notify في مسارات/عمال متوازية يعطي نفس الإنتاجية — يعالج HTTP/2 ذلك حسب التصميم. استخدم NotifyBatch للراحة عندما لا يكون تكاملك مبنيًا للتزامن، وليس للسرعة.

هيكل الطلب

Shape

{
  "items": [
    {
      "item_id": "caller-defined-id",
      "request": { ... }
    }
  ]
}

الحقل	النوع	الوصف
items	array of NotifyBatchItem	مطلوب، من 1 إلى 500 إدخال (حد يكوّنه الخادم). تتم معالجة العناصر بشكل متزامن؛ تعود النتائج بترتيب الطلب بغض النظر عن ذلك.

NotifyBatchItem

الحقل	النوع	الوصف
item_id	string	معرف ارتباط اختياري يوفره المستدعي، يتم إرجاعه في النتيجة المطابقة. لا يستخدمه Pushwoosh بخلاف ذلك.
request	NotifyRequest	نفس الجسم لاستدعاء Notify واحد — يتضمن segment أو transactional و transaction_id. مطلوب.

لا يزال حقل schedule مطلوبًا لكل عنصر

يحتاج request الخاص بكل عنصر إلى schedule خاص به، تمامًا مثل استدعاء Notify مستقل. حذفه لا يؤدي إلى “الإرسال الآن” — يفشل العنصر بخطأ EmptySchedule.

إعادة محاولة إرسال دفعة آمنة

قم بتعيين transaction_id على request الخاص بكل عنصر. الاستدعاء المتكرر بنفس transaction_id يُرجع نفس message_code لذلك العنصر خلال نافذة إزالة التكرار البالغة 5 دقائق الموضحة في صفحة Notify — لذا فإن إعادة محاولة إرسال الدفعة بأكملها بعد خطأ في الشبكة لا يؤدي إلى تكرار الرسائل التي تم إرسالها بالفعل.

مثال

curl -X POST https://api.pushwoosh.com/messaging/v2/notify/batch \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "item_id": "order-1001",
        "request": {
          "transactional": {
            "application": "XXXXX-XXXXX",
            "platforms": ["IOS", "ANDROID"],
            "users": { "list": ["user-123"] },
            "payload": {
              "content": {
                "localized_content": {
                  "en": { "ios": { "body": "Your order has shipped." } }
                }
              }
            },
            "schedule": { "at": "2026-05-01T12:00:00Z" },
            "message_type": "MESSAGE_TYPE_TRANSACTIONAL",
            "transaction_id": "order-1001-shipped"
          }
        }
      },
      {
        "item_id": "order-1002",
        "request": {
          "transactional": {
            "application": "XXXXX-XXXXX",
            "platforms": ["IOS", "ANDROID"],
            "users": { "list": ["user-456"] },
            "payload": {
              "content": {
                "localized_content": {
                  "en": { "ios": { "body": "Your order has shipped." } }
                }
              }
            },
            "schedule": { "at": "2026-05-01T12:00:00Z" },
            "message_type": "MESSAGE_TYPE_TRANSACTIONAL",
            "transaction_id": "order-1002-shipped"
          }
        }
      }
    ]
  }'

الاستجابة

{
  "results": [
    {
      "item_id": "order-1001",
      "index": 0,
      "result": {
        "message_code": "XXXXX-XXXXX-XXXXX",
        "unknown_identifiers": []
      }
    },
    {
      "item_id": "order-1002",
      "index": 1,
      "error": {
        "code": 3,
        "message": "invalid argument",
        "reason": "EmptySchedule",
        "domain": "api.pushwoosh.com"
      }
    }
  ],
  "succeeded": 1,
  "failed": 1
}

الحقل	النوع	الوصف
results	array of NotifyBatchResult	إدخال واحد لكل عنصر مطلوب، بترتيب الطلب.
succeeded	integer	عدد العناصر التي أعادت نتيجة.
failed	integer	عدد العناصر التي أعادت خطأ.

NotifyBatchResult

الحقل	النوع	الوصف
item_id	string	صدى لـ item_id الخاص بعنصر الطلب.
index	integer	موضع العنصر في الطلب يبدأ من الصفر. استخدم هذا لربط النتائج عندما يُترك item_id فارغًا.
result	object	يتم تعيينه عند نجاح العنصر — نفس شكل استجابة Notify واحدة: message_code و unknown_identifiers.
error	NotifyBatchError	يتم تعيينه عند فشل العنصر.

NotifyBatchError

الحقل	النوع	الوصف
code	integer	رمز حالة gRPC (google.rpc.Code)، على سبيل المثال 3 لـ INVALID_ARGUMENT.
message	string	رسالة خطأ موجهة للمطور، باللغة الإنجليزية.
reason	string	اسم حالة قصير — نفس القيمة التي سيعيدها استدعاء Notify واحد، على سبيل المثال EmptySchedule.
domain	string	نطاق الخطأ، api.pushwoosh.com.

الأخطاء

تستخدم الأخطاء غلاف الخطأ القياسي لـ gRPC-Gateway: { "code": ..., "message": ..., "details": [...] }. هذه أخطاء على مستوى الغلاف تؤدي إلى فشل الطلب بأكمله — فشل عنصر فردي ينتج خطأ error لكل عنصر في results[] بدلاً من ذلك (انظر NotifyBatchError أعلاه)، وليس أحد هذه الأخطاء.

حالة HTTP	الشرط
400	items فارغ.
400	items يحتوي على أكثر من الحد الذي يكوّنه الخادم (500 افتراضيًا).
400	أحد العناصر يفتقد request.

مثال

إرسال 501 عنصرًا عندما يكون الحد 500 يُرجع HTTP 400:

{
  "code": 3,
  "message": "items must not exceed 500 entries, got 501",
  "details": []
}

مواضيع ذات صلة

إشعار

إلغاء

مرجع الحمولة

نظرة عامة على Messaging API v2

الترحيل من v1