إشعار (Notify)

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

ينشئ ويجدول رسالة واحدة.

بنية الطلب

نص الطلب هو NotifyRequest بنوع واحد فقط من نوعين:

segment: استهداف شريحة جمهور برمز الشريحة، أو — دون إنشاء شريحة أولاً — تعبير seglang أو تعبير مرشح منظم.
transactional: إرسال إلى قائمة صريحة من hwids، معرفات المستخدمين (user IDs)، رموز الإشعارات الفورية (push tokens)، أو الأجهزة الاختبارية.

{
  "segment": { ... },      // أو
  "transactional": { ... },
  "transaction_id": "unique-uuid"
}

الحقل	النوع	الوصف
`transaction_id`	string	اختياري. مفتاح عدم التكرار للطلب — يعمل مع كل من `segment` و `transactional`. إعادة الاتصال بنفس `transaction_id` خلال 5 دقائق تُرجع `message_code` الأصلي بدلاً من إرسال رسالة مكررة. استخدم UUID أو قيمة أخرى فريدة لكل عملية إرسال منطقية.

NotifySegment

يستهدف المستخدمين الذين يطابقون شريحة جمهور أو تعبير مرشح. قم بتعيين واحد فقط من code أو expression أو filter_expression. بالنسبة لـ expression و filter_expression، لا يلزم إنشاء شريحة مسبقًا — يتم تقييم التعبير بشكل مضمن لهذا الإرسال فقط.

الحقل	النوع	الوصف
`schedule`	`Schedule`	متى وكيف يتم الإرسال. مطلوب.
`application`	string	رمز التطبيق.
`platforms`	array of `Platform`	المنصات التي تستهدفها الرسالة.
`code`	string	رمز الشريحة لشريحة محفوظة مسبقًا. حصري بشكل متبادل مع `expression` و `filter_expression`.
`expression`	string	تعبير Seglang، يتم تقييمه لهذا الإرسال فقط — لا يلزم وجود شريحة محفوظة. حصري بشكل متبادل مع `code` و `filter_expression`.
`filter_expression`	`FilterExpression`	نفس منطق `expression`، ككائن منظم بدلاً من سلسلة seglang. حصري بشكل متبادل مع `code` و `expression`. مخطط `FilterExpression` غير موثق علنًا — اطلبه من دعم Pushwoosh إذا كنت بحاجة إلى النموذج المنظم.
`payload`	`Payload`	حمولة Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber / Facebook Messenger. حصري بشكل متبادل مع `email_payload`.
`email_payload`	`EmailPayload`	حمولة البريد الإلكتروني.
`campaign`	string	رمز الحملة لنسب هذه الرسالة إليه.
`campaign_name`	string	اسم داخلي لهذه الرسالة، يظهر كعنوان للصف في Message History وفي تصديرها. لا علاقة له بـ `campaign` أعلاه. لا يقوم بتجميع الرسائل ولا يؤثر على التسليم. الحد الأقصى 255 حرفًا، ويتم اقتطاعه. احذفه أو اتركه فارغًا ليأتي عنوان الصف من محتوى الحمولة نفسها.
`frequency_capping`	`FrequencyCapping`	حدود التكرار لكل مستخدم.
`send_rate`	`SendRate`	التحكم في معدل الإرسال.
`message_type`	`MessageType`	`MESSAGE_TYPE_MARKETING` (افتراضي) أو `MESSAGE_TYPE_TRANSACTIONAL`. يتحكم في تصفية مجموعة التحكم.
`dynamic_content_placeholders`	map<string, string>	يستبدل العناصر النائبة في المحتوى.
`meta_data`	object	بيانات وصفية حرة الشكل يتم تمريرها إلى التحليلات النهائية.
`use_latest_user_device`	bool	عندما يكون `true`، يتم تسليم الرسالة إلى أحدث جهاز نشط لكل مستخدم (الجهاز الذي لديه أحدث “آخر فتح للتطبيق”) بدلاً من كل جهاز تطابقه الشريحة. يقتصر النطاق على `platforms`: يتم النظر فقط في الأجهزة على تلك المنصات، وإذا لم يكن لدى أي منها بيانات “آخر فتح للتطبيق”، يتم استخدام أول جهاز مطابق بدلاً من إسقاط الإرسال. الافتراضي هو `false` (إرسال إلى كل جهاز).
`control_group`	string	رمز أو اسم المجموعة الضابطة الخاصة بهذا الإرسال والتي تُطبَّق على هذه الرسالة. لا يحدّ من المجموعات الضابطة المطبقة: فكل مجموعة ضابطة مفعّلة في التطبيق تستثني المستخدمين من الإرساليات التسويقية سواء تم ضبط هذا الحقل أم لا. يتعارض مع `holdout_percentage`.
`holdout_percentage`	uint32	يسحب هذه النسبة من الشريحة، من `1` إلى `20`، إلى مجموعة ضابطة تقتصر على هذا الإرسال، إضافةً إلى المجموعات الضابطة المفعّلة في التطبيق، لقياس تأثير حملة واحدة دون استنزاف المجموعات المشتركة. القيمة `0` (الافتراضية) تُبقيه معطّلًا. يتعارض مع `control_group`.

