إشعار

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

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

بنية الطلب

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

• segment: استهداف شريحة جمهور حسب رمز الشريحة، أو تعبير seglang، أو تعبير مرشح منظم.
• transactional: الإرسال إلى قائمة صريحة من hwids، أو معرفات المستخدمين، أو رموز الإشعارات اللحظية، أو الأجهزة الاختبارية.

الشكل

{
  "segment": { ... }       // أو
  "transactional": { ... }
}

NotifySegment

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

الحقل	النوع	الوصف
schedule	Schedule	متى وكيف يتم الإرسال. مطلوب.
application	string	رمز التطبيق.
platforms	array of Platform	المنصات التي تستهدفها الرسالة.
code	string	رمز الشريحة. متعارض مع expression و filter_expression.
expression	string	تعبير Seglang.
filter_expression	FilterExpression	تعبير مرشح منظم (متقدم).
payload	Payload	حمولة الإشعارات اللحظية / الرسائل النصية / تيليجرام / كاكاو. متعارض مع email_payload.
email_payload	EmailPayload	حمولة البريد الإلكتروني.
campaign	string	رمز الحملة لنسب هذه الرسالة إليه.
frequency_capping	FrequencyCapping	حدود التكرار لكل مستخدم.
send_rate	SendRate	التحكم في سرعة الإرسال.
message_type	MessageType	MESSAGE_TYPE_MARKETING (الافتراضي) أو MESSAGE_TYPE_TRANSACTIONAL. يتحكم في تصفية مجموعة التحكم.
dynamic_content_placeholders	map<string, string>	يستبدل العناصر النائبة في المحتوى.
meta_data	object	بيانات وصفية حرة الشكل تُمرر إلى التحليلات النهائية.

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

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, ...] }	الإرسال إلى معرفات المستخدمين هذه فقط.
push_tokens	{ "list": [string, ...] }	الإرسال إلى رموز الإشعارات اللحظية هذه فقط.
payload	Payload	حمولة الإشعارات اللحظية / الرسائل النصية / تيليجرام / كاكاو.
email_payload	EmailPayload	حمولة البريد الإلكتروني.
return_unknown_identifiers	bool	عندما يكون true، تعرض الاستجابة في unknown_identifiers قائمة بالمعرفات التي لم يتم العثور عليها.
use_latest_user_device	bool	ينطبق فقط عند استهداف users. عندما يكون true، يتم تسليم الرسالة إلى أحدث جهاز نشط لكل مستخدم — الجهاز الذي لديه أحدث وقت لفتح التطبيق — بدلاً من جميع الأجهزة المرتبطة بمعرف المستخدم هذا. القيمة الافتراضية هي false (الإرسال إلى كل جهاز).
campaign, 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)

حدود التكرار لكل مستخدم للإرسالات التسويقية.

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

• days (int, 1–30): نافذة المراجعة الزمنية.
• count (int): الحد الأقصى للرسائل المسموح بها خلال 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, BAIDU_ANDROID, HUAWEI_ANDROID, SMS, WEB, KAKAO, TELEGRAM, LINE, WHATS_APP, VIBER.

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

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

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

إلغاء

مرجع الحمولة

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

الترحيل من الإصدار v1