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

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

ملاحظة

طرق v1 القديمة مهملة ولكنها تعمل بكامل طاقتها. لا يوجد تاريخ محدد لإيقافها، لذا يمكنك الترحيل بالسرعة التي تناسبك. بالنسبة لعمليات التكامل الجديدة، استخدم Messaging API v2.

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

الجانب	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. في 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.

المحتوى

• content (نص) ← payload.content.localized_content.default.{platform}.body. في v2، يكون المحتوى دائمًا لكل لغة وكل منصة. ضع نص v1 العادي تحت المفتاح الخاص "default" (ترجمة شاملة، انظر اختيار اللغة للجهاز).
• 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) للحصول على أسماء v2 الدقيقة.

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

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

{
  "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:

{
  "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).

• 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 مقابل مستخدم. في 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:

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

يعيد v2 Notify:

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

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