إرسال إشعار (Notify)

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 / LINE / WhatsApp / Viber. متعارض مع 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	حمولة Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber.
email_payload	EmailPayload	حمولة البريد الإلكتروني.
return_unknown_identifiers	bool	عندما تكون true، تعرض قائمة unknown_identifiers في الاستجابة المعرفات التي لم يتم العثور عليها.
use_latest_user_device	bool	ينطبق فقط عند استهداف users. عندما تكون true، يتم تسليم الرسالة إلى أحدث جهاز نشط لكل مستخدم — الجهاز الذي لديه أحدث وقت لفتح التطبيق (Last Application Open) — بدلاً من جميع الأجهزة المرتبطة بمعرف المستخدم هذا. القيمة الافتراضية هي 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

حدود التكرار لكل مستخدم للإرسالات التسويقية. لتعطيل الحد، احذف 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): تجنب ناعم للمستخدمين الذين وصلوا بالفعل إلى الحد الأقصى (لا يزالون يُحتسبون في التحليلات).

هام

إرسال days و count بصفرية غير متطابقة (على سبيل المثال، {"days": 0, "count": 5}) يعيد 400. هذا التحقق هو تغيير جذري في Notify — العملاء الذين كانوا يعتمدون سابقًا على تجاهل 0 منفرد بصمت سيحصلون الآن على خطأ بدلاً من ذلك.

SendRate

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

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

تعداد Platform

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

تعداد MessageType

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

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

إلغاء

مرجع الحمولة

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

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