অবজেক্ট ট্যাগ API (বিটা)

অবজেক্ট ট্যাগ একজন ব্যবহারকারী সম্পর্কে কাঠামোগত ডেটা একটি ট্যাগে সংরক্ষণ করে। Object টাইপের একটি ট্যাগ নামযুক্ত ফিল্ডসহ একটি অবজেক্ট ধারণ করে, যেমন amount এবং status সহ সর্বশেষ order। ObjectList টাইপের একটি ট্যাগ এমন অবজেক্টের একটি অ্যারে ধারণ করে, যেমন সমস্ত orders। আপনি ফিল্ডগুলি একবার সংজ্ঞায়িত করেন, ট্যাগ API-এর মাধ্যমে মান লেখেন ও পড়েন, এবং ফিল্ডের মান অনুযায়ী সেগমেন্ট তৈরি করেন।

বিটা

অবজেক্ট ট্যাগ বিটাতে রয়েছে এবং অনুরোধের ভিত্তিতে উপলব্ধ। আপনার অ্যাকাউন্টের জন্য এগুলি সক্রিয় করতে Pushwoosh সাপোর্ট-এর সাথে যোগাযোগ করুন। বিটা চলাকালীন অবজেক্ট ট্যাগ শুধুমাত্র API-এর মাধ্যমে কাজ করে:

• কন্ট্রোল প্যানেলে অবজেক্ট ট্যাগের জন্য কোনো স্ক্রিন নেই।
• অবজেক্ট ট্যাগের ফিল্ড বার্তার কনটেন্টে যোগ করা যায় না।
• Customer Journey অবজেক্ট ট্যাগ সমর্থন করে না।

অবজেক্ট ট্যাগ কীভাবে কাজ করে

একটি অবজেক্ট ট্যাগের একটি স্কিমা এবং একটি মান থাকে। স্কিমা হলো ট্যাগের নাম এবং ফিল্ডের একটি তালিকা, যার প্রতিটির নিজস্ব স্কেলার টাইপ রয়েছে। মান ফিল্ডগুলিতে সংরক্ষিত হয়, প্রতিটি ব্যবহারকারীর জন্য আলাদাভাবে।

• ফিল্ড। প্রতিটি ফিল্ড <object>.<field> নামের একটি ট্যাগ, উদাহরণস্বরূপ order.amount। আপনি ফিল্ড অনুযায়ী সেগমেন্ট তৈরি করেন, এবং এই নাম দিয়ে একটি Object ট্যাগের ফিল্ড লিখতে পারেন।
• Object মান। প্রতি ব্যবহারকারী একটি অবজেক্ট, উদাহরণস্বরূপ "order": {"amount": 120, "status": "paid"}।
• ObjectList মান। একই ফিল্ডসহ অবজেক্টের একটি অ্যারে, উদাহরণস্বরূপ "orders": [{"amount": 120, "status": "paid"}, {"amount": 50}]।

অবজেক্ট ট্যাগ সবসময় User-specific, অর্থাৎ মানটি ব্যবহারকারীর, কোনো একটি ডিভাইসের নয়, এবং এটি ব্যবহারকারীর সমস্ত ডিভাইসে কপি করা হয়। সাধারণ ট্যাগের জন্য ট্যাগ API দেখুন।

স্কিমার নিয়ম

আপনি যখন একটি অবজেক্ট ট্যাগ তৈরি করেন বা একটি ফিল্ড যোগ করেন, Pushwoosh এই নিয়মগুলি পরীক্ষা করে:

