# مرجع Payload

مرجع لرسالة `Payload` المستخدمة بواسطة [`Notify`](/ar/developer/api-reference/messaging-api-v2/notify/) عند الإرسال عبر أي قناة غير البريد الإلكتروني (push, SMS, Telegram, Kakao, LINE, Viber, WhatsApp).

<Aside type="note">
بالنسبة للبريد الإلكتروني، انظر [مرجع حمولة البريد الإلكتروني](/ar/developer/api-reference/messaging-api-v2/email-payload-reference/).
</Aside>

## الحمولة (Payload)

- `preset` (string): رمز [الإعداد المسبق للإشعارات الفورية (push preset)](/ar/product/content/push-presets/) (بالتنسيق `XXXXX-XXXXX`) لتطبيقه على هذه الرسالة.
- `sms_preset` (string): رمز (بالتنسيق `XXXXX-XXXXX`) لـ [إعداد مسبق لرسائل SMS](/ar/product/content/sms-presets/) محفوظ. يتم تحليل نصه لكل لغة محلية في [`sms.body`](#sms-sms) الخاص بكل لغة. أي `sms.body` مضمن للغة معينة يتجاوز الإعداد المسبق لتلك اللغة. يجب أن ينتمي الإعداد المسبق إلى نفس التطبيق الذي تنتمي إليه الرسالة.
- `content` ([`LocalizedContent`](#localizedcontent)): محتوى الرسالة. متعارض مع `silent`.
- `silent` (bool): إرسال إشعار فوري صامت (بيانات فقط). متعارض مع `content`.
- `custom_data` (object): كائن JSON حر الشكل يتم تمريره إلى SDK العميل كمعامل `u`.
- `open_action` ([`OpenAction`](#openaction)): الإجراء الذي يتم تشغيله عندما يفتح المستخدم الإشعار.
- `open_actions` (map&lt;Platform, `OpenAction`&gt;): تجاوز `open_action` لكل منصة. المفتاح هو قيمة رقمية لتعداد `Platform`.
- `voip_push` (bool): إشعار VoIP لنظام iOS.

```json
{
  "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](https://www.loc.gov/standards/iso639-2/php/code_list.php) (على سبيل المثال، `"en"`, `"es"`) بالإضافة إلى المفتاح الخاص `"default"` للترجمة الشاملة. الاستثناءات من ISO 639-1 هي `"zh-Hant"` و `"zh-Hans"` للصينية التقليدية والمبسطة.

```json
{
  "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" }
    }
  }
}
```

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

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

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

وفر على الأقل واحدًا من `"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 |
| `viber` | رسالة Viber |
| `whatsapp` | رسالة WhatsApp |
| `sms` | رسالة SMS |

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

هذه الحقول مشتركة بين كتل `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`](#inbox)): إدخال [صندوق وارد الرسائل](/ar/developer/guides/message-inbox/mobile-message-inbox/).

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

```json
{
  "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`, `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`](#notificationpriority-enum)): الأولوية في درج الإشعارات.
- `group_id` (string): مفتاح مجموعة الإشعارات.
- `collapse_key` (string): مفتاح الطي لـ FCM. الإشعارات التي لها نفس `collapse_key` تحل محل بعضها البعض أثناء عدم اتصال الجهاز بالإنترنت.

```json
{
  "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 الذي يتم فتحه عندما ينقر المستخدم على الإشعار).

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

## Amazon (`amazon`)

يستخدم حقول الإشعارات الفورية الشائعة بالإضافة إلى `custom_icon` و `priority` ([`NotificationPriority`](#notificationpriority-enum)).

```json
{
  "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 للإشعارات الفورية على الويب.

```json
{
  "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`: ما يصل إلى زرين للإجراء.

```json
{
  "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`.

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

## Windows (`windows`)

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

```json
{
  "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 لقالب جانب الروبوت.

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

## Kakao (`kakao`)

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

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

## LINE (`line`)

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

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

```json
{
  "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&lt;string, string&gt;): روابط مفتاح/قيمة يتم استبدالها في القالب، على سبيل المثال `{ "name": "John", "code": "123456" }`.
- `all_devices` (bool): `false` (افتراضي) يسلم إلى الجهاز الأساسي للمستخدم فقط؛ `true` يسلم إلى جميع أجهزة المستخدم.

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

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

نص عادي:

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

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

```json
{
  "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`.

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

## SMS (`sms`)

لدى SMS كتلة منصة خاصة بها داخل [`Content`](#localizedcontent) لكل لغة، إلى جانب `ios` و `android` وقنوات المراسلة الأخرى.

- `body` (string): نص SMS للغة. مطلوب عند وجود كتلة `sms`.

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

- **مضمن** — قم بتعيين `sms.body` لكل لغة في `localized_content`.
- **من إعداد مسبق** — قم بتعيين [`sms_preset`](#payload) على مستوى الحمولة إلى رمز (بالتنسيق `XXXXX-XXXXX`) لـ [إعداد مسبق لرسائل SMS](/ar/product/content/sms-presets/) محفوظ. يتم تحليل محتواه لكل لغة في `sms.body` لكل لغة يحددها الإعداد المسبق. أي `sms.body` مضمن للغة معينة يتجاوز الإعداد المسبق لتلك اللغة، لذا يمكنك إعادة استخدام إعداد مسبق مع تعديل لغات فردية.

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

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

واحد فقط من:

- `rich_media` ([`RichMedia`](#richmedia)): فتح صفحة [وسائط غنية](/ar/product/content/in-apps/).
- `deep_link`: فتح رابط عميق: `{ "code": "flow-code", "params": { "key": "value" } }`.
- `link` ([`Link`](#link)): فتح عنوان URL.

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

يدعم عنوان URL للرابط العميق وقيم `params` صيغة [التخصيص باستخدام Liquid](/ar/developer/guides/personalization/liquid-templates/) — يتم تحليل التعبيرات قبل فتح الرابط العميق.

### الوسائط الغنية (RichMedia)


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

### الرابط (Link)


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

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

## صندوق الوارد (Inbox)

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

```json
{
  "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`

<Aside type="caution">
أرسل دائمًا `priority` كواحدة من القيم النصية أعلاه. تقبل واجهة برمجة التطبيقات أيضًا المكافئات الرقمية للتعداد (1-5، مطابقة للترتيب أعلاه)، لكن هذا الربط هو تفصيل داخلي لـ protobuf، وليس عقدًا مدعومًا — لا تعتمد عليه.

لا يتم رفض قيمة `priority` غير معروفة (سلسلة نصية بها خطأ إملائي أو رقم خارج النطاق): تتجاهلها واجهة برمجة التطبيقات بصمت، ويتم إرسال الإشعار بدون حقل `priority` على الإطلاق بدلاً من إرجاع خطأ.
</Aside>

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

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

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

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