إرسال إشعار

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

إنشاء وجدولة رسالة واحدة.

هيكل الطلب

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

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

الشكل

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

NotifySegment

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

الحقل	النوع	الوصف
schedule	Schedule	متى وكيف يتم الإرسال. مطلوب.
application	string	رمز التطبيق.
platforms	array of Platform	المنصات التي تستهدفها الرسالة.
code	string	رمز الشريحة. متعارض مع expression و filter_expression.
expression	string	تعبير Seglang.
filter_expression	FilterExpression	تعبير فلتر منظم (متقدم).
payload	Payload	حمولة Push / SMS / Telegram / Kakao. متعارض مع 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, ...] }	الإرسال إلى هذه المعرفات (user IDs) فقط.
push_tokens	{ "list": [string, ...] }	الإرسال إلى هذه الرموز (push tokens) فقط.
payload	Payload	حمولة Push / SMS / Telegram / Kakao.
email_payload	EmailPayload	حمولة البريد الإلكتروني.
return_unknown_identifiers	bool	عندما تكون true، تعرض unknown_identifiers في الاستجابة قائمة بالمعرفات التي لم يتم العثور عليها.
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
    }
  }'

الاستجابة

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

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

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

الجدول الزمني

{
  "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.

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

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

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

مرجع الحمولة

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

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