# إرسال إشعار (Notify)

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

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

## بنية الطلب

جسم الطلب هو `NotifyRequest` مع نوع واحد بالضبط من نوعين:

- [`segment`](#notifysegment): استهداف شريحة جمهور عن طريق رمز الشريحة، أو تعبير [seglang](/ar/developer/api-reference/segmentation-filters-api/segmentation-language/)، أو تعبير مرشح منظم.
- [`transactional`](#notifytransactional): الإرسال إلى قائمة صريحة من hwids، أو معرفات المستخدمين (user IDs)، أو رموز الإشعارات الفورية (push tokens)، أو أجهزة الاختبار.

```json title="الشكل"
{
  "segment": { ... }       // أو
  "transactional": { ... }
}
```

## NotifySegment

يستهدف المستخدمين الذين يطابقون شريحة جمهور أو تعبير مرشح.

| الحقل | النوع | الوصف |
|---|---|---|
| `schedule` | [`Schedule`](#schedule) | متى وكيف يتم الإرسال. مطلوب. |
| `application` | string | [رمز التطبيق](/ar/developer/api-reference/api-identifiers/#application-code). |
| `platforms` | array of [`Platform`](#platform-enum) | المنصات التي تستهدفها الرسالة. |
| `code` | string | [رمز الشريحة](/ar/developer/api-reference/api-identifiers/#segment--filter-code). متعارض مع `expression` و `filter_expression`. |
| `expression` | string | تعبير [Seglang](/ar/developer/api-reference/segmentation-filters-api/segmentation-language/). |
| `filter_expression` | `FilterExpression` | تعبير مرشح منظم (متقدم). |
| `payload` | [`Payload`](/ar/developer/api-reference/messaging-api-v2/payload-reference/) | حمولة Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber. متعارض مع `email_payload`. |
| `email_payload` | [`EmailPayload`](/ar/developer/api-reference/messaging-api-v2/email-payload-reference/) | حمولة البريد الإلكتروني. |
| `campaign` | string | [رمز الحملة](/ar/developer/api-reference/api-identifiers/#campaign-code) لنسب هذه الرسالة إليه. |
| `frequency_capping` | [`FrequencyCapping`](#frequencycapping) | حدود التكرار لكل مستخدم. |
| `send_rate` | [`SendRate`](#sendrate) | تخفيف سرعة الإرسال. |
| `message_type` | [`MessageType`](#messagetype-enum) | `MESSAGE_TYPE_MARKETING` (الافتراضي) أو `MESSAGE_TYPE_TRANSACTIONAL`. يتحكم في تصفية المجموعة الضابطة. |
| `dynamic_content_placeholders` | map<string, string> | يستبدل العناصر النائبة في المحتوى. |
| `meta_data` | object | بيانات وصفية حرة الشكل يتم تمريرها إلى التحليلات اللاحقة. |

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

```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":     { "body": "Hello!" },
              "android": { "body": "Hello!" }
            }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_MARKETING"
    }
  }'
```

## NotifyTransactional

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

| الحقل | النوع | الوصف |
|---|---|---|
| `schedule` | [`Schedule`](#schedule) | مطلوب. |
| `application` | string | [رمز التطبيق](/ar/developer/api-reference/api-identifiers/#application-code). |
| `platforms` | array of [`Platform`](#platform-enum) | المنصات التي تستهدفها الرسالة. |
| `test_devices` | bool | إذا كانت `true`، يتم الإرسال إلى أجهزة الاختبار الخاصة بالتطبيق فقط. |
| `hwids` | `{ "list": [string, ...] }` | الإرسال إلى هذه [hwids](/ar/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid) فقط. |
| `users` | `{ "list": [string, ...] }` | الإرسال إلى [معرفات المستخدمين](/ar/developer/pushwoosh-knowledge-hub/users-userids/) هذه فقط. |
| `push_tokens` | `{ "list": [string, ...] }` | الإرسال إلى [رموز الإشعارات الفورية](/ar/developer/pushwoosh-knowledge-hub/device-identifiers/#push-token) هذه فقط. |
| `payload` | [`Payload`](/ar/developer/api-reference/messaging-api-v2/payload-reference/) | حمولة Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber. |
| `email_payload` | [`EmailPayload`](/ar/developer/api-reference/messaging-api-v2/email-payload-reference/) | حمولة البريد الإلكتروني. |
| `return_unknown_identifiers` | bool | عندما تكون `true`، تعرض قائمة `unknown_identifiers` في الاستجابة المعرفات التي لم يتم العثور عليها. |
| `use_latest_user_device` | bool | ينطبق فقط عند استهداف `users`. عندما تكون `true`، يتم تسليم الرسالة إلى أحدث جهاز نشط لكل مستخدم — الجهاز الذي لديه أحدث وقت لفتح التطبيق (Last Application Open) — بدلاً من جميع الأجهزة المرتبطة بمعرف المستخدم هذا. القيمة الافتراضية هي `false` (إرسال إلى كل جهاز). |
| `campaign`, `frequency_capping`, `send_rate`, `message_type`, `dynamic_content_placeholders`, `meta_data` | | انظر `NotifySegment` أعلاه. |

`test_devices`، `hwids`، `users`، و `push_tokens` متعارضة. يجب تعيين واحد منها فقط.

### مثال: رسالة تعاملية حسب معرفات المستخدمين

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

## الاستجابة

```json
{
  "result": {
    "message_code": "XXXXX-XXXXX-XXXXX",
    "unknown_identifiers": []
  }
}
```

| الحقل | النوع | الوصف |
|---|---|---|
| `message_code` | string | [رمز رسالة](/ar/developer/api-reference/api-identifiers/#message-code) فريد. استخدمه مع [`/getMessageDetails`](/ar/developer/api-reference/messages-api/#getmessagedetails) ونقاط نهاية إحصائيات الرسائل. |
| `unknown_identifiers` | array of string | المعرفات التي لم يتم العثور عليها في الحساب. يتم ملؤها فقط عند تعيين `return_unknown_identifiers: true` في النوع `transactional`. |

## الأنواع المشتركة

### Schedule

```json
{
  "at": "2026-05-01T12:00:00Z",
  "follow_user_timezone": true,
  "past_timezones_behaviour": "PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY"
}
```

| الحقل | النوع | الوصف |
|---|---|---|
| `at` | timestamp | وقت الإرسال المطلق (RFC 3339). إذا كان في الماضي، يتم إرسال الرسالة فورًا. بحد أقصى 14 يومًا في المستقبل. |
| `after` | duration | بديل لـ `at`. أرسل بعد هذا الفاصل الزمني من "الآن" (على سبيل المثال، `"3600s"`). |
| `follow_user_timezone` | bool | عندما تكون `true`، يستقبل كل جهاز الرسالة في وقت `at` حسب منطقته الزمنية المحلية. |
| `past_timezones_behaviour` | enum | `PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY` (الافتراضي)، `PAST_TIMEZONES_BEHAVIOUR_DO_NOT_SEND`، أو `PAST_TIMEZONES_BEHAVIOUR_NEXT_DAY`. يكون ذا معنى فقط عندما تكون `follow_user_timezone` قيمتها `true`. |

### FrequencyCapping

حدود التكرار لكل مستخدم للإرسالات التسويقية. لتعطيل الحد، احذف `frequency_capping` بالكامل، أو أرسل `days: 0` مع `count: 0`.

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

<Aside type="caution" title="هام">
إرسال `days` و `count` بصفرية غير متطابقة (على سبيل المثال، `{"days": 0, "count": 5}`) يعيد `400`. هذا التحقق هو تغيير جذري في `Notify` — العملاء الذين كانوا يعتمدون سابقًا على تجاهل `0` منفرد بصمت سيحصلون الآن على خطأ بدلاً من ذلك.
</Aside>

### SendRate

```json
{ "value": 500, "bucket": "1s", "avoid": false }
```

يخفف سرعة الإرسال. `value` هي الرسائل لكل `bucket`؛ `bucket` النموذجي هو `"1s"`.

### تعداد Platform

`IOS`, `ANDROID`, `OSX`, `WINDOWS`, `AMAZON`, `SAFARI`, `CHROME`, `FIREFOX`, `IE`, `EMAIL`, `BAIDU_ANDROID`, `HUAWEI_ANDROID`, `SMS`, `WEB`, `KAKAO`, `TELEGRAM`, `LINE`, `WHATS_APP`, `VIBER`.

### تعداد MessageType

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

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

<CardGrid>
  <LinkCard title="إلغاء" href="/developer/api-reference/messaging-api-v2/cancel/" />
  <LinkCard title="مرجع الحمولة" href="/developer/api-reference/messaging-api-v2/payload-reference/" />
  <LinkCard title="مرجع حمولة البريد الإلكتروني" href="/developer/api-reference/messaging-api-v2/email-payload-reference/" />
  <LinkCard title="الترحيل من الإصدار 1" href="/developer/api-reference/messaging-api-v2/migration-from-v1/" />
</CardGrid>