إشعار (Notify)
POST https://api.pushwoosh.com/messaging/v2/notify
ينشئ ويجدول رسالة واحدة.
بنية الطلب
Anchor link toنص الطلب هو NotifyRequest بنوع واحد فقط من نوعين:
segment: استهداف شريحة جمهور برمز الشريحة، أو — دون إنشاء شريحة أولاً — تعبير seglang أو تعبير مرشح منظم.transactional: إرسال إلى قائمة صريحة من hwids، معرفات المستخدمين (user IDs)، رموز الإشعارات الفورية (push tokens)، أو الأجهزة الاختبارية.
{ "segment": { ... }, // أو "transactional": { ... }, "transaction_id": "unique-uuid"}| الحقل | النوع | الوصف |
|---|---|---|
transaction_id | string | اختياري. مفتاح عدم التكرار للطلب — يعمل مع كل من segment و transactional. إعادة الاتصال بنفس transaction_id خلال 5 دقائق تُرجع message_code الأصلي بدلاً من إرسال رسالة مكررة. استخدم UUID أو قيمة أخرى فريدة لكل عملية إرسال منطقية. |
NotifySegment
Anchor link toيستهدف المستخدمين الذين يطابقون شريحة جمهور أو تعبير مرشح. قم بتعيين واحد فقط من code أو expression أو filter_expression. بالنسبة لـ expression و filter_expression، لا يلزم إنشاء شريحة مسبقًا — يتم تقييم التعبير بشكل مضمن لهذا الإرسال فقط.
| الحقل | النوع | الوصف |
|---|---|---|
schedule | Schedule | متى وكيف يتم الإرسال. مطلوب. |
application | string | رمز التطبيق. |
platforms | array of Platform | المنصات التي تستهدفها الرسالة. |
code | string | رمز الشريحة لشريحة محفوظة مسبقًا. حصري بشكل متبادل مع expression و filter_expression. |
expression | string | تعبير Seglang، يتم تقييمه لهذا الإرسال فقط — لا يلزم وجود شريحة محفوظة. حصري بشكل متبادل مع code و filter_expression. |
filter_expression | FilterExpression | نفس منطق expression، ككائن منظم بدلاً من سلسلة seglang. حصري بشكل متبادل مع code و expression. مخطط FilterExpression غير موثق علنًا — اطلبه من دعم Pushwoosh إذا كنت بحاجة إلى النموذج المنظم. |
payload | Payload | حمولة Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber / Facebook Messenger. حصري بشكل متبادل مع email_payload. |
email_payload | EmailPayload | حمولة البريد الإلكتروني. |
campaign | string | رمز الحملة لنسب هذه الرسالة إليه. |
campaign_name | string | اسم داخلي لهذه الرسالة، يظهر كعنوان للصف في Message History وفي تصديرها. لا علاقة له بـ campaign أعلاه. لا يقوم بتجميع الرسائل ولا يؤثر على التسليم. الحد الأقصى 255 حرفًا، ويتم اقتطاعه. احذفه أو اتركه فارغًا ليأتي عنوان الصف من محتوى الحمولة نفسها. |
frequency_capping | FrequencyCapping | حدود التكرار لكل مستخدم. |
send_rate | SendRate | التحكم في معدل الإرسال. |
silent_hours | SilentHours | اختياري. يرسل الرسالة دون مراعاة ساعات الصمت الخاصة بالتطبيق. |
message_type | MessageType | MESSAGE_TYPE_MARKETING (افتراضي) أو MESSAGE_TYPE_TRANSACTIONAL. يتحكم في تصفية مجموعة التحكم. |
dynamic_content_placeholders | map<string, string> | يستبدل العناصر النائبة في المحتوى. |
meta_data | object | بيانات وصفية حرة الشكل يتم تمريرها إلى التحليلات النهائية. |
use_latest_user_device | bool | عندما يكون true، يتم تسليم الرسالة إلى أحدث جهاز نشط لكل مستخدم (الجهاز الذي لديه أحدث “آخر فتح للتطبيق”) بدلاً من كل جهاز تطابقه الشريحة. يقتصر النطاق على platforms: يتم النظر فقط في الأجهزة على تلك المنصات، وإذا لم يكن لدى أي منها بيانات “آخر فتح للتطبيق”، يتم استخدام أول جهاز مطابق بدلاً من إسقاط الإرسال. الافتراضي هو false (إرسال إلى كل جهاز). |
geo_zone | GeoZone | اختياري. يضيّق الجمهور ليقتصر على الأجهزة التي يقع آخر موقع مسجَّل لها داخل دائرة تحددها في هذا الطلب. يُدمج مع code أو expression أو filter_expression بعامل AND: يجب أن يطابق الجهاز الشريحة وأن يقع داخل الدائرة. تُتخطّى الأجهزة التي ليس لها موقع مسجَّل. غير متاح في NotifyTransactional. |
control_group | string | رمز أو اسم المجموعة الضابطة الخاصة بهذا الإرسال والتي تُطبَّق على هذه الرسالة. لا يحدّ من المجموعات الضابطة المطبقة: فكل مجموعة ضابطة مفعّلة في التطبيق تستثني المستخدمين من الإرساليات التسويقية سواء تم ضبط هذا الحقل أم لا. يتعارض مع holdout_percentage. |
holdout_percentage | uint32 | يسحب هذه النسبة من الشريحة، من 1 إلى 20، إلى مجموعة ضابطة تقتصر على هذا الإرسال، إضافةً إلى المجموعات الضابطة المفعّلة في التطبيق، لقياس تأثير حملة واحدة دون استنزاف المجموعات المشتركة. القيمة 0 (الافتراضية) تُبقيه معطّلًا. يتعارض مع control_group. |
تُستبعد الأجهزة المسحوبة إلى مجموعة الاستبعاد من التسليم بالطريقة نفسها التي تستبعدها بها المجموعات الضابطة للتطبيق. لا يُرسَل إليها شيء، ويسجّل سجل التتبع هذا الاستبعاد على أنه Device is in control group. وعندما تكون قيمة message_type هي MESSAGE_TYPE_TRANSACTIONAL يُتخطّى هذا الاستبعاد بالكامل، تمامًا كما في المجموعات الضابطة للتطبيق.
يؤدي ضبط holdout_percentage مع control_group، أو ضبط holdout_percentage بقيمة أكبر من 20، إلى إرجاع 400:
{ "code": 3, "message": "invalid argument", "details": [ { "@type": "type.googleapis.com/google.rpc.BadRequest", "fieldViolations": [ { "field": "holdout_percentage", "description": "holdout_percentage and control_group are mutually exclusive" } ] }, { "@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": "InvalidHoldoutPercentage", "domain": "api.pushwoosh.com", "metadata": {} } ]}مثال: إرسال إلى شريحة
Anchor link tocurl -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
Anchor link toيرسل إلى قائمة صريحة من المستلمين.
| الحقل | النوع | الوصف |
|---|---|---|
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 / LINE / WhatsApp / Viber / Facebook Messenger. |
email_payload | EmailPayload | حمولة البريد الإلكتروني. |
return_unknown_identifiers | bool | عندما يكون true، تسرد unknown_identifiers في الاستجابة المعرفات التي لم يتم العثور عليها. |
registration_type | RegistrationType | ما يجب فعله مع hwids غير المسجلة في Pushwoosh بعد. القيمة الافتراضية هي REGISTRATION_TYPE_DEFAULT، التي تتخطاها. اضبط REGISTRATION_TYPE_FORCE لتسجيل عناوين البريد الإلكتروني أو أرقام الهواتف الجديدة والإرسال إليها في الطلب نفسه. |
use_latest_user_device | bool | ينطبق فقط عند استهداف users. نفس السلوك كما في NotifySegment أعلاه — يسلم رسالة واحدة لكل مستخدم بدلاً من رسالة واحدة لكل جهاز، يقتصر النطاق على platforms. الافتراضي هو false. |
campaign, campaign_name, frequency_capping, send_rate, silent_hours, message_type, dynamic_content_placeholders, meta_data | راجع NotifySegment أعلاه. |
test_devices و hwids و users و push_tokens حصرية بشكل متبادل. يجب تعيين واحد فقط.
الإرسال إلى عناوين بريد إلكتروني وأرقام هواتف جديدة
Anchor link toبالنسبة إلى البريد الإلكتروني و SMS و WhatsApp و LINE و Viber و Kakao، يكون hwid هو الوجهة نفسها، مثل عنوان البريد الإلكتروني أو رقم الهاتف. للإرسال إلى hwid غير مسجَّل بعد، أدرجه في hwids واضبط registration_type على REGISTRATION_TYPE_FORCE. تسجّله Pushwoosh وتسلّم الرسالة في الطلب نفسه، لذا لا تحتاج إلى استدعاء منفصل لـ /registerDevice أو /registerEmail أولاً.
يعمل registration_type فقط مع hwids. مع users، لا يُنشأ معرف مستخدم غير معروف، بغض النظر عن قيمة registration_type.
اكتب كل hwid بالتنسيق نفسه الذي يخزّنه /registerDevice لتلك القناة:
| القناة | تنسيق hwid | مثال |
|---|---|---|
| البريد الإلكتروني | عنوان البريد الإلكتروني | new.customer@example.com |
| SMS | رقم الهاتف بالتنسيق الدولي | +14155552671 |
رقم الهاتف مع البادئة whatsapp: | whatsapp:+14155552671 | |
| Kakao | رقم الهاتف مع البادئة kakao: | kakao:+821012345678 |
| Viber | رقم الهاتف مع البادئة viber:. تضيف Pushwoosh البادئة إذا كانت مفقودة | viber:+14155552671 |
| LINE | معرف مستخدم LINE | U4af4980629a1b2c3d4e5f6a7b8c9d0e1 |
احتفظ بالبادئتين whatsapp: و kakao:. بدونهما، يُقرأ الرقم على أنه hwid لـ SMS. إذا كان هذا الرقم مسجلاً بالفعل لـ SMS، فإن الإرسال يعثر على hwid الخاص بـ SMS، الذي لا يطابق المنصة المستهدفة، ويُتخطّى المستلم.
لا تتحقق Pushwoosh من أرقام الهواتف إلا مع return_unknown_identifiers: true. عندها لا يُسجَّل hwid الخاص بـ SMS أو WhatsApp أو Kakao الذي ليس رقم هاتف صالحًا، ويُعاد في unknown_identifiers. بدون هذه العلامة، تُسجَّل القيمة كما هي.
لا يسجّل REGISTRATION_TYPE_FORCE قيم hwid على منصات الإشعارات الفورية أو Telegram أو Facebook Messenger، لأنها تحتاج إلى رمز (token) من SDK أو من تطبيق المراسلة. يُسقَط hwid غير المعروف على هذه المنصات بصمت. لا يُعاد في unknown_identifiers، ولا يُرسَل إليه شيء.
بالنسبة إلى WhatsApp، لا يفتح تسجيل رقم نافذة خدمة العملاء لمدة 24 ساعة. الرقم الذي لم يراسلك يمكنه أن يتلقى فقط قالبًا معتمدًا مسبقًا محددًا في whatsapp.content_id، وليس whatsapp.content الحر.
مثال: الإرسال إلى عنوان بريد إلكتروني جديد
Anchor link tocurl -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": ["EMAIL"], "hwids": { "list": ["new.customer@example.com"] }, "registration_type": "REGISTRATION_TYPE_FORCE", "email_payload": { "subject": { "en": "Welcome aboard" }, "body": "<p>Thanks for signing up!</p>" }, "schedule": { "at": "2026-05-01T12:00:00Z" }, "message_type": "MESSAGE_TYPE_TRANSACTIONAL", "return_unknown_identifiers": true } }'مثال: معاملاتي حسب معرفات المستخدمين
Anchor link tocurl -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 } }'الاستجابة
Anchor link to{ "result": { "message_code": "XXXXX-XXXXX-XXXXX", "unknown_identifiers": [] }}| الحقل | النوع | الوصف |
|---|---|---|
message_code | string | رمز رسالة فريد. استخدمه مع /getMessageDetails ونقاط نهاية إحصائيات الرسائل. |
unknown_identifiers | array of string | المعرفات التي لم يتم العثور عليها في الحساب. يتم ملؤها فقط لإرسال transactional مع return_unknown_identifiers: true أو مع الاستهداف عبر push_tokens. لا تُدرج المعرفات المسجلة عبر REGISTRATION_TYPE_FORCE. |
لا يمكن لـ /getMessageDetails العثور على رسالة transactional أُرسلت فورًا إلى أقل من 10 مستخدمين وأقل من 10 أجهزة، لأن مثل هذه الرسالة لا يتم تخزينها. راجع الرسائل المرسلة فورًا إلى أقل من 10 مستلمين.
لم يتم العثور على مستلمين
Anchor link toمع return_unknown_identifiers: true أو الاستهداف عبر push_tokens، تبحث Pushwoosh عن كل مستلم قبل إنشاء الرسالة. إذا لم يكن أي منهم مسجلاً، يُرجع Notify رمز HTTP 400 مع هذا الخطأ، ولا تُنشأ أي رسالة:
{ "code": 9, "message": "No recipients found", "details": [ ... ]}إذا عُثر على مستلم واحد على الأقل، ينجح الطلب وتُدرج البقية في unknown_identifiers. للإرسال إلى عناوين بريد إلكتروني أو أرقام هواتف جديدة بدلاً من ذلك، اضبط registration_type على REGISTRATION_TYPE_FORCE.
بالنسبة إلى البريد الإلكتروني، تُزال العناوين غير الصالحة والعناوين التي ارتدّت سابقًا قبل هذا التحقق، دون إدراجها في unknown_identifiers. إذا لم يتبقَّ أي عنوان بعد ذلك، يُرجع Notify 200 مع message_code، لكن لا تُنشأ أي رسالة ولا يُرسَل شيء.
الأنواع المشتركة
Anchor link toSchedule
Anchor link to{ "at": "2026-05-01T12:00:00Z", "follow_user_timezone": true, "past_timezones_behaviour": "PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY"}| الحقل | النوع | الوصف |
|---|---|---|
at | timestamp | وقت الإرسال المطلق (RFC 3339). بحد أقصى 30 يومًا في المستقبل. عندما يكون follow_user_timezone غير مضبوط أو false، تُستبدل قيمة at الماضية بوقت استلام الطلب، فتُرسل الرسالة على الفور إلى الجميع. مع follow_user_timezone: true، تُبقى قيمة at الماضية كما هي. راجع التنبيه أدناه. |
after | duration | بديل لـ at. إرسال بعد هذا الإزاحة من “الآن” (على سبيل المثال "3600s"). بحد أقصى 30 يومًا. |
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 أو عند ضبط best_time_to_send. |
best_time_to_send | timestamp | اختياري. لعمليات الإرسال إلى شريحة فقط. يتلقى كل جهاز الرسالة في أفضل ساعة خاصة به خلال 24 ساعة من هذا الوقت. أما الأجهزة التي ليست لها أفضل ساعة فتتلقاها في تاريخ ووقت at / after حسب منطقتها الزمنية المحلية. راجع أفضل وقت للإرسال. |
أفضل وقت للإرسال
Anchor link tobest_time_to_send هو المقابل في API لخيار أفضل وقت في Control Panel. يحدد at / after الإرسال الاحتياطي للأجهزة التي لا تتوفر لها بيانات كافية لتحديد أفضل ساعة. تأخذ Pushwoosh تاريخ ووقت at / after بتوقيت UTC وتسلّم الإرسال الاحتياطي في ذلك التاريخ والوقت حسب المنطقة الزمنية المحلية لكل جهاز، كما هو الحال مع follow_user_timezone: true. يُطبَّق ذلك ضمنيًا: اترك follow_user_timezone دون ضبط، لأن القيمة true تُرفض مع BestTimeToSendWithUserTimezone. في المثال أدناه، تتلقى الأجهزة التي ليست لها أفضل ساعة الرسالة في الساعة 18:00 بالتوقيت المحلي يوم 1 مايو. وحيثما يكون ذلك الوقت المحلي قد مضى عند بدء الإرسال، يُطبَّق past_timezones_behaviour.
{ "at": "2026-05-01T18:00:00Z", "best_time_to_send": "2026-05-01T00:00:00Z"}ترفض Pushwoosh الطلب مع 400 ما لم تتحقق جميع الشروط التالية:
- يستخدم الطلب النوع
segment. لا تدعم عمليات الإرسالtransactionalالحقلbest_time_to_send. follow_user_timezoneغير مضبوط أو قيمتهfalse.- وقت الإرسال المحدد في
at/afterفي المستقبل. تُعد قيمةatفي الماضي، أوafter: "0s"، أو حذفafterبمثابة “أرسل الآن” وتُرفض. - لا يكون
best_time_to_sendقبل الساعة الكاملة التالية، ولا يتجاوز 30 يومًا في المستقبل. ويُقرَّب إلى الأسفل إلى الساعة الكاملة. - لا يكون وقت الإرسال المحدد في
at/afterبعدbest_time_to_sendمضافًا إليه 24 ساعة.
يحدد reason في الخطأ (ضمن تفاصيل ErrorInfo) التحقق الذي فشل:
reason | السبب |
|---|---|
BestTimeToSendWithUserTimezone | قيمة follow_user_timezone هي true. |
BestTimeToSendTooEarly | best_time_to_send قبل الساعة الكاملة التالية. |
BestTimeToSendTooFarInFuture | best_time_to_send يتجاوز 30 يومًا في المستقبل. |
SendDateAfterBestTimeToSend | at / after بعد best_time_to_send مضافًا إليه 24 ساعة. |
BestTimeToSendNotAllowed | تم ضبط best_time_to_send في إرسال transactional. |
BestTimeToSendWithSendNow | يُحسب at / after على أنه “الآن” (at في الماضي أو after صفري). |
GeoZone
Anchor link toدائرة لمرة واحدة لـ geo_zone، تُعرَّف في الطلب نفسه. وهي ليست منطقة جغرافية محفوظة: لا تشارك الحملات الجغرافية ولا Geozones API، ولا يُخزَّن أي شيء في التطبيق.
{ "lat": 40.7128, "lng": -74.006, "range": 500 }| الحقل | النوع | الوصف |
|---|---|---|
lat | double | خط عرض مركز الدائرة، بالدرجات. مطلوب. |
lng | double | خط طول مركز الدائرة، بالدرجات. مطلوب. |
range | double | نصف قطر الدائرة بالأمتار. مطلوب. |
FrequencyCapping
Anchor link toحدود التكرار لكل مستخدم للإرسالات التسويقية. لتعطيل تحديد السقف، احذف 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): تجنب ناعم للمستخدمين الذين وصلوا بالفعل إلى الحد الأقصى (لا يزالون يُحتسبون ضمن التحليلات).
SendRate
Anchor link to{ "value": 500, "bucket": "1s", "avoid": false }يتحكم في معدل الإرسال. value هو عدد الرسائل لكل bucket؛ bucket النموذجي هو "1s".
SilentHours
Anchor link to{ "avoid": true }تلتزم الرسائل التسويقية افتراضيًا بساعات الصمت الخاصة بالتطبيق: خلال ساعات الصمت، يتم تأجيلها حتى انتهائها أو لا يتم إرسالها، وفقًا لإعدادات القناة. اضبط avoid على true لإرسال هذه الرسالة حتى خلال ساعات الصمت. الرسائل التي يكون message_type فيها MESSAGE_TYPE_TRANSACTIONAL لا تؤجلها ساعات الصمت أبدًا، لذا لا تحتاج إلى هذا الحقل.
تعداد المنصات (Platform enum)
Anchor link toIOS, ANDROID, OSX, WINDOWS, AMAZON, SAFARI, CHROME, FIREFOX, IE, EMAIL, HUAWEI_ANDROID, SMS, WEB, KAKAO, TELEGRAM, LINE, WHATS_APP, VIBER, FB_MESSENGER.
تعداد نوع التسجيل (RegistrationType enum)
Anchor link toREGISTRATION_TYPE_DEFAULT: يتخطى المعرفات غير المسجلة في Pushwoosh. القيمة الافتراضية.REGISTRATION_TYPE_NONE: يرسل إلى كل hwid مدرج دون حفظ جهاز له.REGISTRATION_TYPE_FORCE: يسجّل كل hwid غير معروف كجهاز على القناة المستهدفة، ثم يرسل إليه. ينطبق على البريد الإلكتروني و SMS و WhatsApp و LINE و Viber و Kakao.
تعداد نوع الرسالة (MessageType enum)
Anchor link toMESSAGE_TYPE_UNSPECIFIED: مكافئ لـMESSAGE_TYPE_MARKETING.MESSAGE_TYPE_MARKETING: يخضع لتصفية مجموعة التحكم وتحديد سقف التكرار وساعات الصمت.MESSAGE_TYPE_TRANSACTIONAL: يتخطى تصفية مجموعة التحكم وتحديد سقف التكرار وساعات الصمت. استخدمه لتأكيدات الطلبات، وكلمات المرور لمرة واحدة (OTPs)، والتدفقات الحرجة المماثلة.