• অবজেক্ট এবং ফিল্ডের নামে শুধুমাত্র ল্যাটিন অক্ষর, অঙ্ক এবং _ থাকে।
• সম্পূর্ণ ফিল্ডের নাম <object>.<field> 64 অক্ষর বা তার কম।
• একটি অবজেক্ট ট্যাগে 1 থেকে 20টি ফিল্ড থাকে। ফিল্ডের নাম কেস-ইনসেনসিটিভ, তাই Amount এবং amount একই ফিল্ড।
• একটি ফিল্ডের টাইপ এগুলির একটি: INTEGER, STRING, LIST, DATE, BOOLEAN, PRICE, VERSION। টাইমজোন ফিল্ড এবং নেস্টেড অবজেক্ট সমর্থিত নয়।
• একটি ফিল্ড এমন নাম নিতে পারে না যা অন্য কোনো ট্যাগের ইতিমধ্যে আছে। যদি order.note ট্যাগ বিদ্যমান থাকে, তাহলে order-এ note ফিল্ড যোগ করা tag order.note already exists দিয়ে ব্যর্থ হয়।
• একটি অবজেক্ট ট্যাগ তার শেষ ফিল্ড হারাতে পারে না। পরিবর্তে অবজেক্ট ট্যাগটি ডিলিট করুন।
• ব্যবহৃত হচ্ছে এমন কোনো ফিল্ড বা অবজেক্ট ট্যাগ ডিলিট করা যায় না। ত্রুটিতে এটি কোথায় ব্যবহৃত হচ্ছে তার তালিকা থাকে, উদাহরণস্বরূপ field is in use: segment Big buyers, in-app Spring sale। ট্যাগটিকে রেফারেন্স করে এমন সেগমেন্ট, ইন-অ্যাপ, চলমান Customer Journey ক্যাম্পেইন, প্রিসেট, ইমেল টেমপ্লেট এবং অন্যান্য আইটেম ব্যবহার হিসেবে গণ্য হয়।

স্কিমা পরিচালনা করুন

নিচের REST মেথডগুলি দিয়ে অবজেক্ট ট্যাগ তৈরি ও পরিবর্তন করুন। /json/1.3/addTag শুধুমাত্র সাধারণ ট্যাগের জন্য ব্যবহার করুন, কারণ এটি ফিল্ড সংজ্ঞায়িত করতে পারে না।

বেস URL

https://rpc-api.svc-nue.pushwoosh.com

প্রমাণীকরণ

প্রতিটি অনুরোধে আপনার সার্ভার API টোকেন সহ একটি Authorization হেডার থাকতে হবে। একটি ডিভাইস API টোকেন HTTP 403 a device API token cannot call this method, use an account API token পায়।

Authorization: Api YOUR_API_TOKEN

এন্ডপয়েন্ট

এই মেথডগুলি অবজেক্ট ট্যাগের স্কিমা পরিচালনা করে:

মেথড	পাথ	বিবরণ
POST	/api/tags	ফিল্ডসহ একটি অবজেক্ট ট্যাগ তৈরি করুন
GET	/api/tags/{name}	ফিল্ডসহ একটি অবজেক্ট ট্যাগ পান
GET	/api/tags	ট্যাগের তালিকা দেখুন। একটি অবজেক্ট ট্যাগ তার fields সহ আসে, এবং ফিল্ডগুলি আলাদা ট্যাগ হিসেবে তালিকাভুক্ত হয় না
POST	/api/tags/{name}/fields	একটি ফিল্ড যোগ করুন
DELETE	/api/tags/{name}/fields/{field}	একটি ফিল্ড ডিলিট করুন
DELETE	/api/tags/{name}	সমস্ত ফিল্ডসহ একটি অবজেক্ট ট্যাগ ডিলিট করুন

POST /api/tags এবং উভয় ফিল্ড মেথড পরিবর্তনের পরের অবজেক্ট ট্যাগ {"tag": {...}}-এ মোড়ানো অবস্থায় ফেরত দেয়। DELETE /api/tags/{name} {} ফেরত দেয়।

যদি আপনার অ্যাকাউন্টের জন্য অবজেক্ট ট্যাগ সক্রিয় না থাকে, তাহলে অবজেক্ট টাইপসহ POST /api/tags এবং উভয় ফিল্ড মেথড HTTP 403 object tags are not enabled for the account দিয়ে ব্যর্থ হয়। GET /api/tags/{name} এবং DELETE /api/tags/{name} HTTP 404 tag not found ফেরত দেয়, এবং GET /api/tags অবজেক্ট ট্যাগ তালিকাভুক্ত করে না। অবজেক্ট ট্যাগ সক্রিয় না থাকলে আপনি একটিও তৈরি করতে পারবেন না, তাই মান লেখার মতো কিছু থাকে না।

