إرسال إشعار

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 في الاستجابة المعرفات التي لم يتم العثور عليها.
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

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

تعداد MessageType

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

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

إلغاء

مرجع الحمولة

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

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