الترحيل من الإصدار 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

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

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

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

• application ← segment.application أو transactional.application (نفس تنسيق رمز التطبيق).
• applications_group: غير مدعوم في v2. استخدم طلبات متعددة لكل تطبيق.
• auth: تم نقله إلى رأس Authorization، ولم يعد في الجسم.
• transactionId ← transaction_id، وهو حقل على مستوى الطلب بجانب segment / transactional. نفس سلوك إزالة التكرار كما في v1: استدعاء متكرر بنفس القيمة في غضون 5 دقائق يُرجع message_code الأصلي بدلاً من إعادة الإرسال، تتم المطابقة على المفتاح وحده، وليس على الحمولة. انظر transaction_id.

الجدولة

• 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 (عدد صحيح) ← send_rate.value مع send_rate.bucket: "1s".
• message_type ("marketing" / "transactional") ← message_type (MESSAGE_TYPE_MARKETING / MESSAGE_TYPE_TRANSACTIONAL).

غير مدعوم في v2

• 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" }
      }
    }
  }
}

تختلف أسماء الحقول داخل كتل المنصة في بعض الأماكن. انظر مرجع الحمولة للحصول على أسماء 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. المرجع الكامل: مرجع حمولة البريد الإلكتروني.

• 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 على أي كتلة منصة ممتلئة.

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

/createSMSMessage ليس له مكافئ MMS. لإرسال MMS (موضوع + مرفقات صور)، استخدم sms.subject و sms.file_urls — انظر MMS.

من /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.