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

مرجع لرسالة Payload المستخدمة بواسطة Notify عند الإرسال عبر أي قناة غير البريد الإلكتروني (الإشعارات، الرسائل القصيرة، تيليجرام، كاكاو، لاين، فايبر، واتساب، فيسبوك ماسنجر).

الحمولة (Payload)

preset (string): رمز الإعداد المسبق للإشعارات (تنسيق XXXXX-XXXXX) لتطبيقه على هذه الرسالة.
sms_preset (string): رمز (تنسيق XXXXX-XXXXX) لـ إعداد مسبق للرسائل القصيرة محفوظ. يتم تحليل نصه لكل لغة في sms.body الخاص بكل لغة. أي sms.body مضمن للغة معينة يتجاوز الإعداد المسبق لتلك اللغة. يجب أن ينتمي الإعداد المسبق إلى نفس التطبيق الذي تنتمي إليه الرسالة.
content (LocalizedContent): محتوى الرسالة. متعارض مع silent.
silent (bool): إرسال إشعار صامت (بيانات فقط). متعارض مع content.
custom_data (object): JSON حر الشكل يتم تمريره إلى SDK العميل كمعامل u.
open_action (OpenAction): الإجراء الذي يتم تشغيله عندما يفتح المستخدم الإشعار.
open_actions (map<Platform, OpenAction>): تجاوز open_action لكل منصة. المفتاح هو قيمة رقمية لتعداد Platform.
voip_push (bool): إشعار VoIP لنظام iOS.

{
  "payload": {
    "preset": "XXXXX-XXXXX",
    "content": { "localized_content": { "default": { "ios": { "title": "Hello", "body": "Tap to view" } } } },
    "custom_data": { "order_id": "42" },
    "open_action": { "link": { "url": "https://example.com/promo" } }
  }
}

LocalizedContent

يربط رمز اللغة بمحتوى كل منصة. المفاتيح هي رموز من حرفين ISO 639-1 (على سبيل المثال، "en", "es") بالإضافة إلى المفتاح الخاص "default" لترجمة شاملة. الاستثناءات من ISO 639-1 هي "zh-Hant" و "zh-Hans" للصينية التقليدية والمبسطة.

{
  "localized_content": {
    "default": {
      "ios":     { "title": "Hello", "body": "Tap to view" },
      "android": { "title": "Hello", "body": "Tap to view" }
    },
    "es": {
      "ios":     { "title": "Hola",  "body": "Toca para ver" },
      "android": { "title": "Hola",  "body": "Toca para ver" }
    }
  }
}

اختيار اللغة للجهاز

يتم اختيار المحتوى الذي يتم تسليمه إلى الجهاز بهذا الترتيب:

تطابق تام مع لغة الجهاز.
المفتاح "default".
المفتاح "en".
أي لغة أخرى موجودة في الخريطة.

قم بتوفير واحد على الأقل من "default" أو "en" حتى يكون لكل جهاز بديل محدد. إذا كنت لا تتوقع متغيرات لكل لغة، أرسل "default" فقط.

كل إدخال لغة هو كائن Content مع كتل اختيارية لكل منصة. املأ فقط المنصات التي تستهدفها.

كتلة المنصة	القناة
`ios`	إشعار iOS
`android`	إشعار Android (FCM)
`huawei_android`	إشعار Huawei Android
`mac_os`	إشعار macOS
`amazon`	إشعار Amazon (ADM)
`safari`	إشعار ويب Safari
`chrome`	إشعار ويب Chrome
`firefox`	إشعار ويب Firefox
`ie`	إشعار ويب Internet Explorer
`windows`	إشعار Windows (tile / toast / badge)
`telegram`	رسالة تيليجرام
`kakao`	رسالة كاكاو
`line`	رسالة لاين
`viber`	رسالة فايبر
`whatsapp`	رسالة واتساب
`fb_messenger`	رسالة فيسبوك ماسنجر
`sms`	رسالة SMS

حقول الإشعارات الشائعة

هذه الحقول مشتركة بين كتل ios, android, huawei_android, mac_os, amazon, safari, chrome, و firefox (يختلف الدعم. يتم تجاهل الحقول غير المستخدمة من قبل المنصة المعنية).

