مرجع Payload

مرجع لرسالة Payload المستخدمة بواسطة Notify عند الإرسال عبر أي قناة غير البريد الإلكتروني (push, SMS, Telegram, Kakao, LINE, WhatsApp).

Payload

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

المحتوى المترجم (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
`baidu_android`	إشعار Baidu Android
`mac_os`	إشعار macOS
`amazon`	إشعار Amazon (ADM)
`safari`	إشعار ويب Safari
`chrome`	إشعار ويب Chrome
`firefox`	إشعار ويب Firefox
`ie`	إشعار ويب Internet Explorer
`windows`	إشعار Windows (tile / toast / badge)
`telegram`	رسالة Telegram
`kakao`	رسالة Kakao
`line`	رسالة LINE
`whatsapp`	رسالة WhatsApp

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

تتم مشاركة هذه الحقول بواسطة كتل ios, android, huawei_android, baidu_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): إدخال صندوق الرسائل (Message Inbox).

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 تحل محل بعضها البعض على الجهاز.

Android (`android`, `huawei_android`, `baidu_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 تحل محل بعضها البعض أثناء عدم اتصال الجهاز بالإنترنت.

macOS (`mac_os`)

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

Amazon (`amazon`)

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

Safari (`safari`)

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

Chrome (`chrome`)

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

Firefox (`firefox`)

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

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 لقالب جانب الروبوت (bot).

Kakao (`kakao`)

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

LINE (`line`)

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

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

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.

SMS

تستخدم الرسائل القصيرة (SMS) تدفق الرسائل العام. كتلة منصة sms محجوزة. قدم النص من خلال حقل body المشترك في أي كتلة منصة مملوءة. يأتي معرف المرسل وخيارات المزود الأخرى من تكوين SMS للتطبيق. راجع تكوين SMS.

OpenAction

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

واحد فقط مما يلي:

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

RichMedia

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

Link

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

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

Inbox

يضبط كيفية ظهور الرسالة في صندوق الرسائل (Message Inbox).

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

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

NotificationPriority enum

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

PRIORITY_UNSPECIFIED
PRIORITY_MIN
PRIORITY_LOW
PRIORITY_DEFAULT
PRIORITY_HIGH
PRIORITY_MAX

مثال: إرسال إشعار (push) إلى شريحة (segment)

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"
    }
  }'

مثال: إشعار (push) للمعاملات حسب معرفات المستخدم (user IDs)

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)

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

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

iOS (ios)

Android (android, huawei_android, baidu_android)

macOS (mac_os)

Amazon (amazon)

Safari (safari)

Chrome (chrome)

Firefox (firefox)

Windows (windows)

Telegram (telegram)

Kakao (kakao)

LINE (line)

WhatsApp (whatsapp)

SMS