انتقل إلى المحتوى

إشعار (Notify)

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

ينشئ ويجدول رسالة واحدة.

بنية الطلب

Anchor link to

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

  • segment: استهداف شريحة جمهور برمز الشريحة، أو — دون إنشاء شريحة أولاً — تعبير seglang أو تعبير مرشح منظم.
  • transactional: إرسال إلى قائمة صريحة من hwids، معرفات المستخدمين (user IDs)، رموز الإشعارات الفورية (push tokens)، أو الأجهزة الاختبارية.
Shape
{
"segment": { ... }, // أو
"transactional": { ... },
"transaction_id": "unique-uuid"
}
الحقلالنوعالوصف
transaction_idstringاختياري. مفتاح عدم التكرار للطلب — يعمل مع كل من segment و transactional. إعادة الاتصال بنفس transaction_id خلال 5 دقائق تُرجع message_code الأصلي بدلاً من إرسال رسالة مكررة. استخدم UUID أو قيمة أخرى فريدة لكل عملية إرسال منطقية.

NotifySegment

Anchor link to

يستهدف المستخدمين الذين يطابقون شريحة جمهور أو تعبير مرشح. قم بتعيين واحد فقط من code أو expression أو filter_expression. بالنسبة لـ expression و filter_expression، لا يلزم إنشاء شريحة مسبقًا — يتم تقييم التعبير بشكل مضمن لهذا الإرسال فقط.

الحقلالنوعالوصف
scheduleScheduleمتى وكيف يتم الإرسال. مطلوب.
applicationstringرمز التطبيق.
platformsarray of Platformالمنصات التي تستهدفها الرسالة.
codestringرمز الشريحة لشريحة محفوظة مسبقًا. حصري بشكل متبادل مع expression و filter_expression.
expressionstringتعبير Seglang، يتم تقييمه لهذا الإرسال فقط — لا يلزم وجود شريحة محفوظة. حصري بشكل متبادل مع code و filter_expression.
filter_expressionFilterExpressionنفس منطق expression، ككائن منظم بدلاً من سلسلة seglang. حصري بشكل متبادل مع code و expression. مخطط FilterExpression غير موثق علنًا — اطلبه من دعم Pushwoosh إذا كنت بحاجة إلى النموذج المنظم.
payloadPayloadحمولة Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber / Facebook Messenger. حصري بشكل متبادل مع email_payload.
email_payloadEmailPayloadحمولة البريد الإلكتروني.
campaignstringرمز الحملة لنسب هذه الرسالة إليه.
campaign_namestringاسم داخلي لهذه الرسالة، يظهر كعنوان للصف في Message History وفي تصديرها. لا علاقة له بـ campaign أعلاه. لا يقوم بتجميع الرسائل ولا يؤثر على التسليم. الحد الأقصى 255 حرفًا، ويتم اقتطاعه. احذفه أو اتركه فارغًا ليأتي عنوان الصف من محتوى الحمولة نفسها.
frequency_cappingFrequencyCappingحدود التكرار لكل مستخدم.
send_rateSendRateالتحكم في معدل الإرسال.
silent_hoursSilentHoursاختياري. يرسل الرسالة دون مراعاة ساعات الصمت الخاصة بالتطبيق.
message_typeMessageTypeMESSAGE_TYPE_MARKETING (افتراضي) أو MESSAGE_TYPE_TRANSACTIONAL. يتحكم في تصفية مجموعة التحكم.
dynamic_content_placeholdersmap<string, string>يستبدل العناصر النائبة في المحتوى.
meta_dataobjectبيانات وصفية حرة الشكل يتم تمريرها إلى التحليلات النهائية.
use_latest_user_deviceboolعندما يكون true، يتم تسليم الرسالة إلى أحدث جهاز نشط لكل مستخدم (الجهاز الذي لديه أحدث “آخر فتح للتطبيق”) بدلاً من كل جهاز تطابقه الشريحة. يقتصر النطاق على platforms: يتم النظر فقط في الأجهزة على تلك المنصات، وإذا لم يكن لدى أي منها بيانات “آخر فتح للتطبيق”، يتم استخدام أول جهاز مطابق بدلاً من إسقاط الإرسال. الافتراضي هو false (إرسال إلى كل جهاز).
geo_zoneGeoZoneاختياري. يضيّق الجمهور ليقتصر على الأجهزة التي يقع آخر موقع مسجَّل لها داخل دائرة تحددها في هذا الطلب. يُدمج مع code أو expression أو filter_expression بعامل AND: يجب أن يطابق الجهاز الشريحة وأن يقع داخل الدائرة. تُتخطّى الأجهزة التي ليس لها موقع مسجَّل. غير متاح في NotifyTransactional.
control_groupstringرمز أو اسم المجموعة الضابطة الخاصة بهذا الإرسال والتي تُطبَّق على هذه الرسالة. لا يحدّ من المجموعات الضابطة المطبقة: فكل مجموعة ضابطة مفعّلة في التطبيق تستثني المستخدمين من الإرساليات التسويقية سواء تم ضبط هذا الحقل أم لا. يتعارض مع holdout_percentage.
holdout_percentageuint32يسحب هذه النسبة من الشريحة، من 1 إلى 20، إلى مجموعة ضابطة تقتصر على هذا الإرسال، إضافةً إلى المجموعات الضابطة المفعّلة في التطبيق، لقياس تأثير حملة واحدة دون استنزاف المجموعات المشتركة. القيمة 0 (الافتراضية) تُبقيه معطّلًا. يتعارض مع control_group.

