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

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

الحمولة (Payload)

preset (string): رمز الإعداد المسبق للإشعارات (تنسيق XXXXX-XXXXX) لتطبيقه على هذه الرسالة.
sms_preset (string): رمز (تنسيق XXXXX-XXXXX) لـ إعداد مسبق للرسائل القصيرة محفوظ. يتم تحليل نصه لكل لغة في sms.body الخاص بكل لغة. أي sms.body مضمن للغة معينة يتجاوز الإعداد المسبق لتلك اللغة. يجب أن ينتمي الإعداد المسبق إلى نفس التطبيق الذي تنتمي إليه الرسالة.
content (LocalizedContent): محتوى الرسالة. متعارض مع silent.
silent (bool): إرسال إشعار صامت (بيانات فقط) إلى جميع المنصات. متعارض مع content. لجعل بعض المنصات فقط صامتة، قم بتعيين silent داخل content لـ iOS أو Android بدلاً من ذلك.
custom_data (object): JSON حر الشكل يتم تمريره إلى SDK العميل كمعامل u. قد تفقد الأعداد الصحيحة الكبيرة جدًا دقتها، راجع الأعداد الصحيحة الكبيرة في البيانات المخصصة.
custom_data_raw (string): سلسلة نصية تحتوي على كائن JSON، يتم تمريرها إلى SDK العميل كمعامل u. تحتفظ الأرقام الموجودة فيها بقيمتها الدقيقة. متعارض مع custom_data غير الفارغ. تُرجع القيمة غير الصالحة 400.
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" } }
  }
}

الأعداد الصحيحة الكبيرة في البيانات المخصصة

تفقد الأعداد الصحيحة الأكبر من 9007199254740992 دقتها في custom_data. استخدم custom_data_raw للحفاظ عليها دقيقة.

custom_data هو google.protobuf.Struct (كائن عام شبيه بـ JSON). يخزّن كل رقم كـ double، وهو رقم فاصلة عائمة بحجم 64 بت يكون دقيقًا فقط للأعداد الصحيحة حتى 9007199254740992. يتم تقريب الأعداد الصحيحة الأكبر: يصل 5190090000030465245 إلى الجهاز كـ 5190090000030465000. لا تتأثر السلاسل النصية.

للحفاظ على دقة هذه الأعداد الصحيحة، أرسل في custom_data_raw سلسلة نصية تحتوي على كائن JSON:

{ "payload": { "silent": true, "custom_data_raw": "{\"pushUID\": 5190090000030465245}" } }

قواعد custom_data_raw:

يجب أن تحتوي السلسلة النصية على كائن JSON. تُرجع المصفوفة أو السلسلة النصية أو null أو JSON غير الصالح الخطأ 400 (INVALID_ARGUMENT) مع انتهاك للحقل payload.custom_data_raw.
إذا كان custom_data يحتوي على أي مفاتيح وتم تعيين custom_data_raw، يُرجع الطلب 400. يتم تجاهل كائن custom_data الفارغ.
مثل custom_data، يحل محل البيانات المخصصة المحفوظة في preset الإشعار.
يتم تحويل الكائن مرة أخرى إلى نص JSON قبل التسليم. لا يتم الحفاظ على ترتيب المفاتيح وتتم إزالة المسافات البيضاء. تحتفظ الأرقام بقيمتها الدقيقة، لكن النص الأصلي لا يُحفظ بايتًا ببايت.
في /messaging/v2/notify/batch، يؤدي custom_data_raw غير الصالح إلى فشل عنصره فقط. يتم إرسال العناصر الأخرى.

كيف ترسل الطلب:

REST: لا يلزم أي تغيير لـ /messaging/v2/notify و /messaging/v2/notify/batch. إذا احتوى custom_data على عدد صحيح لا يستطيع double تمثيله بدقة، تحتفظ به API تلقائيًا دون فقدان. لا يزال بإمكانك تعيين custom_data_raw بشكل صريح.
gRPC: يبني العميل Struct بنفسه، لذا تُفقد الدقة قبل إرسال الطلب. املأ custom_data_raw بدلاً من custom_data.

