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-এর মতো একই ডিডুপ্লিকেশন আচরণ: ৫ মিনিটের মধ্যে একই মান দিয়ে একটি পুনরাবৃত্তি কল পুনরায় পাঠানোর পরিবর্তে আসল message_code ফেরত দেয়, শুধুমাত্র কী-এর উপর ম্যাচ করে, পেলোডের উপর নয়। দেখুন transaction_id।

শিডিউলিং

• 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>) হিসাবে রেফারেন্স করা হয়। উদাহরণ: conditions_operator: AND সহ [["Country","EQ","BR"],["Language","EQ","pt"]] → 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-এ, raw push tokens যায় push_tokens-এ।
• users → transactional.users.list।
• platforms (সংখ্যাসূচক কোড [1, 3, …]) → segment.platforms বা transactional.platforms (স্ট্রিং enum ["IOS", "ANDROID", …])। দেখুন Platform enum।

কন্টেন্ট

• content (স্ট্রিং) → payload.content.localized_content.default.{platform}.body। v2-তে, কন্টেন্ট সর্বদা প্রতি-লোকেল এবং প্রতি-প্ল্যাটফর্ম হয়। একটি সাধারণ v1 স্ট্রিং বিশেষ "default" কী-এর অধীনে রাখুন (ক্যাচ-অল অনুবাদ, দেখুন Locale selection)।
• 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.bucket: "1s" সহ send_rate.value।
• 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 নামের জন্য Payload reference দেখুন।

উদাহরণ: আগে এবং পরে

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-তে যান। সম্পূর্ণ রেফারেন্স: 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 থেকে

platforms: ["SMS"] সহ Notify-তে যান। SMS বডি অ্যাপের কনফিগার করা SMS প্রদানকারীর মাধ্যমে ডেলিভার করা হয়। কন্টেন্টটি যেকোনো পূরণ করা প্ল্যাটফর্ম ব্লকে payload.content.localized_content.{locale}.{platform}.body-তে রাখুন।

SMS-নির্দিষ্ট প্রদানকারীর বিকল্পগুলি (প্রেরক আইডি, ইত্যাদি) রিকোয়েস্ট বডির পরিবর্তে অ্যাপের SMS কনফিগারেশন থেকে আসতে থাকবে।

/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। শুধুমাত্র ২৪-ঘণ্টার গ্রাহক পরিষেবা উইন্ডোর ভিতরে Meta দ্বারা ডেলিভার করা হয়।
• 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 (পেলোড স্তরে জেনেরিক প্রিসেট)।
• টার্গেটিং: v1-এ devices-এ যাওয়া WhatsApp ফোন নম্বরটি (যেমন "whatsapp:+1234567890") একজন ব্যবহারকারীর বিরুদ্ধে /registerDevice এর মাধ্যমে রেজিস্টার করতে হবে। v2-তে, ফলস্বরূপ ব্যবহারকারীকে transactional.users.list (অথবা hwid-কে transactional.hwids.list-এর মাধ্যমে) দিয়ে টার্গেট করুন।
• use_auto_registration: সমর্থিত নয়। পাঠানোর আগে WhatsApp নম্বরটি রেজিস্টার করুন।

/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": [...] }) অনুসরণ করে।