# الترحيل من الإصدار v1

import { Badge } from '@astrojs/starlight/components';

يقوم هذا الدليل بربط كل حقل من حقول `/create*Message` القديمة بما يعادله في Messaging API v2. استخدمه كمرجع أثناء نقل عمليات التكامل الحالية.

<Aside type="note">
طرق v1 القديمة مهملة ولكنها تعمل بكامل طاقتها. لا يوجد تاريخ محدد لإيقافها، لذا يمكنك الترحيل بالسرعة التي تناسبك. بالنسبة لعمليات التكامل الجديدة، استخدم Messaging API v2.
</Aside>

## الفروق على المستوى العام

| الجانب | v1 | v2 |
|---|---|---|
| نقطة نهاية لكل قناة | طريقة منفصلة لكل قناة (`/createMessage`، `/createEmailMessage`، `/createSMSMessage`، `/createKakaoMessage`، ...) | نقطة نهاية واحدة — `POST /messaging/v2/notify` |
| المصادقة | حقل `auth` في جسم الطلب | ترويسة `Authorization: Token <API_TOKEN>` |
| الاستهداف | مختلط: `filter` + `conditions` + `devices` + `users` في نفس الطلب | تقسيم صريح: `NotifySegment` مقابل `NotifyTransactional` |
| المحتوى | `content` مسطح + كتل منصات شقيقة | متداخل `payload.content.localized_content.{locale}.{platform}` |
| الاستجابة | `MessageCode[]` | `message_code` + `unknown_identifiers` اختياري |

## من `/createMessage`

تصبح إدخالات `notifications[*]` في v1 طلبات `Notify` فردية (رسالة واحدة لكل طلب). إذا كان استدعاء v1 يحتوي على إدخالات متعددة، قم بإصدار طلب `Notify` واحد لكل إدخال.

**قرار الاستهداف.** إذا كان إدخال v1 يستخدم `devices` أو `users` (قوائم صريحة)، قم بربطه بـ `transactional`. وإلا، قم بربطه بـ `segment`.

### حقول على مستوى الطلب

- `application` ← `segment.application` أو `transactional.application` (نفس تنسيق رمز التطبيق).
- `applications_group`: غير مدعوم في v2. استخدم طلبات متعددة لكل تطبيق.
- `auth`: تم نقله إلى ترويسة `Authorization`، ولم يعد في الجسم.

### الجدولة

- `send_date` (`"YYYY-MM-DD HH:mm"` أو `"now"`) ← `schedule.at` (طابع زمني RFC 3339 UTC). لإعادة إنتاج `"now"` من v1، اضبط `schedule.at` على الوقت الحالي. أي طابع زمني في الماضي يتم إرساله فورًا.
- `ignore_user_timezone` ← `schedule.follow_user_timezone`. **معكوس:** `ignore_user_timezone: true` تصبح `follow_user_timezone: false`.
- `timezone`: غير مدعوم. يستخدم v2 دائمًا UTC لـ `at`. قم بالتحويل من جانب العميل.

### الاستهداف