أين يتم تسليم الإشعار:

Android: يمرر SDK المعامل u إلى التطبيق كسلسلة نصية عبر PushMessage.getCustomData()، لذا يتم الحفاظ على كل رقم.
Web push: يحلل Web SDK المعامل u باستخدام JSON.parse، وكل رقم في JavaScript هو double. يتم تقريب الأعداد الصحيحة الكبيرة في المتصفح بغض النظر عن API، لذا مرّرها كسلاسل نصية.
Windows: يتلقى الإشعار المنبثق (toast) بيانات u نفسها التي تتلقاها المنصات الأخرى، وتصل الأعداد الصحيحة المرسلة عبر custom_data_raw دقيقة.

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

الأزرار

يمكن لكل إدخال لغة أن يتضمن أيضًا buttons، وهي ما يصل إلى 3 أزرار إجراءات تظهر أسفل الإشعار على iOS وAndroid وHuawei. تتجاهلها المنصات الأخرى. تتطلب الأزرار iOS SDK 7.2.10 أو أحدث مع Notification Service Extension، وAndroid SDK 6.17.0 أو أحدث.

يحتوي كل PushButton على هذه الحقول:

id (string): معرّف الزر الذي يتلقاه تطبيقك عند النقر. حتى 64 حرفًا، دون مسافات، وفريد داخل الإشعار. مطلوب لـ ACTION_OPEN وACTION_CUSTOM. إذا حذفته للإجراءات الأخرى، يعيّن Pushwoosh القيم btn_1 وbtn_2 وهكذا.
label (string): نص الزر، من 1 إلى 64 حرفًا.
action (enum): يفتح ACTION_OPEN التطبيق، ويفتح ACTION_URL الرابط url، ويفتح ACTION_DEEPLINK رابطًا عميقًا، ويمرّر ACTION_CUSTOM المعرّف id إلى تطبيقك ليتولى معالجته.
url (string): عنوان http أو https مطلق لـ ACTION_URL، أو رابط عميق مع مخطط لـ ACTION_DEEPLINK.
platform_urls (map): رابط عميق لكل منصة لـ ACTION_DEEPLINK، مفهرس برمز المنصة: 1 iOS، 3 Android، 17 Huawei.
style (enum): STYLE_DEFAULT أو STYLE_DESTRUCTIVE. يعرض النمط التدميري الزر باللون الأحمر على iOS.

{
  "localized_content": {
    "default": {
      "ios": { "title": "Your order is on its way", "body": "Arrives tomorrow" },
      "android": { "title": "Your order is on its way", "body": "Arrives tomorrow" },
      "buttons": [
        { "id": "track", "label": "Track order", "action": "ACTION_DEEPLINK", "url": "myapp://orders/42" },
        { "id": "cancel", "label": "Cancel order", "action": "ACTION_CUSTOM", "style": "STYLE_DESTRUCTIVE" }
      ]
    }
  }
}

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

هذه الحقول مشتركة بين كتل 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 تحل محل بعضها البعض على الجهاز.
silent (bool): إرسال إشعار iOS كإشعار صامت (بيانات فقط)، بينما تتلقى المنصات الأخرى في نفس الرسالة إشعارًا عاديًا. يتم تعيينه داخل content، لذا يعمل معه. لجعل جميع المنصات صامتة، استخدم silent ذي المستوى الأعلى بدلاً من ذلك، والذي يحل محل content. قم بتعيينه في أي لغة لتطبيقه على جميع اللغات.

