إشعار

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

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

هيكل الطلب

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

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

الشكل

{
  "segment": { ... },      // أو
  "transactional": { ... },
  "transaction_id": "unique-uuid"
}

الحقل	النوع	الوصف
transaction_id	string	اختياري. مفتاح Idempotency للطلب — يعمل مع كل من segment و transactional. استدعاء متكرر بنفس transaction_id في غضون 5 دقائق يُرجع message_code الأصلي بدلاً من إرسال رسالة مكررة. استخدم UUID أو قيمة أخرى فريدة لكل إرسال منطقي.

نصيحة

مرّر ترويسة X-Request-ID لربط الرسالة التي تم إنشاؤها بطلبك للتتبع من طرف إلى طرف — انظر معرف الطلب.

يتم التحقق من المفتاح فقط، وليس الحمولة

تطابق إزالة التكرار على transaction_id وحده. إذا أعادت محاولة استخدام نفس transaction_id ولكن أرسلت جسم segment / transactional مختلف، فسيتم إرجاع message_code الأصلي ويتم تجاهل الجسم الجديد بصمت — لا تتم مقارنته بالطلب الأول. لا تعيد استخدام transaction_id أبدًا عبر رسائل مختلفة منطقيًا.

نصيحة

هذه هي نفس آلية إزالة التكرار مثل transactionId في Messages API القديمة، وتتشارك في نفس نافذة التخزين لمدة 5 دقائق، لذلك يتم إزالة تكرار الطلب المعاد محاولته عبر /createMessage و Notify على حد سواء. لا علاقة له بسمة transaction_id في أحداث الإيرادات PW_Conversion، والتي يخزنها Pushwoosh كما هي ولا يستخدمها لإزالة التكرار.

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	بيانات وصفية حرة الشكل يتم توجيهها إلى التحليلات النهائية.
use_latest_user_device	bool	عندما تكون true، يتم تسليم الرسالة إلى أحدث جهاز نشط لكل مستخدم (الجهاز الذي لديه أحدث Last Application Open) بدلاً من كل جهاز يطابقه الشريحة. يقتصر النطاق على platforms: يتم النظر فقط في الأجهزة على تلك المنصات، وإذا لم يكن لدى أي منها بيانات Last Application Open، يتم استخدام أول جهاز مطابق بدلاً من إسقاط الإرسال. الافتراضي هو 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, ...] }	إرسال إلى هذه معرفات المستخدمين فقط.
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. نفس السلوك كما في NotifySegment أعلاه — يسلم رسالة واحدة لكل مستخدم بدلاً من رسالة واحدة لكل جهاز، يقتصر النطاق على platforms. الافتراضي هو 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, HUAWEI_ANDROID, SMS, WEB, KAKAO, TELEGRAM, LINE, WHATS_APP, VIBER.

تعداد MessageType

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

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

دفعة إشعار

إلغاء

مرجع الحمولة

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

الترحيل من v1