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

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

नोट

पुराने v1 तरीके अब पदावनत (deprecated) हैं लेकिन पूरी तरह से चालू हैं। कोई निश्चित सूर्यास्त तिथि नहीं है, इसलिए आप अपनी गति से माइग्रेट कर सकते हैं। नए इंटीग्रेशन के लिए, 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 टाइमस्टैम्प)। v1 "now" को पुन: उत्पन्न करने के लिए, schedule.at को वर्तमान समय पर सेट करें। अतीत का टाइमस्टैम्प तुरंत भेजा जाता है, जब follow_user_timezone सेट न हो या false हो। follow_user_timezone: true के साथ इसके बजाय अतीत के 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 → payload.content.localized_content.{locale}.{platform}.inbox.expires_in, सेकंड में अवधि के रूप में (उदाहरण के लिए, 7 दिन "604800s" है)।

डिलीवरी नियंत्रण

• dynamic_content / dynamic_content_placeholders → dynamic_content_placeholders segment या transactional पर।
• campaign → campaign segment या transactional पर।
• campaign_name → campaign_name 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 में समर्थित नहीं

• template_bindings: लिक्विड टेम्प्लेट बाइंडिंग 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>" }])।
• devices (ईमेल पते) → transactional.hwids.list। ईमेल के लिए, hwid ही पता होता है।
• use_auto_registration: true → transactional.registration_type: "REGISTRATION_TYPE_FORCE"। यह उन पतों को पंजीकृत करता है जो Pushwoosh के लिए नए हैं और उसी अनुरोध में उन्हें भेजता है। यह केवल hwids के साथ काम करता है। इसके बिना, नए पते छोड़ दिए जाते हैं। return_unknown_identifiers: true के साथ, ऐसा अनुरोध जिसमें कोई भी पता पंजीकृत नहीं है, No recipients found के साथ विफल हो जाता है।
• टारगेटिंग, शेड्यूल, अभियान, आदि, /createMessage के समान।

/createSMSMessage से

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

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

• devices (अंतरराष्ट्रीय प्रारूप में फ़ोन नंबर, जैसे +14155552671) → transactional.hwids.list।
• use_auto_registration: true → transactional.registration_type: "REGISTRATION_TYPE_FORCE", जो भेजने से पहले नए फ़ोन नंबर पंजीकृत करता है।

/createSMSMessage का कोई MMS समकक्ष नहीं है। MMS (विषय + छवि अटैचमेंट) भेजने के लिए, sms.subject और sms.file_urls का उपयोग करें — MMS देखें।

/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") अब transactional.hwids.list में जाता है। यदि आपने इसे /registerDevice के माध्यम से किसी उपयोगकर्ता के लिए पंजीकृत किया है, तो आप इसके बजाय उस उपयोगकर्ता को transactional.users.list के साथ लक्षित कर सकते हैं।
• use_auto_registration: true → transactional.registration_type: "REGISTRATION_TYPE_FORCE"। v1 की तरह, नंबर को whatsapp: प्रीफ़िक्स के साथ transactional.hwids.list में डालें, और Pushwoosh भेजने से पहले इसे पंजीकृत कर देता है, इसलिए आप /registerDevice कॉल छोड़ सकते हैं। प्रत्येक चैनल के hwid प्रारूप और 24-घंटे की विंडो सीमा के लिए नए ईमेल पतों और फ़ोन नंबरों पर भेजें देखें।

/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-Gateway त्रुटि लिफाफे ({ "code": ..., "message": ..., "details": [...] }) का पालन करती हैं।