{
  "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 تحل محل بعضها البعض أثناء عدم اتصال الجهاز بالإنترنت.
silent (bool): إرسال الإشعار إلى هذه المنصة كإشعار صامت (بيانات فقط)، بينما تتلقى المنصات الأخرى في نفس الرسالة إشعارًا عاديًا. يتم تعيينه داخل content، لذا يعمل معه. لجعل جميع المنصات صامتة، استخدم silent ذي المستوى الأعلى بدلاً من ذلك، والذي يحل محل content. قم بتعيينه في أي لغة لتطبيقه على جميع اللغات. تقبل كتلة baidu_android أيضًا silent، بنفس السلوك.

{
  "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، ما لم يتم تعيين image. مطلوب مع زر أو كاروسيل.
image (string): عنوان URL عام للصورة. يتم تجاهله عند تعيين template_id.
button_caption (string): نص الزر، حتى 30 حرفًا. يُعيَّن مع button_action. يتطلب body. يتم تجاهله عند تعيين template_id.
button_action (string): رابط الزر: عنوان URL يبدأ بـ http:// أو https://، أو رابط عميق viber://، أو رمز Omni مثل {lp-100} (عنصر نائب لرابط تتبع يحلّه Omni Messaging وقت الإرسال). يُعيَّن مع button_caption.
carousel (object): من 2 إلى 5 بطاقات قابلة للتمرير تظهر أسفل body. لا يمكن دمجه مع image أو button_caption أو button_action أو 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 أو image أو 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
  }
}

الكاروسيل

يحتوي carousel.items على 2 إلى 5 بطاقات. لإعداد كاروسيل في رحلة بدلًا من ذلك، راجع إرسال كاروسيل. تحتوي كل بطاقة على هذه الحقول:

title (string): عنوان البطاقة، من 2 إلى 38 حرفًا. مطلوب.
image (string): عنوان URL عام للصورة يبدأ بـ http:// أو https://. مطلوب.
primary_button (object): الزر الرئيسي. مطلوب.
secondary_button (object): الزر الثاني. اختياري.

لكل زر حقلان، وكلاهما مطلوب عند وجود الزر:

caption (string): نص الزر، حتى 10 أحرف لـ primary_button وحتى 12 لـ secondary_button.
action (string): رابط الزر: عنوان URL مع مخطط (http://، https://، viber://) أو رمز Omni مثل {lp-100}، وهي القيم نفسها المستخدمة في button_action.

يُرفض الطلب الذي يخالف أيًا من هذه القواعد مع INVALID_ARGUMENT. تحدد تفاصيل google.rpc.BadRequest الحقل، على سبيل المثال viber.carousel.items[0].title.

مثال:

{
  "viber": {
    "body": "New arrivals are in. Swipe to see them.",
    "carousel": {
      "items": [
        {
          "title": "Running shoes",
          "image": "https://example.com/img/shoes.jpg",
          "primary_button": { "caption": "Buy now", "action": "https://example.com/shoes" },
          "secondary_button": { "caption": "Details", "action": "{lp-100}" }
        },
        {
          "title": "Sports backpack",
          "image": "https://example.com/img/backpack.jpg",
          "primary_button": { "caption": "Buy now", "action": "https://example.com/backpack" }
        }
      ]
    }
  }
}

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): رسالة نصية عادية. مطلوب ما لم تقم بتعيين message.
message (string): كائن message كامل من Meta Send API كسلسلة JSON، يتضمن نصاً أو مرفقات أو قوالب أو ردوداً سريعة. عند تعيينه، ترسله Pushwoosh بدلاً من body.
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
  }
}

RCS

تؤدي إضافة rcs إلى كتلة sms إلى إرسال قالب محتوى Twilio عبر RCS (Rich Communication Services) بدلاً من body. تسلّم Twilio القالب كرسالة RCS، وكبديل احتياطي ترسل رسالة SMS مبنية من نوع twilio/text في القالب، وليس من body. القالب الذي لا يحتوي على نوع twilio/text يصل فقط إلى الهواتف التي تدعم RCS.

rcs.content_sid (string): SID قالب محتوى Twilio، وهو HX متبوعًا بـ 32 حرفًا سداسيًا عشريًا. احصل عليه من ListRcsTemplates أو من Twilio Console.
rcs.content_variables (string): كائن JSON لمتغيرات القالب، مُسلسل كسلسلة نصية، على سبيل المثال "{\"1\": \"{FirstName|CapitalizeFirst|there}\"}". تدعم القيم العلامات وتخصيص Liquid. المتغير الذي تحذفه يأخذ القيمة الافتراضية للقالب.

