v1 से माइग्रेशन

यह गाइड हर लेगेसी /create*Message फ़ील्ड को उसके Messaging API v2 समकक्ष पर मैप करती है। मौजूदा इंटीग्रेशन को पोर्ट करते समय इसे एक संदर्भ के रूप में उपयोग करें।

नोट

लेगेसी v1 मेथड्स अब पदावनत (deprecated) हैं लेकिन पूरी तरह से चालू हैं। कोई हार्ड सनसेट डेट नहीं है, इसलिए आप अपनी गति से माइग्रेट कर सकते हैं। नए इंटीग्रेशन के लिए, Messaging API v2 का उपयोग करें।

उच्च-स्तरीय अंतर

पहलू	v1	v2
प्रति चैनल एंडपॉइंट	हर चैनल के लिए अलग मेथड (/createMessage, /createEmailMessage, /createSMSMessage, /createKakaoMessage, …)	एकल एंडपॉइंट — POST /messaging/v2/notify
प्रमाणीकरण (Auth)	रिक्वेस्ट बॉडी में 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 हेडर में ले जाया गया, अब बॉडी में नहीं है।

शेड्यूलिंग

• send_date ("YYYY-MM-DD HH:mm" या "now") → schedule.at (RFC 3339 UTC टाइमस्टैम्प)। v1 "now" को फिर से बनाने के लिए, schedule.at को वर्तमान समय पर सेट करें। अतीत में कोई भी टाइमस्टैम्प तुरंत भेजा जाता है।
• ignore_user_timezone → schedule.follow_user_timezone। उलटा: ignore_user_timezone: true अब follow_user_timezone: false हो जाता है।
• timezone: समर्थित नहीं है। v2 हमेशा at के लिए UTC का उपयोग करता है। क्लाइंट-साइड पर रूपांतरित करें।

टारगेटिंग

• filter (सेगमेंट का नाम) → 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 या पुश टोकन) → transactional.hwids.list या transactional.push_tokens.list। v2 दोनों को अलग करता है: hwids hwids में जाते हैं, रॉ पुश टोकन push_tokens में जाते हैं।
• users → transactional.users.list।
• platforms (संख्यात्मक कोड [1, 3, …]) → segment.platforms या transactional.platforms (स्ट्रिंग एनम ["IOS", "ANDROID", …])। प्लेटफ़ॉर्म एनम देखें।

कंटेंट

• 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 → segment या transactional पर dynamic_content_placeholders।
• campaign → segment या transactional पर campaign।
• 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" }
      }
    }
  }
}

प्लेटफ़ॉर्म ब्लॉक्स के भीतर फ़ील्ड नाम कुछ जगहों पर भिन्न होते हैं। सटीक v2 नामों के लिए पेलोड संदर्भ देखें।

उदाहरण: पहले और बाद में

v1 /createMessage (एक सेगमेंट को पुश):

{
  "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 से

platforms: ["EMAIL"] और एक email_payload ब्लॉक के साथ Notify पर जाएँ। पूरा संदर्भ: ईमेल पेलोड संदर्भ।

• 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 से

platforms: ["SMS"] के साथ Notify पर जाएँ। SMS बॉडी ऐप के कॉन्फ़िगर किए गए SMS प्रदाता के माध्यम से डिलीवर की जाती है। कंटेंट को किसी भी भरे हुए प्लेटफ़ॉर्म ब्लॉक पर payload.content.localized_content.{locale}.{platform}.body में डालें।

SMS-विशिष्ट प्रदाता विकल्प (प्रेषक आईडी, आदि) रिक्वेस्ट बॉडी के बजाय ऐप के SMS कॉन्फ़िगरेशन से आते रहेंगे।

/createKakaoMessage से

platforms: ["KAKAO"] के साथ Notify पर जाएँ, payload.content.localized_content.{locale}.kakao का उपयोग करके:

• template_id → kakao.template।
• content → kakao.content।
• variables → kakao.content_variables (JSON-स्ट्रिंगीफाइड)।

/createWhatsAppMessage से

platforms: ["WHATS_APP"] के साथ Notify पर जाएँ, payload.content.localized_content.{locale}.whatsapp का उपयोग करके:

• content (फ्री-फॉर्म टेक्स्ट) → whatsapp.content। मेटा द्वारा केवल 24-घंटे की ग्राहक सेवा विंडो के अंदर डिलीवर किया जाता है।
• content_id → whatsapp.content_id। एक पूर्व-अनुमोदित मेटा टेम्पलेट का नाम।
• language → whatsapp.language। मेटा-टेम्पलेट लोकेल (जैसे "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 (पेलोड स्तर पर सामान्य प्रीसेट)।
• टारगेटिंग: व्हाट्सएप फ़ोन नंबर जो v1 में devices में जाता था (जैसे "whatsapp:+1234567890") को एक उपयोगकर्ता के विरुद्ध /registerDevice के माध्यम से पंजीकृत किया जाना चाहिए। v2 में, परिणामी उपयोगकर्ता को transactional.users.list (या hwid को transactional.hwids.list के माध्यम से) के साथ लक्षित करें।
• use_auto_registration: समर्थित नहीं है। भेजने से पहले व्हाट्सएप नंबर पंजीकृत करें।

/createLineMessage से

platforms: ["LINE"] के साथ Notify पर जाएँ, payload.content.localized_content.{locale}.line का उपयोग करके:

• content (सादा टेक्स्ट) → line.content।
• preset (LINE प्रीसेट कोड) → line.template। v2 फ़ील्ड एक कोड संग्रहीत करता है जो Pushwoosh कंट्रोल पैनल में कॉन्फ़िगर किए गए LINE टेम्पलेट को संदर्भित करता है।
• इनलाइन template (v1 इमेज, कैरोसेल, या फ्लेक्स संदेश संरचनाएं): v2 में सीधे समर्थित नहीं हैं। रिच संदेश को कंट्रोल पैनल में LINE प्रीसेट के रूप में पूर्व-कॉन्फ़िगर करें और इसे line.template के माध्यम से संदर्भित करें।
• टारगेटिंग: v1 devices सूची (SDK / /registerDevice के माध्यम से पंजीकृत LINE उपयोगकर्ता आईडी) v2 में transactional.users.list (या hwid transactional.hwids.list के माध्यम से) बन जाती है।

रिस्पॉन्स में अंतर

v1 /createMessage लौटाता है:

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

v2 Notify लौटाता है:

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

200 के अलावा अन्य रिस्पॉन्स v1 के status_code / status_message जोड़ी के बजाय मानक gRPC-गेटवे त्रुटि एनवेलप ({ "code": ..., "message": ..., "details": [...] }) का पालन करते हैं।