إشعار (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` (إرسال إلى كل جهاز).

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

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). إذا كان في الماضي، يتم إرسال الرسالة على الفور. بحد أقصى 14 يومًا في المستقبل.
`after`	duration	بديل لـ `at`. إرسال بعد هذا الإزاحة من “الآن” (على سبيل المثال `"3600s"`).
`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`.

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