تُستبعد الأجهزة المسحوبة إلى مجموعة الاستبعاد من التسليم بالطريقة نفسها التي تستبعدها بها المجموعات الضابطة للتطبيق. لا يُرسَل إليها شيء، ويسجّل سجل التتبع هذا الاستبعاد على أنه Device is in control group. وعندما تكون قيمة message_type هي MESSAGE_TYPE_TRANSACTIONAL يُتخطّى هذا الاستبعاد بالكامل، تمامًا كما في المجموعات الضابطة للتطبيق.

يؤدي ضبط holdout_percentage مع control_group، أو ضبط holdout_percentage بقيمة أكبر من 20، إلى إرجاع 400:

{
  "code": 3,
  "message": "invalid argument",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.BadRequest",
      "fieldViolations": [
        {
          "field": "holdout_percentage",
          "description": "holdout_percentage and control_group are mutually exclusive"
        }
      ]
    },
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "InvalidHoldoutPercentage",
      "domain": "api.pushwoosh.com",
      "metadata": {}
    }
  ]
}

مثال: إرسال إلى شريحة

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": {
      "application": "XXXXX-XXXXX",
      "platforms": ["IOS", "ANDROID"],
      "code": "active_users",
      "payload": {
        "content": {
          "localized_content": {
            "en": {
              "ios":     { "body": "Hello!" },
              "android": { "body": "Hello!" }
            }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_MARKETING"
    }
  }'

NotifyTransactional

يرسل إلى قائمة صريحة من المستلمين.

الحقل	النوع	الوصف
`schedule`	`Schedule`	مطلوب.
`application`	string	رمز التطبيق.
`platforms`	array of `Platform`	المنصات التي تستهدفها الرسالة.
`test_devices`	bool	إذا كان `true`، يتم الإرسال إلى الأجهزة الاختبارية للتطبيق فقط.
`hwids`	`{ "list": [string, ...] }`	إرسال إلى هذه hwids فقط.
`users`	`{ "list": [string, ...] }`	إرسال إلى هذه معرفات المستخدمين (user IDs) فقط.
`push_tokens`	`{ "list": [string, ...] }`	إرسال إلى هذه رموز الإشعارات الفورية (push tokens) فقط.
`payload`	`Payload`	حمولة Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber / Facebook Messenger.
`email_payload`	`EmailPayload`	حمولة البريد الإلكتروني.
`return_unknown_identifiers`	bool	عندما يكون `true`، تسرد `unknown_identifiers` في الاستجابة المعرفات التي لم يتم العثور عليها.
`use_latest_user_device`	bool	ينطبق فقط عند استهداف `users`. نفس السلوك كما في `NotifySegment` أعلاه — يسلم رسالة واحدة لكل مستخدم بدلاً من رسالة واحدة لكل جهاز، يقتصر النطاق على `platforms`. الافتراضي هو `false`.
`campaign`, `campaign_name`, `frequency_capping`, `send_rate`, `message_type`, `dynamic_content_placeholders`, `meta_data`		راجع `NotifySegment` أعلاه.

test_devices و hwids و users و push_tokens حصرية بشكل متبادل. يجب تعيين واحد فقط.

مثال: معاملاتي حسب معرفات المستخدمين

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional": {
      "application": "XXXXX-XXXXX",
      "platforms": ["IOS", "ANDROID"],
      "users": { "list": ["user-123", "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",
      "return_unknown_identifiers": true,
      "use_latest_user_device": true
    }
  }'

الاستجابة

{
  "result": {
    "message_code": "XXXXX-XXXXX-XXXXX",
    "unknown_identifiers": []
  }
}

الحقل	النوع	الوصف
`message_code`	string	رمز رسالة فريد. استخدمه مع `/getMessageDetails` ونقاط نهاية إحصائيات الرسائل.
`unknown_identifiers`	array of string	المعرفات التي لم يتم العثور عليها في الحساب. يتم ملؤها فقط عند تعيين `return_unknown_identifiers: true` على نوع `transactional`.

الأنواع المشتركة

Schedule

{
  "at": "2026-05-01T12:00:00Z",
  "follow_user_timezone": true,
  "past_timezones_behaviour": "PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY"
}

الحقل	النوع	الوصف
`at`	timestamp	وقت الإرسال المطلق (RFC 3339). إذا كان في الماضي، تستبدله Pushwoosh بوقت استلام الطلب. وعندما يكون `follow_user_timezone` غير مضبوط أو `false`، يعني ذلك أن الرسالة تُرسل على الفور إلى الجميع. راجع التنبيه أدناه بشأن `follow_user_timezone: true`. بحد أقصى 30 يومًا في المستقبل.
`after`	duration	بديل لـ `at`. إرسال بعد هذا الإزاحة من “الآن” (على سبيل المثال `"3600s"`). بحد أقصى 30 يومًا.
`follow_user_timezone`	bool	عندما يكون `true`، يتلقى كل جهاز الرسالة في `at` في منطقته الزمنية المحلية.
`past_timezones_behaviour`	enum	`PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY` (افتراضي)، `PAST_TIMEZONES_BEHAVIOUR_DO_NOT_SEND`، أو `PAST_TIMEZONES_BEHAVIOUR_NEXT_DAY`. يكون ذا معنى فقط عندما يكون `follow_user_timezone` هو `true` أو عند ضبط `best_time_to_send`.
`best_time_to_send`	timestamp	اختياري. لعمليات الإرسال إلى شريحة فقط. يتلقى كل جهاز الرسالة في أفضل ساعة خاصة به خلال 24 ساعة من هذا الوقت. أما الأجهزة التي ليست لها أفضل ساعة فتتلقاها في تاريخ ووقت `at` / `after` حسب منطقتها الزمنية المحلية. راجع أفضل وقت للإرسال.

مع follow_user_timezone: true، يظل “الآن” المُستبدَل مقسّمًا إلى فترات زمنية محلية لكل جهاز، ولا يُسلَّم إلى كل الأجهزة دفعة واحدة. المناطق الزمنية المتأخرة عن UTC لم تبلغ تلك اللحظة محليًا بعد، لذا تتلقى الرسالة بعد ما يصل إلى 12 ساعة. أما المناطق الزمنية المتقدمة على UTC فقد تجاوزت تلك اللحظة محليًا، لذا تتبع past_timezones_behaviour بدلاً من ذلك: الإرسال الآن، أو التخطي (DO_NOT_SEND)، أو التأجيل يومًا إلى الأمام (NEXT_DAY) في الوقت المحلي نفسه. وينطبق التقسيم نفسه على الإرسال الاحتياطي في best_time_to_send.

أفضل وقت للإرسال

best_time_to_send هو المقابل في API لخيار أفضل وقت في Control Panel. يحدد at / after الإرسال الاحتياطي للأجهزة التي لا تتوفر لها بيانات كافية لتحديد أفضل ساعة. تأخذ Pushwoosh تاريخ ووقت at / after بتوقيت UTC وتسلّم الإرسال الاحتياطي في ذلك التاريخ والوقت حسب المنطقة الزمنية المحلية لكل جهاز، كما هو الحال مع follow_user_timezone: true. يُطبَّق ذلك ضمنيًا: اترك follow_user_timezone دون ضبط، لأن القيمة true تُرفض مع BestTimeToSendWithUserTimezone. في المثال أدناه، تتلقى الأجهزة التي ليست لها أفضل ساعة الرسالة في الساعة 18:00 بالتوقيت المحلي يوم 1 مايو. وحيثما يكون ذلك الوقت المحلي قد مضى عند بدء الإرسال، يُطبَّق past_timezones_behaviour.

{
  "at": "2026-05-01T18:00:00Z",
  "best_time_to_send": "2026-05-01T00:00:00Z"
}

ترفض Pushwoosh الطلب مع 400 ما لم تتحقق جميع الشروط التالية:

يستخدم الطلب النوع segment. لا تدعم عمليات الإرسال transactional الحقل best_time_to_send.
follow_user_timezone غير مضبوط أو قيمته false.
وقت الإرسال المحدد في at / after في المستقبل. تُعد قيمة at في الماضي، أو after: "0s"، أو حذف after بمثابة “أرسل الآن” وتُرفض.
لا يكون best_time_to_send قبل الساعة الكاملة التالية، ولا يتجاوز 30 يومًا في المستقبل. ويُقرَّب إلى الأسفل إلى الساعة الكاملة.
لا يكون وقت الإرسال المحدد في at / after بعد best_time_to_send مضافًا إليه 24 ساعة.

يحدد reason في الخطأ (ضمن تفاصيل ErrorInfo) التحقق الذي فشل:

`reason`	السبب
`BestTimeToSendWithUserTimezone`	قيمة `follow_user_timezone` هي `true`.
`BestTimeToSendTooEarly`	`best_time_to_send` قبل الساعة الكاملة التالية.
`BestTimeToSendTooFarInFuture`	`best_time_to_send` يتجاوز 30 يومًا في المستقبل.
`SendDateAfterBestTimeToSend`	`at` / `after` بعد `best_time_to_send` مضافًا إليه 24 ساعة.
`BestTimeToSendNotAllowed`	تم ضبط `best_time_to_send` في إرسال `transactional`.
`BestTimeToSendWithSendNow`	يُحسب `at` / `after` على أنه “الآن” (`at` في الماضي أو `after` صفري).

FrequencyCapping

حدود التكرار لكل مستخدم للإرسالات التسويقية. لتعطيل تحديد السقف، احذف frequency_capping بالكامل، أو أرسل days: 0 مع count: 0.

{ "days": 7, "count": 3, "exclude": false, "avoid": true }

days (int, 1–30, أو 0 لتعطيل تحديد السقف): نافذة المراجعة. يجب إرسالها مع count — إذا كان أحدهما 0، فيجب أن يكون الآخر أيضًا 0؛ إرسال أحدهما كـ 0 بينما الآخر غير صفري يُرجع 400.
count (int, 1 أو أعلى، أو 0 لتعطيل تحديد السقف): الحد الأقصى للرسائل المسموح بها خلال days. نفس قاعدة الاقتران مثل days أعلاه.
exclude (bool): استبعاد صارم للمستخدمين الذين وصلوا بالفعل إلى الحد الأقصى.
avoid (bool): تجنب ناعم للمستخدمين الذين وصلوا بالفعل إلى الحد الأقصى (لا يزالون يُحتسبون ضمن التحليلات).

SendRate

{ "value": 500, "bucket": "1s", "avoid": false }

يتحكم في معدل الإرسال. value هو عدد الرسائل لكل bucket؛ bucket النموذجي هو "1s".

تعداد المنصات (Platform enum)

IOS, ANDROID, OSX, WINDOWS, AMAZON, SAFARI, CHROME, FIREFOX, IE, EMAIL, HUAWEI_ANDROID, SMS, WEB, KAKAO, TELEGRAM, LINE, WHATS_APP, VIBER, FB_MESSENGER.

تعداد نوع الرسالة (MessageType enum)

MESSAGE_TYPE_UNSPECIFIED: مكافئ لـ MESSAGE_TYPE_MARKETING.
MESSAGE_TYPE_MARKETING: يخضع لتصفية مجموعة التحكم وتحديد سقف التكرار.
MESSAGE_TYPE_TRANSACTIONAL: يتخطى تصفية مجموعة التحكم وتحديد سقف التكرار. استخدمه لتأكيدات الطلبات، وكلمات المرور لمرة واحدة (OTPs)، والتدفقات الحرجة المماثلة.

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

دفعة Notify

إلغاء

مرجع الحمولة (Payload)

مرجع حمولة البريد الإلكتروني

الترحيل من v1