একটি অবজেক্ট ট্যাগ তৈরি করুন

POST /api/tags

অনুরোধের বডি

নাম	টাইপ	বিবরণ
name*	string	অবজেক্ট ট্যাগের নাম।
type*	string	একটি অবজেক্টের জন্য OBJECT অথবা অবজেক্টের তালিকার জন্য OBJECT_LIST।
fields*	array	অবজেক্টের ফিল্ড, 1 থেকে 20টি।
fields[].name*	string	ফিল্ডের নাম। ফিল্ডটি <name>.<fields[].name> ট্যাগে পরিণত হয়।
fields[].type*	string	ফিল্ডের টাইপ: INTEGER, STRING, LIST, DATE, BOOLEAN, PRICE অথবা VERSION।

উদাহরণ

{
  "name": "orders",
  "type": "OBJECT_LIST",
  "fields": [
    { "name": "amount", "type": "INTEGER" },
    { "name": "status", "type": "STRING" }
  ]
}

প্রতিক্রিয়া

{
  "tag": {
    "name": "orders",
    "type": "OBJECT_LIST",
    "system": false,
    "user_specific": true,
    "has_right_ace_modify": true,
    "fields": [
      { "name": "amount", "type": "INTEGER" },
      { "name": "status", "type": "STRING" }
    ]
  }
}

user_specific-এর মান যা-ই হোক, ট্যাগটি User-specific হিসেবে তৈরি হয়। GET /api/tags/{name} একই অবজেক্ট tag র‍্যাপার ছাড়া ফেরত দেয়। ফিল্ডগুলি নাম অনুযায়ী সাজানো থাকে।

একটি ফিল্ড যোগ করুন

POST /api/tags/{name}/fields

উদাহরণ: POST /api/tags/orders/fields

{
  "field": { "name": "note", "type": "STRING" }
}

আপনি নতুন ফিল্ডটি সঙ্গে সঙ্গে সম্পূর্ণ ট্যাগ মানের অংশ হিসেবে লিখতে পারেন। অবজেক্ট ট্যাগে ইতিমধ্যে 20টি ফিল্ড থাকলে বা সম্পূর্ণ ফিল্ডের নামসহ কোনো ট্যাগ বিদ্যমান থাকলে ফিল্ড যোগ করা ব্যর্থ হয়, ত্রুটি দেখুন।

একটি ফিল্ড ডিলিট করুন

DELETE /api/tags/{name}/fields/{field}

উদাহরণস্বরূপ, DELETE /api/tags/orders/fields/note orders.note ফিল্ডটি ডিলিট করে। আপনি শেষ ফিল্ড বা ব্যবহৃত হচ্ছে এমন ফিল্ড ডিলিট করতে পারবেন না, ত্রুটি দেখুন।

ত্রুটি

ত্রুটিগুলি {"code": <n>, "message": "...", "details": [...]} ফরম্যাটে আসে। আপনি যখন একটি অবজেক্ট ট্যাগ তৈরি করেন, 400 বার্তাগুলি validate: দিয়ে শুরু হয়।