لا يزال body مطلوبًا في كتلة sms تحتوي على rcs.

يُرفض الطلب ما لم يرسل التطبيق الرسائل القصيرة عبر Twilio باستخدام Account SID وAuth token وMessaging Service SID الخاصة به، والمعيّنة في إعدادات منصة SMS. لا يمكن للتطبيق الذي يستخدم بيانات اعتماد Twilio المقدمة من Pushwoosh إرسال RCS.

يمكن أن يحمل الإعداد المسبق للرسائل القصيرة قالبًا لكل لغة. عند وجود sms_preset في الحمولة، يُستخدم قالب الإعداد المسبق لكل لغة لا يتضمن فيها الطلب rcs.content_sid خاصًا به.

{
  "sms": {
    "body": "Your order has shipped.",
    "rcs": {
      "content_sid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
      "content_variables": "{\"1\": \"{FirstName|CapitalizeFirst|there}\", \"2\": \"A-1042\"}"
    }
  }
}

عرض قائمة قوالب RCS

يُرجع ListRcsTemplates قوالب محتوى Twilio الخاصة بالتطبيق والتي يمكن إرسالها عبر RCS، ويقرأها باستخدام بيانات اعتماد Twilio الخاصة بالتطبيق.

GET https://rpc-api.svc-nue.pushwoosh.com/api/sms_presets:rcs_templates?application=XXXXX-XXXXX
Authorization: Api YOUR_API_TOKEN

application (string, query): رمز التطبيق، بتنسيق XXXXX-XXXXX.

تحتوي الاستجابة على مصفوفة templates. تُدرج فقط القوالب التي تحتوي على نوع محتوى RCS واحد على الأقل: twilio/card أو twilio/carousel أو twilio/quick-reply أو twilio/call-to-action أو twilio/media.

الحقل	النوع	الوصف
`content_sid`	string	SID القالب، وهو القيمة لـ `rcs.content_sid`.
`friendly_name`	string	اسم القالب في Twilio.
`language`	string	رمز لغة القالب.
`types`	array of string	أنواع محتوى Twilio التي يحددها القالب، على سبيل المثال `twilio/card` و `twilio/text`.
`variables`	object	متغيرات القالب مع قيمها الافتراضية.
`has_sms_fallback`	boolean	`true` عندما يحتوي القالب على نوع `twilio/text`، وهو رسالة SMS التي يتلقاها الهاتف الذي لا يدعم RCS.

{
  "templates": [
    {
      "content_sid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
      "friendly_name": "order_shipped_card",
      "language": "en",
      "types": ["twilio/card", "twilio/text"],
      "variables": { "1": "there", "2": "your order" },
      "has_sms_fallback": true
    }
  ]
}

يُرجع ListRcsTemplates الأخطاء التالية:

حالة HTTP	السبب
`400 Bad Request`	لا يملك التطبيق Account SID وAuth token خاصين به في Twilio (`FailedPrecondition`).
`401 Unauthorized`	رفضت Twilio بيانات اعتماد التطبيق (`Unauthenticated`).
`503 Service Unavailable`	أرجعت Twilio Content API خطأً آخر (`Unavailable`).

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): وقت إزالة الإدخال من صندوق الوارد.
expires_in (duration، مثلاً "604800s"): مدة بقاء الإدخال في صندوق الوارد، محسوبة من تاريخ الإرسال (send_date المجدول، أو لحظة الطلب عند الإرسال الفوري). يجب أن تكون قيمة موجبة. يتم تجاهلها عند تعيين expiration_date.

لتعيين مدة صلاحية نسبية بدلاً من تاريخ ثابت، أرسل expires_in وحده:

{
  "image_url": "https://cdn.example.com/inbox.png",
  "expires_in": "604800s"
}

إذا كان لحسابك حد أقصى لمدة بقاء الإدخالات في صندوق الوارد، يتم رفض expiration_date أو expires_in الذي يتجاوزه.

تعداد 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)