- `filter` (اسم segment) ← `segment.code`.
- `conditions` (`[[tag, op, value], ...]`) ← `segment.expression`. أعد كتابته إلى تعبير [seglang](/ar/developer/api-reference/segmentation-filters-api/segmentation-language/). في seglang، `*` هو AND المنطقي ويتم الإشارة إلى العلامات الخاصة بالتطبيق كـ `Tag("<application-code>", "<tag>", <op>, <value>)`. مثال: `[["Country","EQ","BR"],["Language","EQ","pt"]]` مع `conditions_operator: AND` ← `Tag("XXXXX-XXXXX", "Country", EQ, "br") * Tag("XXXXX-XXXXX", "Language", EQ, "pt")`.
- `conditions_operator` (`AND` / `OR`): تم دمجه في `segment.expression`.
- `devices` (hwids أو push tokens) ← `transactional.hwids.list` أو `transactional.push_tokens.list`. يفصل v2 بين الاثنين: تذهب hwids إلى `hwids`، وتذهب push tokens الخام إلى `push_tokens`.
- `users` ← `transactional.users.list`.
- `platforms` (رموز رقمية `[1, 3, …]`) ← `segment.platforms` أو `transactional.platforms` (تعدادات نصية `["IOS", "ANDROID", …]`). انظر [Platform enum](/ar/developer/api-reference/messaging-api-v2/notify/#platform-enum).

### المحتوى

- `content` (نص) ← `payload.content.localized_content.default.{platform}.body`. في v2، يكون المحتوى دائمًا لكل لغة وكل منصة. ضع نص v1 العادي تحت المفتاح الخاص `"default"` (ترجمة شاملة، انظر [اختيار اللغة للجهاز](/ar/developer/api-reference/messaging-api-v2/payload-reference/#locale-selection-for-a-device)).
- `content` (`{locale: text}`) ← `payload.content.localized_content.{locale}.{platform}.body`. كرر الجسم في كل كتلة منصة مستهدفة.
- `preset` ← `payload.preset`.
- `data` ← `payload.custom_data`.
- `rich_media` ← `payload.open_action.rich_media.code`.
- `link` ← `payload.open_action.link.url`.
- `minimize_link` (`0` أو `2`) ← `payload.open_action.link.shortener` (`NONE` أو `BITLY`).
- `inbox_image` ← `payload.content.localized_content.{locale}.{platform}.inbox.image_url` (كل كتلة منصة لها `inbox` خاص بها).
- `inbox_date` ← `payload.content.localized_content.{locale}.{platform}.inbox.expiration_date`.
- `inbox_days`: غير مدعوم. قم بتحويله إلى `expiration_date` مطلق من جانب العميل.

### ضوابط التسليم

- `dynamic_content` / `dynamic_content_placeholders` ← `dynamic_content_placeholders` على `segment` أو `transactional`.
- `campaign` ← `campaign` على `segment` أو `transactional`.
- `capping_days` ← `frequency_capping.days`.
- `capping_count` ← `frequency_capping.count`.
- `send_rate` (int) ← `send_rate.value` مع `send_rate.bucket: "1s"`.
- `message_type` (`"marketing"` / `"transactional"`) ← `message_type` (`MESSAGE_TYPE_MARKETING` / `MESSAGE_TYPE_TRANSACTIONAL`).

### غير مدعوم في v2

- `transactionId`: لا يوجد معادل مباشر. تتبع الارتباط من جانبك.
- `template_bindings`: روابط قوالب Liquid غير متوفرة في v2. استمر في استخدام v1 إذا كنت تعتمد عليها.

### كتل خاصة بالمنصات

يقبل v1 معلمات خاصة بالمنصة على المستوى الأعلى لكل إدخال `notifications[*]` (`ios`، `android`، `safari`، `chrome`، ...). في v2، تنتقل هذه المعلمات إلى داخل اللغة:

```
// v1
"notifications": [{
  "content": "Hello",
  "ios":     { "title": "Hi",    "sound": "default.caf" },
  "android": { "header": "Hi",   "led": "#ff0000" }
}]

// v2
"payload": {
  "content": {
    "localized_content": {
      "en": {
        "ios":     { "title": "Hi", "body": "Hello", "sound": "default.caf" },
        "android": { "title": "Hi", "body": "Hello", "led_color": "#ff0000" }
      }
    }
  }
}
```

تختلف أسماء الحقول داخل كتل المنصات في بعض الأماكن. انظر [مرجع الحمولة (Payload)](/ar/developer/api-reference/messaging-api-v2/payload-reference/) للحصول على أسماء v2 الدقيقة.

### مثال: قبل وبعد

**v1 `/createMessage`** (إرسال إشعار إلى segment):

```json
{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth":        "YOUR_API_TOKEN",
    "notifications": [{
      "send_date":  "2026-05-01 12:00",
      "content":    "Hello!",
      "platforms":  [1, 3],
      "filter":     "active_users",
      "campaign":   "YYYYY-YYYYY",
      "capping_days":  7,
      "capping_count": 3,
      "message_type":  "marketing"
    }]
  }
}
```

**v2 `/messaging/v2/notify`**:

```json
{
  "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" },
    "frequency_capping": { "days": 7, "count": 3 },
    "campaign":          "YYYYY-YYYYY",
    "message_type":      "MESSAGE_TYPE_MARKETING"
  }
}
```

## من `/createTargetedMessage`

يتم ربط `/createTargetedMessage` بـ `transactional` في معظم الحالات أو بـ `segment` إذا كنت تستخدمه فقط كـ `devices_filter` عبر التطبيقات بدون معرفات صريحة.

- `devices_filter` ← `segment.expression` (seglang) أو `segment.filter_expression` (منظم).
- `content` ← `payload.content.localized_content.{locale}.{platform}.body`.
- جميع الحقول الأخرى، كما في `/createMessage` أعلاه.

## من `/createEmailMessage`

انتقل إلى `Notify` مع `platforms: ["EMAIL"]` وكتلة `email_payload`. المرجع الكامل: [مرجع حمولة البريد الإلكتروني (Email payload)](/ar/developer/api-reference/messaging-api-v2/email-payload-reference/).

- `subject` ← `email_payload.subject` (خريطة مفتاحها اللغة. قم بتغليف قيم اللغة الواحدة في `{"en": "..."}`).
- `content` (HTML) ← `email_payload.body`.
- `email_template` ← `email_payload.email_template`.
- `from` / `from_name` ← `email_payload.from` (`{ "name": "...", "email": "..." }`).
- `reply_to` / `reply_to_name` ← `email_payload.reply_to`.
- `list_unsubscribe` ← `email_payload.list_unsubscribe`.
- `attachments` ← `email_payload.attachments` (`[{ "name": "...", "content": "<base64>" }]`).
- الاستهداف، الجدولة، الحملة، إلخ، كما في `/createMessage`.

## من `/createSMSMessage`

انتقل إلى `Notify` مع `platforms: ["SMS"]`. يتم تسليم نص الرسالة القصيرة عبر مزود خدمة الرسائل القصيرة الذي تم تكوينه للتطبيق. ضع المحتوى في `payload.content.localized_content.{locale}.{platform}.body` على أي كتلة منصة مملوءة.

تستمر خيارات مزود خدمة الرسائل القصيرة المحددة (معرف المرسل، إلخ) في القدوم من تكوين الرسائل القصيرة للتطبيق بدلاً من جسم الطلب.

## من `/createKakaoMessage`

انتقل إلى `Notify` مع `platforms: ["KAKAO"]`، باستخدام `payload.content.localized_content.{locale}.kakao`:

- `template_id` ← `kakao.template`.
- `content` ← `kakao.content`.
- `variables` ← `kakao.content_variables` (محول إلى سلسلة JSON).

## من `/createWhatsAppMessage`

انتقل إلى `Notify` مع `platforms: ["WHATS_APP"]`، باستخدام `payload.content.localized_content.{locale}.whatsapp`:

- `content` (نص حر) ← `whatsapp.content`. يتم تسليمه بواسطة Meta فقط خلال نافذة خدمة العملاء التي تبلغ 24 ساعة.
- `content_id` ← `whatsapp.content_id`. اسم قالب Meta تمت الموافقة عليه مسبقًا.
- `language` ← `whatsapp.language`. لغة قالب Meta (على سبيل المثال `"en_US"`). مستقل عن مفتاح لغة `LocalizedContent` الخارجي.
- `content_variables` (كائن في v1) ← `whatsapp.content_variables` (كائن محول إلى سلسلة JSON). مثال v1 `{"1": "John"}` يصبح v2 `"{\"1\":\"John\"}"`.
- `button_url_variables` (كائن) ← `whatsapp.button_url_variables` (محول إلى سلسلة JSON).
- `header_variables` (كائن) ← `whatsapp.header_variables` (محول إلى سلسلة JSON).
- `preset` ← `payload.preset` (إعداد مسبق عام على مستوى الحمولة).
- الاستهداف: رقم هاتف WhatsApp الذي كان في v1 يذهب إلى `devices` (على سبيل المثال `"whatsapp:+1234567890"`) يجب تسجيله عبر [`/registerDevice`](/ar/developer/api-reference/device-api#registerdevice) مقابل مستخدم. في v2، استهدف المستخدم الناتج باستخدام `transactional.users.list` (أو hwid عبر `transactional.hwids.list`).
- `use_auto_registration`: غير مدعوم. قم بتسجيل رقم WhatsApp قبل الإرسال.

## من `/createLineMessage`

انتقل إلى `Notify` مع `platforms: ["LINE"]`، باستخدام `payload.content.localized_content.{locale}.line`:

- `content` (نص عادي) ← `line.content`.
- `preset` (رمز إعداد مسبق لـ LINE) ← `line.template`. يخزن حقل v2 رمزًا يشير إلى قالب LINE تم تكوينه في لوحة تحكم Pushwoosh.
- `template` المضمن (هياكل رسائل الصور أو الدوارة أو المرنة في v1): غير مدعوم مباشرة في v2. قم بتكوين الرسالة الغنية مسبقًا كإعداد مسبق لـ LINE في لوحة التحكم وأشر إليها من خلال `line.template`.
- الاستهداف: قائمة `devices` في v1 (معرفات مستخدمي LINE المسجلة من خلال SDK / `/registerDevice`) تصبح `transactional.users.list` (أو hwid عبر `transactional.hwids.list`) في v2.

## فروق الاستجابة

يعيد v1 `/createMessage`:

```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": { "Messages": ["XXXXX-XXXXX-AAAAA"] }
}
```

يعيد v2 `Notify`:

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

تتبع الاستجابات غير 200 غلاف الخطأ القياسي لـ gRPC-Gateway (`{ "code": ..., "message": ..., "details": [...] }`) بدلاً من زوج `status_code` / `status_message` في v1.