HTTP স্ট্যাটাস	বার্তা	কারণ
400	object tag and field names must contain only letters, digits and underscores	কোনো নামে অন্য কোনো অক্ষর আছে।
400	an object tag needs 1 to 20 fields	তৈরির সময় কোনো ফিল্ড নেই বা 20টির বেশি ফিল্ড।
400	an object tag has at most 20 fields	অবজেক্ট ট্যাগে ইতিমধ্যে 20টি ফিল্ড আছে।
400	field <name> is given twice	কেস উপেক্ষা করলে দুটি ফিল্ডের নাম একই।
400	<object>.<field>: object and field names together cannot be longer than 64 characters	সম্পূর্ণ ফিল্ডের নাম খুব দীর্ঘ।
400	<object>.<field>: field type must be INTEGER, STRING, LIST, DATE, BOOLEAN, PRICE or VERSION	অসমর্থিত ফিল্ড টাইপ।
400	an object tag needs at least one field; delete the object tag instead	আপনি শেষ ফিল্ডটি ডিলিট করার চেষ্টা করেছেন।
400	field is in use: ..., tag is in use: ...	ফিল্ড বা অবজেক্ট ট্যাগটি সেগমেন্ট, ইন-অ্যাপ, Customer Journey ক্যাম্পেইন বা অন্যান্য আইটেমে ব্যবহৃত হচ্ছে।
403	object tags are not enabled for the account	অ্যাকাউন্টের জন্য অবজেক্ট ট্যাগ সক্রিয় নয়।
403	a device API token cannot call this method, use an account API token	অনুরোধটি একটি ডিভাইস API টোকেন ব্যবহার করে।
404	tag not found	GET বা DELETE /api/tags/{name}: এমন কোনো ট্যাগ নেই, নামটি একটি ফিল্ড, অথবা অবজেক্ট ট্যাগ সক্রিয় নয়।
404	object tag not found, field not found	ফিল্ড মেথড: এমন কোনো অবজেক্ট ট্যাগ বা ফিল্ড নেই।
409	tag already exists	অবজেক্ট ট্যাগের নামসহ একটি ট্যাগ বিদ্যমান।
409	tag <object>.<field> already exists	ফিল্ডের সম্পূর্ণ নামসহ একটি ট্যাগ বিদ্যমান।

মান লিখুন

/setTags এবং /bulkSetTags দিয়ে অবজেক্ট ট্যাগের মান লিখুন। এই মেথডগুলি তাদের নিজস্ব প্রমাণীকরণ বজায় রাখে: /setTags Authorization: Token হেডারে একটি ডিভাইস API টোকেন নেয়, এবং /bulkSetTags auth-এ API অ্যাক্সেস টোকেন নেয়। একটি Object মান JSON অবজেক্ট হিসেবে এবং একটি ObjectList মান অবজেক্টের অ্যারে হিসেবে পাঠান:

উদাহরণ: /json/1.3/setTags

{
  "request": {
    "application": "XXXXX-XXXXX",
    "userId": "user_42",
    "tags": {
      "order": { "amount": 120, "status": "paid" },
      "orders": [
        { "amount": 120, "status": "paid" },
        { "amount": 50 }
      ]
    }
  }
}

আপনি যদি HWID দিয়ে মান সেট করেন, তাহলে এটি সেই ডিভাইসের ব্যবহারকারীর উপর সংরক্ষিত হয়।

প্রতিটি ফিল্ড তার টাইপের ফরম্যাটে একটি মান নেয়:

ফিল্ড টাইপ	উদাহরণ মান
INTEGER	120
STRING	"paid"
LIST	["gift", "express"]
DATE	"2026-10-02 22:11" (UTC), "2026-10-02", অথবা সেকেন্ডে Unix টাইমস্ট্যাম্প
BOOLEAN	true অথবা false
PRICE	19.95
VERSION	"1.0.0"

লেখা সম্পূর্ণ মান প্রতিস্থাপন করে

প্রতিটি লেখা অবজেক্ট ট্যাগের সংরক্ষিত মান প্রতিস্থাপন করে:

• নতুন মানে অনুপস্থিত একটি ফিল্ড ডিলিট হয়ে যায়। null হিসেবে পাঠানো ফিল্ডও ডিলিট হয়।
• null, [] অথবা "" সম্পূর্ণ মান ডিলিট করে।
• {} একটি Object ট্যাগের সমস্ত ফিল্ড ডিলিট করে।
• যে কী অবজেক্টের ফিল্ড নয়, তা বাদ দেওয়া হয়।
• যদি কোনো ফিল্ডের মান ফিল্ডের টাইপের সাথে না মেলে, তাহলে ট্যাগের সম্পূর্ণ মান প্রত্যাখ্যাত হয় এবং সংরক্ষিত মান আগের মতোই থাকে।

