Notify

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

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

هيكل الطلب

نص الطلب هو NotifyRequest بأحد نوعين بالضبط:

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

الشكل

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

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

نصيحة

مرّر ترويسة X-Request-ID لربط الرسالة التي تم إنشاؤها بطلبك للتتبع من البداية إلى النهاية — انظر معرف الطلب (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	رمز التطبيق (Application code).
platforms	array of Platform	المنصات التي تستهدفها الرسالة.
code	string	رمز الشريحة (Segment code). حصري متبادل مع 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	رمز الحملة (Campaign code) لنسب هذه الرسالة إليه.
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	رمز التطبيق (Application code).
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 / 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	رمز الرسالة (message code) الفريد. استخدمه مع /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. هذا التحقق هو تغيير جذري (breaking change) في Notify — العملاء الذين كانوا يعتمدون سابقًا على تجاهل القيمة 0 المنفردة بصمت سيتلقون الآن خطأ بدلاً من ذلك.

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: يتخطى فلترة مجموعة التحكم وتحديد معدل التكرار. استخدمه لتأكيدات الطلبات، ورموز OTP، والتدفقات الحرجة المماثلة.

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

إلغاء

مرجع الحمولة (Payload)

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

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