title (string): عنوان الإشعار.
body (string): نص الإشعار.
time_to_live (duration, e.g. "3600s"): المدة التي يجب أن يحتفظ بها خادم الإشعارات بالإشعار لجهاز غير متصل بالإنترنت.
sound (string): اسم ملف الصوت.
sound_enabled (bool): تمكين أو كبت الصوت.
badges (string): عدد الشارات (iOS) أو ما يعادله.
root_params (object): تجاوزات حمولة خام خاصة بالمنصة.
inbox (Inbox): إدخال صندوق الوارد للرسائل.

{
  "android": {
    "title": "Hello",
    "body": "Tap to view",
    "time_to_live": "3600s",
    "sound": "default",
    "sound_enabled": true,
    "badges": "+1"
  }
}

iOS (`ios`)

subtitle (string): عنوان فرعي لإشعار iOS.
is_critical (bool): تنبيه حرج (يتطلب استحقاقًا).
attachment (string): عنوان URL لمرفق وسائط.
thread_id (string): معرف السلسلة للإشعارات المجمعة.
trim_content (bool): قص المحتوى ليلائم.
category_id (string): معرف UNNotificationCategory للإجراءات التفاعلية.
interruption_level (string): passive, active, time-sensitive, أو critical.
collapse_id (string): معرف الانهيار لـ APNs. الإشعارات التي لها نفس collapse_id تحل محل بعضها البعض على الجهاز.

{
  "ios": {
    "title": "Hello",
    "body": "Tap to view",
    "subtitle": "New update",
    "attachment": "https://cdn.example.com/image.png",
    "interruption_level": "active",
    "thread_id": "promo"
  }
}

Android (`android`, `huawei_android`)

icon (string): أيقونة الإشعار الصغيرة.
banner (string): عنوان URL للصورة الكبيرة.
delivery_priority (NORMAL | HIGH): أولوية تسليم FCM.
vibration (bool): اهتزاز عند الاستلام.
led_color (string, hex): لون LED للإشعار.
icon_background_color (string, hex): لون خلفية الأيقونة.
show_on_lockscreen (bool): إظهار على شاشة القفل.
custom_icon (string): عنوان URL لأيقونة مخصصة.
priority (NotificationPriority): الأولوية في درج الإشعارات.
group_id (string): مفتاح مجموعة الإشعارات.
collapse_key (string): مفتاح الانهيار لـ FCM. الإشعارات التي لها نفس collapse_key تحل محل بعضها البعض أثناء عدم اتصال الجهاز بالإنترنت.

{
  "android": {
    "title": "Hello",
    "body": "Tap to view",
    "icon": "ic_notification",
    "banner": "https://cdn.example.com/banner.png",
    "led_color": "#FF0000",
    "priority": "PRIORITY_HIGH",
    "delivery_priority": "HIGH"
  }
}

macOS (`mac_os`)

يستخدم حقول الإشعارات الشائعة بالإضافة إلى subtitle و action (عنوان URL الذي يتم فتحه عندما ينقر المستخدم على الإشعار).

{
  "mac_os": {
    "title": "Hello",
    "body": "Tap to view",
    "subtitle": "New update",
    "action": "https://example.com/promo"
  }
}

Amazon (`amazon`)

يستخدم حقول الإشعارات الشائعة بالإضافة إلى custom_icon و priority (NotificationPriority).

{
  "amazon": {
    "title": "Hello",
    "body": "Tap to view",
    "custom_icon": "https://cdn.example.com/icon.png",
    "priority": "PRIORITY_HIGH"
  }
}

Safari (`safari`)

action (string): عنوان URL الذي يتم فتحه عندما ينقر المستخدم على الإشعار.
url_arguments (array of string): وسائط URL لـ Safari يتم استبدالها في قالب URL للإشعارات على الويب.

{
  "safari": {
    "title": "Hello",
    "body": "Tap to view",
    "action": "https://example.com/promo",
    "url_arguments": ["promo", "2026"]
  }
}

Chrome (`chrome`)

icon, image (string): عناوين URL للأيقونة الصغيرة والصورة الكبيرة.
duration (duration): مؤقت الإغلاق التلقائي.
button_text1 / button_url1, button_text2 / button_url2: ما يصل إلى زرين للإجراء.

{
  "chrome": {
    "title": "Hello",
    "body": "Tap to view",
    "icon": "https://cdn.example.com/icon.png",
    "image": "https://cdn.example.com/banner.png",
    "duration": "20s",
    "button_text1": "Open",
    "button_url1": "https://example.com/promo"
  }
}