تُستبعد الأجهزة المسحوبة إلى مجموعة الاستبعاد من التسليم بالطريقة نفسها التي تستبعدها بها المجموعات الضابطة للتطبيق. لا يُرسَل إليها شيء، ويسجّل سجل التتبع هذا الاستبعاد على أنه Device is in control group. وعندما تكون قيمة message_type هي MESSAGE_TYPE_TRANSACTIONAL يُتخطّى هذا الاستبعاد بالكامل، تمامًا كما في المجموعات الضابطة للتطبيق.

يؤدي ضبط holdout_percentage مع control_group، أو ضبط holdout_percentage بقيمة أكبر من 20، إلى إرجاع 400:

Invalid holdout_percentage
{
"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 to
Terminal window
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

Anchor link to

يرسل إلى قائمة صريحة من المستلمين.

الحقلالنوعالوصف
scheduleScheduleمطلوب.
applicationstringرمز التطبيق.
platformsarray of Platformالمنصات التي تستهدفها الرسالة.
test_devicesboolإذا كان true، يتم الإرسال إلى الأجهزة الاختبارية للتطبيق فقط.
hwids{ "list": [string, ...] }إرسال إلى هذه hwids فقط.
users{ "list": [string, ...] }إرسال إلى هذه معرفات المستخدمين (user IDs) فقط.
push_tokens{ "list": [string, ...] }إرسال إلى هذه رموز الإشعارات الفورية (push tokens) فقط.
payloadPayloadحمولة Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber / Facebook Messenger.
email_payloadEmailPayloadحمولة البريد الإلكتروني.
return_unknown_identifiersboolعندما يكون true، تسرد unknown_identifiers في الاستجابة المعرفات التي لم يتم العثور عليها.
registration_typeRegistrationTypeما يجب فعله مع hwids غير المسجلة في Pushwoosh بعد. القيمة الافتراضية هي REGISTRATION_TYPE_DEFAULT، التي تتخطاها. اضبط REGISTRATION_TYPE_FORCE لتسجيل عناوين البريد الإلكتروني أو أرقام الهواتف الجديدة والإرسال إليها في الطلب نفسه.
use_latest_user_deviceboolينطبق فقط عند استهداف 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:whatsapp:+14155552671
Kakaoرقم الهاتف مع البادئة kakao:kakao:+821012345678
Viberرقم الهاتف مع البادئة viber:. تضيف Pushwoosh البادئة إذا كانت مفقودةviber:+14155552671
LINEمعرف مستخدم LINEU4af4980629a1b2c3d4e5f6a7b8c9d0e1

احتفظ بالبادئتين 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 to
Terminal window
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": ["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 to
Terminal window
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
}
}'