/setTags তার প্রতিক্রিয়ায় প্রত্যাখ্যাত মান জানায় না। /getTags দিয়ে ফলাফল পরীক্ষা করুন অথবা /bulkSetTags ব্যবহার করুন, যা প্রতিটি ট্যাগের জন্য একটি ফলাফল জানায়।

একটি Object-এর একটি ফিল্ড লিখুন

একটি Object ট্যাগের একটি ফিল্ড তার সম্পূর্ণ নাম দিয়ে লিখুন। increment এবং /setTags-এর অন্যান্য অপারেশন ফিল্ডে কাজ করে:

"tags": {
  "order.status": "shipped",
  "order.amount": { "operation": "increment", "value": 5 }
}

একটি ObjectList ট্যাগের ফিল্ড আলাদাভাবে লেখা যায় না, কারণ কোন এলিমেন্ট পরিবর্তন করতে হবে তা স্পষ্ট নয়। /setTags এমন মান উপেক্ষা করে। পরিবর্তে সম্পূর্ণ তালিকা পাঠান।

অবজেক্ট ট্যাগ স্বয়ংক্রিয়ভাবে তৈরি হয় না

বিদ্যমান নেই এমন ট্যাগের জন্য একটি অবজেক্ট বা অবজেক্টের অ্যারেসহ মান বাদ দেওয়া হয়। ট্যাগ স্বয়ংক্রিয়-সৃষ্টি অবজেক্ট ট্যাগ তৈরি করে না, তাই প্রথমে POST /api/tags দিয়ে স্কিমা তৈরি করুন।

bulkSetTags ফলাফল

detailed=true সহ, /bulkSetTags স্ট্যাটাস একটি অবজেক্ট ট্যাগের জন্য ok, tag not found এবং wrong value. expect :<type> ছাড়াও এই ফলাফলগুলির একটি ফেরত দেয়:

ফলাফল	কারণ
object tags are stored on the user only	অবজেক্ট ট্যাগটি User-specific নয়।
cannot load the fields of the object	Pushwoosh অবজেক্ট ট্যাগের ফিল্ডগুলি পড়তে পারেনি।
wrong value. expect an object (a map) or, for a list of objects, an array of maps	মানটি অবজেক্ট ট্যাগের সাথে খাপ খায় না, অথবা কোনো ফিল্ডের মান তার টাইপের সাথে মেলে না।
a field of a list of objects cannot be set on its own, set the whole list	মানটি একটি ObjectList ট্যাগের ফিল্ডে সেট করা হয়েছে।

মান পড়ুন

/getTags একটি Object মান JSON অবজেক্ট হিসেবে এবং একটি ObjectList মান অবজেক্টের অ্যারে হিসেবে ফেরত দেয়:

প্রতিক্রিয়া

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "result": {
      "order": { "amount": 120, "status": "paid" },
      "orders": [
        { "amount": 120, "status": "paid" },
        { "amount": 50 }
      ]
    }
  }
}

ফিল্ডের মান /getTags-এ সাধারণ ট্যাগের মানের মতোই ফেরত আসে: Date সেকেন্ডে Unix টাইমস্ট্যাম্প হিসেবে, Price "120.00"-এর মতো স্ট্রিং হিসেবে, এবং Boolean 1 বা 0 হিসেবে।

ফিল্ড অনুযায়ী সেগমেন্ট করুন

সেগমেন্টের শর্ত ফিল্ডে সেট করুন, অবজেক্ট ট্যাগে নয়। সেগমেন্টেশন ভাষায় একটি ফিল্ড হলো ডট-যুক্ত নামের একটি ট্যাগ, এবং এটি তার নিজস্ব টাইপের অপারেটর নেয়:

AT("XXXXX-XXXXX", "order.amount", gte, 100)

অবজেক্ট ট্যাগের উপর সরাসরি দেওয়া শর্ত object tag has no value of its own, use one of its fields দিয়ে ব্যর্থ হয়।

একটি ObjectList-এর শর্ত