Firefox (`firefox`)

يستخدم فقط title, body, icon, root_params, و inbox.

{
  "firefox": {
    "title": "Hello",
    "body": "Tap to view",
    "icon": "https://cdn.example.com/icon.png"
  }
}

Windows (`windows`)

يستخدم Windows شكلاً مختلفًا:

{
  "windows": {
    "type": "TOAST",
    "template": { "title": "Hello", "body": "Tap to view" },
    "tag": "promo",
    "cache": true,
    "time_to_live": "3600s"
  }
}

type هو TILE, TOAST, أو BADGE.
template (منظم) أو raw ({ "content": "<raw xml>" }) — واحد فقط.

Telegram (`telegram`)

body (string): نص الرسالة.
content_variables (string): متغيرات بصيغة JSON كسلسلة نصية لقالب جانب الروبوت.

{
  "telegram": {
    "body": "Hello from Pushwoosh",
    "content_variables": "{\"name\":\"John\"}"
  }
}

Kakao (`kakao`)

content (string): محتوى الرسالة.
template (string): رمز القالب المعتمد.
content_variables (string): روابط متغيرات القالب بصيغة JSON كسلسلة نصية.

{
  "kakao": {
    "content": "Hello from Pushwoosh",
    "template": "welcome_v1",
    "content_variables": "{\"name\":\"John\"}"
  }
}

LINE (`line`)

content (string): نص عادي.
template (string): رمز قالب LINE تم تكوينه في لوحة تحكم Pushwoosh (يستخدم لإرسال رسائل صور أو دوارة أو مرنة). للمحتوى الغني، قم بتكوين القالب مسبقًا في لوحة التحكم وقم بالإشارة إليه هنا.

يجب تعيين واحد على الأقل من content أو template.

{
  "line": {
    "content": "Hello from Pushwoosh",
    "template": "promo_carousel"
  }
}

Viber (`viber`)

رسالة Viber هي إما نص حر أو قالب معاملات معتمد مسبقًا (Omni Messaging / MStat) تتم الإشارة إليه بواسطة المعرف واللغة.

body (string): رسالة نصية عادية. مطلوب عندما لا يتم تعيين template_id.
template_id (string): معرف قالب معاملات معتمد مسبقًا. عند تعيينه، يكون له الأسبقية على body.
template_lang (string): لغة القالب. مطلوب عند تعيين template_id.
template_params (map<string, string>): روابط مفتاح/قيمة يتم استبدالها في القالب، على سبيل المثال { "name": "John", "code": "123456" }.
all_devices (bool): false (افتراضي) يسلم إلى الجهاز الأساسي للمستخدم فقط؛ true يسلم إلى جميع أجهزة المستخدم.

يجب تعيين واحد على الأقل من body أو template_id. عند تعيين template_id، يكون template_lang مطلوبًا.

خاطب مستلمي Viber كـ hwids في شكل viber:<phone> (E.164)، على سبيل المثال viber:+1234567890.

نص عادي:

{
  "viber": {
    "body": "Hello from Pushwoosh"
  }
}

قالب معاملات:

{
  "viber": {
    "template_id": "e3dec4a0-c063-4b0f-96d5-cf9d629a7abe",
    "template_lang": "en",
    "template_params": {
      "name": "John",
      "code": "123456",
      "expires_in": "5 minutes"
    },
    "all_devices": false
  }
}

WhatsApp (`whatsapp`)

تمر رسائل WhatsApp عبر Meta وتخضع لقواعد المراسلة الخاصة بـ Meta. الانقسام الرئيسي هو بين النص الحر (يتم تسليمه فقط داخل نافذة خدمة العملاء التي تبلغ 24 ساعة والتي تفتحها رسالة واردة من المستخدم) والقوالب المعتمدة (مطلوبة لبدء المراسلة الصادرة ولأي رسالة خارج نافذة الـ 24 ساعة).