الاستجابة

Anchor link to
{
"result": {
"message_code": "XXXXX-XXXXX-XXXXX",
"unknown_identifiers": []
}
}
الحقلالنوعالوصف
message_codestringرمز رسالة فريد. استخدمه مع /getMessageDetails ونقاط نهاية إحصائيات الرسائل.
unknown_identifiersarray 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 to
{
"at": "2026-05-01T12:00:00Z",
"follow_user_timezone": true,
"past_timezones_behaviour": "PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY"
}
الحقلالنوعالوصف
attimestampوقت الإرسال المطلق (RFC 3339). بحد أقصى 30 يومًا في المستقبل. عندما يكون follow_user_timezone غير مضبوط أو false، تُستبدل قيمة at الماضية بوقت استلام الطلب، فتُرسل الرسالة على الفور إلى الجميع. مع follow_user_timezone: true، تُبقى قيمة at الماضية كما هي. راجع التنبيه أدناه.
afterdurationبديل لـ at. إرسال بعد هذا الإزاحة من “الآن” (على سبيل المثال "3600s"). بحد أقصى 30 يومًا.
follow_user_timezoneboolعندما يكون true، يتلقى كل جهاز الرسالة في at في منطقته الزمنية المحلية.
past_timezones_behaviourenumPAST_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_sendtimestampاختياري. لعمليات الإرسال إلى شريحة فقط. يتلقى كل جهاز الرسالة في أفضل ساعة خاصة به خلال 24 ساعة من هذا الوقت. أما الأجهزة التي ليست لها أفضل ساعة فتتلقاها في تاريخ ووقت at / after حسب منطقتها الزمنية المحلية. راجع أفضل وقت للإرسال.

أفضل وقت للإرسال

Anchor link to

best_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.
BestTimeToSendTooEarlybest_time_to_send قبل الساعة الكاملة التالية.
BestTimeToSendTooFarInFuturebest_time_to_send يتجاوز 30 يومًا في المستقبل.
SendDateAfterBestTimeToSendat / after بعد best_time_to_send مضافًا إليه 24 ساعة.
BestTimeToSendNotAllowedتم ضبط best_time_to_send في إرسال transactional.
BestTimeToSendWithSendNowيُحسب at / after على أنه “الآن” (at في الماضي أو after صفري).

دائرة لمرة واحدة لـ geo_zone، تُعرَّف في الطلب نفسه. وهي ليست منطقة جغرافية محفوظة: لا تشارك الحملات الجغرافية ولا Geozones API، ولا يُخزَّن أي شيء في التطبيق.

{ "lat": 40.7128, "lng": -74.006, "range": 500 }
الحقلالنوعالوصف
latdoubleخط عرض مركز الدائرة، بالدرجات. مطلوب.
lngdoubleخط طول مركز الدائرة، بالدرجات. مطلوب.
rangedoubleنصف قطر الدائرة بالأمتار. مطلوب.

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): تجنب ناعم للمستخدمين الذين وصلوا بالفعل إلى الحد الأقصى (لا يزالون يُحتسبون ضمن التحليلات).
{ "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 to

IOS, 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 to
  • REGISTRATION_TYPE_DEFAULT: يتخطى المعرفات غير المسجلة في Pushwoosh. القيمة الافتراضية.
  • REGISTRATION_TYPE_NONE: يرسل إلى كل hwid مدرج دون حفظ جهاز له.
  • REGISTRATION_TYPE_FORCE: يسجّل كل hwid غير معروف كجهاز على القناة المستهدفة، ثم يرسل إليه. ينطبق على البريد الإلكتروني و SMS و WhatsApp و LINE و Viber و Kakao.

تعداد نوع الرسالة (MessageType enum)

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

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

Anchor link to