একটি ObjectList ট্যাগের ফিল্ডের শর্ত একজন ব্যবহারকারীর সাথে মেলে যখন তালিকার অন্তত একটি এলিমেন্ট শর্তটি পূরণ করে। AND দিয়ে যুক্ত একই তালিকার ফিল্ডের শর্তগুলিকে একই এলিমেন্টের সাথে মিলতে হবে:

AT("XXXXX-XXXXX", "orders.amount", gte, 100) * AT("XXXXX-XXXXX", "orders.status", eq, "paid")

এই সেগমেন্টে সেই ব্যবহারকারীরা আছেন যাদের অন্তত একটি অর্ডার একই সাথে 100 বা তার বেশি এবং paid। একটি বড় অপরিশোধিত অর্ডার এবং একটি ছোট পরিশোধিত অর্ডারসহ ব্যবহারকারী মেলে না। OR দিয়ে যুক্ত শর্তগুলিকে একই এলিমেন্টের সাথে মিলতে হয় না। দুটি ভিন্ন তালিকার শর্ত প্রতিটি তালিকায় আলাদাভাবে পরীক্ষা করা হয়।

একটি ObjectList ট্যাগের ফিল্ডে কিছু অপারেটর ভিন্নভাবে কাজ করে:

• notset। তালিকার কোনো এলিমেন্টে এই ফিল্ডের মান নেই। তালিকা ছাড়া ব্যবহারকারীও মেলে।
• noteq। অন্তত একটি এলিমেন্টে এই ফিল্ডের মান আছে, এবং সেই মান প্রদত্ত মান থেকে ভিন্ন। ফিল্ড ছাড়া এলিমেন্ট গণনা করা হয় না। paid এবং new স্ট্যাটাসের অর্ডারসহ ব্যবহারকারী noteq "paid"-এর সাথে মেলে।
• List ফিল্ডে notin। কোনো এলিমেন্টে প্রদত্ত মানগুলির কোনোটিই নেই।
• অন্য টাইপের ফিল্ডে notin। অন্তত একটি এলিমেন্টে এই ফিল্ডের এমন মান আছে যা প্রদত্ত মানগুলির মধ্যে নেই।

List ফিল্ডে notset এবং notin AND দিয়ে যুক্ত অন্যান্য শর্তের সাথে একই এলিমেন্টে বাঁধা নয়।

অবজেক্ট ট্যাগসহ সেগমেন্ট এক্সপোর্ট করুন

/exportSegment অবজেক্ট ট্যাগের ফিল্ড এক্সপোর্ট করে:

• CSV। প্রতিটি ফিল্ড <object>.<field> নামের একটি আলাদা কলাম, এবং অবজেক্ট ট্যাগগুলি নিজেরা কোনো কলাম পায় না। একটি ObjectList-এর ফিল্ড সমস্ত এলিমেন্ট জুড়ে সব স্বতন্ত্র মান একটি JSON অ্যারে হিসেবে ধারণ করে, ঠিক একটি List ট্যাগের মতো: ["120","50"]।
• json এবং json_each_line। একটি Object ট্যাগের ফিল্ডগুলি <object>.<field> নামের আলাদা ট্যাগ হিসেবে আসে। একটি ObjectList ট্যাগ tags-এ একটি এন্ট্রি হিসেবে আসে, যার এলিমেন্টগুলি object_list.items-এ থাকে। প্রতিটি এলিমেন্ট তার ফিল্ডগুলি সংক্ষিপ্ত নামে তালিকাভুক্ত করে, এবং প্রতিটি ফিল্ড তার মান তার টাইপের নামের একটি কী-এর অধীনে বহন করে: integer, string, list, date, boolean, price অথবা version। Integer মান স্ট্রিং হিসেবে আসে:

{
  "name": "orders",
  "object_list": {
    "items": [
      { "fields": [{ "name": "amount", "integer": "120" }, { "name": "status", "string": "paid" }] },
      { "fields": [{ "name": "amount", "integer": "50" }] }
    ]
  }
}

যদি tagsList কোনো অবজেক্ট ট্যাগের নাম দেয়, তাহলে তার সমস্ত ফিল্ড এক্সপোর্ট করা হয়।