content (string): نص رسالة حر. يتم تسليمه بواسطة Meta فقط داخل نافذة الـ 24 ساعة.
content_id (string): اسم قالب Meta معتمد مسبقًا (على سبيل المثال، "hello_world"). مطلوب لبدء المراسلة الصادرة أو أي رسالة خارج نافذة الـ 24 ساعة.
language (string): لغة القالب التي يجب أن تتطابق تمامًا مع اللغة المعتمدة في Meta (على سبيل المثال، "en_US", "en_GB"). لا معنى له إلا مع content_id. هذا مستقل عن مفتاح LocalizedContent الخارجي. يختار المفتاح الخارجي المحتوى لجهاز، ويختار language لغة قالب Meta لذلك المحتوى.
content_variables (string): كائن JSON يربط العناصر النائبة في النص، على سبيل المثال "{\"1\":\"John\"}".
button_url_variables (string): كائن JSON يربط العناصر النائبة في عنوان URL للزر مفهرسة بواسطة فهرس الزر، على سبيل المثال "{\"0\":\"https://...\"}".
header_variables (string): كائن JSON يربط العناصر النائبة في الرأس مفهرسة حسب النوع، على سبيل المثال "{\"image\":\"https://...\"}".

يجب تعيين واحد على الأقل من content أو content_id.

{
  "whatsapp": {
    "content_id": "hello_world",
    "language": "en_US",
    "content_variables": "{\"1\":\"John\"}"
  }
}

Facebook Messenger (`fb_messenger`)

تمر رسائل Facebook Messenger عبر Meta وتخضع لقواعد المراسلة الخاصة بـ Meta: يتم تسليم المحتوى الحر فقط داخل نافذة خدمة العملاء التي تبلغ 24 ساعة والتي تفتحها رسالة واردة من المستخدم. خارج تلك النافذة، قم بتعيين message_tag إلى إحدى حالات الاستخدام المعتمدة من Meta، وإلا فإن Meta ترفض الإرسال.

body (string): رسالة نصية عادية. لا يدعم Facebook Messenger القوالب أو الأزرار، لذا هذا هو حقل المحتوى الوحيد.
message_tag (string): مطلوب خارج نافذة الـ 24 ساعة. واحد من CONFIRMED_EVENT_UPDATE, POST_PURCHASE_UPDATE, ACCOUNT_UPDATE, HUMAN_AGENT.

{
  "fb_messenger": {
    "body": "Hello from Pushwoosh",
    "message_tag": "ACCOUNT_UPDATE"
  }
}

لهذه القناة لا يوجد معرف جهاز منفصل: hwid، push_token، و user_id كلها تشير إلى نفس القيمة، وهي معرف نطاق الصفحة (PSID) الخاص بالمستلم في Meta. استهدف محادثة معينة بأي منها في NotifyTransactional.

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": ["FB_MESSENGER"],
      "hwids": { "list": ["<recipient-psid>"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "fb_messenger": { "body": "Hello from Pushwoosh" }
            }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" }
    }
  }'

SMS (`sms`)

للرسائل القصيرة كتلة منصة خاصة بها داخل Content لكل لغة، إلى جانب ios، android، وقنوات المراسلة الأخرى.

body (string): نص الرسالة القصيرة للغة. مطلوب عند وجود كتلة sms.

هناك طريقتان لتوفير النص:

مضمن — قم بتعيين sms.body لكل لغة في localized_content.
من إعداد مسبق — قم بتعيين sms_preset على مستوى الحمولة إلى رمز (تنسيق XXXXX-XXXXX) لـ إعداد مسبق للرسائل القصيرة محفوظ. يتم تحليل محتواه لكل لغة في sms.body لكل لغة يحددها الإعداد المسبق. أي sms.body مضمن للغة يتجاوز الإعداد المسبق لتلك اللغة، لذا يمكنك إعادة استخدام إعداد مسبق مع تعديل لغات فردية.

{
  "payload": {
    "sms_preset": "XXXXX-XXXXX",
    "content": {
      "localized_content": {
        "default": { "sms": { "body": "Your order has shipped." } },
        "es":      { "sms": { "body": "Tu pedido ha sido enviado." } }
      }
    }
  }
}

MMS

إضافة subject و file_urls إلى كتلة sms تحول الرسالة إلى MMS. فقط AbleMobile لديها نقطة نهاية MMS — يتجاهل مقدمو خدمات الرسائل القصيرة الآخرون كلا الحقلين ويسلمون نص body العادي فقط.

subject (string): موضوع MMS. يتطلب إدخالًا واحدًا على الأقل في file_urls — يتم رفض موضوع بدون مرفقات. ما يصل إلى 40 حرفًا ASCII، أو 13 حرفًا إذا كان الموضوع يحتوي على أحرف غير ASCII.
file_urls (array of string): ما يصل إلى 3 عناوين URL للمرفقات. يجب أن يكون كل منها عنوان URL https مطلق ينتهي بـ .jpg أو .gif — يتم رفض .jpeg و .png بواسطة التحقق، حتى لو كان ملف JPEG أو PNG حقيقيًا، لأن المزود لا يمكنه فك تشفيرها. يجب أن يكون كل ملف أيضًا 200 كيلوبايت أو أصغر؛ يرفض AbleMobile الإرسال بأكمله إذا كان أي مرفق أثقل.
message_at (int): فهرس في file_urls (يبدأ من 0) يتم عرض نص الرسالة القصيرة بعده.

يدعم subject و file_urls تخصيص Liquid، تمامًا مثل body.

{
  "sms": {
    "body": "Your order has shipped.",
    "subject": "Order update",
    "file_urls": [
      "https://cdn.example.com/shipping-label.jpg",
      "https://cdn.example.com/tracking-map.gif"
    ],
    "message_at": 1
  }
}

OpenAction

يحدد الإجراء الذي يتم تنفيذه عندما يفتح المستخدم الرسالة.

واحد فقط من:

rich_media (RichMedia): فتح صفحة وسائط غنية.
deep_link: فتح رابط عميق: { "code": "flow-code", "params": { "key": "value" } }.
link (Link): فتح عنوان URL.

{
  "open_action": {
    "deep_link": { "code": "flow-code", "params": { "promo": "summer" } }
  }
}

يدعم عنوان URL للرابط العميق وقيم params صيغة تخصيص Liquid — يتم تحليل التعبيرات قبل فتح الرابط العميق.

RichMedia

{ "code": "XXXXX-XXXXX" }        // بواسطة رمز الوسائط الغنية
{ "url":  "https://..." }        // بواسطة عنوان URL عن بعد

Link

{
  "url": "https://example.com/promo",
  "shortener": "BITLY"
}

shortener هو NONE (افتراضي) أو BITLY.

Inbox

يقوم بتكوين كيفية ظهور الرسالة في صندوق الوارد.

{
  "image_url": "https://cdn.example.com/inbox.png",
  "expiration_date": "2026-05-15T00:00:00Z"
}

image_url (string): الصورة المعروضة في إدخال صندوق الوارد.
expiration_date (timestamp): وقت إزالة الإدخال من صندوق الوارد.

تعداد NotificationPriority

يتحكم في أولوية الإشعار على الجهاز المستهدف، من PRIORITY_MIN (الأدنى) إلى PRIORITY_MAX (الأعلى).

PRIORITY_UNSPECIFIED
PRIORITY_MIN
PRIORITY_LOW
PRIORITY_DEFAULT
PRIORITY_HIGH
PRIORITY_MAX

مثال: إرسال إشعار إلى شريحة

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":     { "title": "Hello",   "body": "Hello, world!" },
              "android": { "title": "Hello",   "body": "Hello, world!" }
            },
            "es": {
              "ios":     { "title": "¡Hola!",  "body": "¡Hola, mundo!" },
              "android": { "title": "¡Hola!",  "body": "¡Hola, mundo!" }
            }
          }
        },
        "open_action": { "link": { "url": "https://example.com/promo" } }
      },
      "schedule":     { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_MARKETING"
    }
  }'

مثال: إشعار معاملات حسب معرفات المستخدم

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": ["customer-42"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "ios":     { "title": "Your order", "body": "Order #42 has shipped." },
              "android": { "title": "Your order", "body": "Order #42 has shipped." }
            }
          }
        },
        "custom_data": { "order_id": "42" }
      },
      "schedule":     { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL"
    }
  }'

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

الحمولة (Payload)

LocalizedContent

اختيار اللغة للجهاز

حقول الإشعارات الشائعة

iOS (ios)

Android (android, huawei_android)

macOS (mac_os)

Amazon (amazon)

Safari (safari)

Chrome (chrome)

Firefox (firefox)

Windows (windows)

Telegram (telegram)

Kakao (kakao)

LINE (line)

Viber (viber)

WhatsApp (whatsapp)

Facebook Messenger (fb_messenger)

SMS (sms)

MMS