# নোটিফাই
`POST` `https://api.pushwoosh.com/messaging/v2/notify`
একটি একক বার্তা তৈরি এবং সময়সূচী করে।
## রিকোয়েস্ট স্ট্রাকচার
রিকোয়েস্ট বডি একটি `NotifyRequest` যা দুটি ধরণের মধ্যে ঠিক একটি:
- [`segment`](#notifysegment): সেগমেন্ট কোড দ্বারা একটি অডিয়েন্স সেগমেন্টকে টার্গেট করুন, অথবা — প্রথমে একটি সেগমেন্ট তৈরি না করে — একটি [seglang](/bn/developer/api-reference/segmentation-filters-api/segmentation-language/) এক্সপ্রেশন বা একটি স্ট্রাকচার্ড ফিল্টার এক্সপ্রেশন ব্যবহার করুন।
- [`transactional`](#notifytransactional): hwids, ইউজার আইডি, পুশ টোকেন, বা টেস্ট ডিভাইসের একটি সুস্পষ্ট তালিকায় পাঠান।
```json title="Shape"
{
"segment": { ... }, // OR
"transactional": { ... },
"transaction_id": "unique-uuid"
}
```
| ফিল্ড | টাইপ | বর্ণনা |
|---|---|---|
| `transaction_id` | string | ঐচ্ছিক। রিকোয়েস্টের জন্য আইডমপোটেন্সি কী — `segment` এবং `transactional` উভয়ের সাথে কাজ করে। ৫ মিনিটের মধ্যে একই `transaction_id` দিয়ে পুনরায় কল করলে ডুপ্লিকেট বার্তা পাঠানোর পরিবর্তে আসল `message_code` ফেরত আসে। একটি UUID বা প্রতি লজিক্যাল সেন্ডের জন্য একটি অনন্য মান ব্যবহার করুন। |
## NotifySegment
যেসব ব্যবহারকারী একটি অডিয়েন্স সেগমেন্ট বা ফিল্টার এক্সপ্রেশনের সাথে মেলে তাদের টার্গেট করে। `code`, `expression`, বা `filter_expression`-এর মধ্যে ঠিক একটি সেট করুন। `expression` এবং `filter_expression`-এর জন্য, আগে থেকে কোনো সেগমেন্ট তৈরি করার প্রয়োজন নেই — এক্সপ্রেশনটি শুধুমাত্র এই সেন্ডের জন্য ইনলাইন মূল্যায়ন করা হয়।
| ফিল্ড | টাইপ | বর্ণনা |
|---|---|---|
| `schedule` | [`Schedule`](#schedule) | কখন এবং কিভাবে পাঠাতে হবে। আবশ্যক। |
| `application` | string | [অ্যাপ্লিকেশন কোড](/bn/developer/api-reference/api-identifiers/#application-code)। |
| `platforms` | array of [`Platform`](#platform-enum) | যেসব প্ল্যাটফর্মে বার্তাটি টার্গেট করা হয়েছে। |
| `code` | string | আগে থেকে সেভ করা একটি সেগমেন্টের [সেগমেন্ট কোড](/bn/developer/api-reference/api-identifiers/#segment--filter-code)। `expression` এবং `filter_expression`-এর সাথে পারস্পরিকভাবে এক্সক্লুসিভ। |
| `expression` | string | [Seglang](/bn/developer/api-reference/segmentation-filters-api/segmentation-language/) এক্সপ্রেশন, শুধুমাত্র এই সেন্ডের জন্য মূল্যায়ন করা হয় — কোনো সেভ করা সেগমেন্টের প্রয়োজন নেই। `code` এবং `filter_expression`-এর সাথে পারস্পরিকভাবে এক্সক্লুসিভ। |
| `filter_expression` | `FilterExpression` | `expression`-এর মতো একই লজিক, একটি seglang স্ট্রিং-এর পরিবর্তে একটি স্ট্রাকচার্ড অবজেক্ট হিসাবে। `code` এবং `expression`-এর সাথে পারস্পরিকভাবে এক্সক্লুসিভ। `FilterExpression` স্কিমা সর্বজনীনভাবে নথিভুক্ত নয় — যদি আপনার স্ট্রাকচার্ড ফর্মের প্রয়োজন হয় তবে Pushwoosh সাপোর্ট থেকে এটি অনুরোধ করুন। |
| `payload` | [`Payload`](/bn/developer/api-reference/messaging-api-v2/payload-reference/) | পুশ / SMS / টেলিগ্রাম / Kakao / LINE / WhatsApp / Viber / Facebook Messenger পেলোড। `email_payload`-এর সাথে পারস্পরিকভাবে এক্সক্লুসিভ। |
| `email_payload` | [`EmailPayload`](/bn/developer/api-reference/messaging-api-v2/email-payload-reference/) | ইমেল পেলোড। |
| `campaign` | string | এই বার্তাটিকে অ্যাট্রিবিউট করার জন্য [ক্যাম্পেইন কোড](/bn/developer/api-reference/api-identifiers/#campaign-code)। |
| `campaign_name` | string | এই বার্তাটির অভ্যন্তরীণ নাম, যা Message History-এ সারির শিরোনাম হিসেবে এবং এর এক্সপোর্টে দেখানো হয়। উপরের `campaign`-এর সাথে এর কোনো সম্পর্ক নেই। এটি বার্তা গ্রুপ করে না বা ডেলিভারি প্রভাবিত করে না। সর্বোচ্চ ২৫৫ অক্ষর, ছাঁটা হয়। এটি বাদ দিন বা খালি রাখুন, যাতে সারির শিরোনাম পেলোডের নিজস্ব কনটেন্ট থেকে আসে। |
| `frequency_capping` | [`FrequencyCapping`](#frequencycapping) | প্রতি-ব্যবহারকারী ফ্রিকোয়েন্সি সীমা। |
| `send_rate` | [`SendRate`](#sendrate) | সেন্ডের জন্য থ্রটলিং। |
| `message_type` | [`MessageType`](#messagetype-enum) | `MESSAGE_TYPE_MARKETING` (ডিফল্ট) বা `MESSAGE_TYPE_TRANSACTIONAL`। কন্ট্রোল-গ্রুপ ফিল্টারিং নিয়ন্ত্রণ করে। |
| `dynamic_content_placeholders` | map<string, string> | কন্টেন্টে প্লেসহোল্ডার প্রতিস্থাপন করে। |
| `meta_data` | object | ডাউনস্ট্রিম অ্যানালিটিক্সে ফরোয়ার্ড করা ফ্রি-ফর্ম মেটাডেটা। |
| `use_latest_user_device` | bool | যখন `true`, তখন বার্তাটি প্রতিটি ব্যবহারকারীর সবচেয়ে সম্প্রতি সক্রিয় ডিভাইসে (সর্বশেষ Last Application Open সহ ডিভাইস) পৌঁছে দেয়, সেগমেন্ট দ্বারা ম্যাচ করা প্রতিটি ডিভাইসের পরিবর্তে। `platforms`-এ স্কোপ করা: শুধুমাত্র সেই প্ল্যাটফর্মের ডিভাইসগুলি বিবেচনা করা হয়, এবং যদি কোনোটিতে Last Application Open ডেটা না থাকে, তাহলে সেন্ড ড্রপ করার পরিবর্তে প্রথম ম্যাচিং ডিভাইসটি ব্যবহার করা হয়। ডিফল্ট `false` (প্রতিটি ডিভাইসে পাঠান)। |
| `control_group` | string | এই বার্তায় প্রয়োগ করার জন্য সেন্ডের নিজস্ব হোল্ড-আউট গ্রুপের কোড বা নাম। এটি কোন [কন্ট্রোল গ্রুপ](/bn/product/audience-data-and-segmentation/control-groups/) প্রযোজ্য হবে তা সীমিত করে না: ফিল্ডটি সেট করা থাকুক বা না থাকুক, অ্যাপ্লিকেশনের প্রতিটি সক্রিয় কন্ট্রোল গ্রুপ মার্কেটিং সেন্ড থেকে ব্যবহারকারীদের হোল্ড আউট করে। `holdout_percentage`-এর সাথে একসাথে ব্যবহার করা যায় না। |
| `holdout_percentage` | uint32 | সেগমেন্টের এই অংশ (`1`–`20`) অ্যাপ্লিকেশনের সক্রিয় কন্ট্রোল গ্রুপগুলির পাশাপাশি শুধু এই সেন্ডের জন্য সীমিত একটি কন্ট্রোল গ্রুপে টেনে নেয়, যাতে শেয়ার করা কন্ট্রোল গ্রুপগুলি খরচ না করেই একটি একক ক্যাম্পেইনের প্রভাব পরিমাপ করা যায়। `0` (ডিফল্ট) এটি বন্ধ রাখে। `control_group`-এর সাথে একসাথে ব্যবহার করা যায় না। |
হোল্ডআউটে টেনে নেওয়া ডিভাইসগুলি অ্যাপ্লিকেশনের [কন্ট্রোল গ্রুপ](/bn/product/audience-data-and-segmentation/control-groups/#how-the-control-group-affects-message-delivery) যেভাবে বাদ দেয়, ঠিক সেভাবেই ডেলিভারি থেকে বাদ পড়ে। তাদের কাছে বার্তা পাঠানো হয় না, এবং ট্র্যাকিং লগ এই বাদ পড়াটিকে `Device is in control group` হিসেবে রেকর্ড করে। `MESSAGE_TYPE_TRANSACTIONAL` মানের `message_type` এই বাদ দেওয়া সম্পূর্ণভাবে এড়িয়ে যায়, ঠিক যেমন অ্যাপ্লিকেশনের কন্ট্রোল গ্রুপগুলির ক্ষেত্রে হয়।
`holdout_percentage`-কে `control_group`-এর সাথে একসাথে সেট করলে, অথবা `20`-এর বেশি `holdout_percentage` দিলে, `400` ফেরত আসে:
```json title="Invalid holdout_percentage"
{
"code": 3,
"message": "invalid argument",
"details": [
{
"@type": "type.googleapis.com/google.rpc.BadRequest",
"fieldViolations": [
{
"field": "holdout_percentage",
"description": "holdout_percentage and control_group are mutually exclusive"
}
]
},
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "InvalidHoldoutPercentage",
"domain": "api.pushwoosh.com",
"metadata": {}
}
]
}
```
### উদাহরণ: একটি সেগমেন্টে পাঠান
```bash
curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
-H "Authorization: Token YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"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" },
"message_type": "MESSAGE_TYPE_MARKETING"
}
}'
```
## NotifyTransactional
প্রাপকদের একটি সুস্পষ্ট তালিকায় পাঠায়।
| ফিল্ড | টাইপ | বর্ণনা |
|---|---|---|
| `schedule` | [`Schedule`](#schedule) | আবশ্যক। |
| `application` | string | [অ্যাপ্লিকেশন কোড](/bn/developer/api-reference/api-identifiers/#application-code)। |
| `platforms` | array of [`Platform`](#platform-enum) | যেসব প্ল্যাটফর্মে বার্তাটি টার্গেট করা হয়েছে। |
| `test_devices` | bool | যদি `true` হয়, শুধুমাত্র অ্যাপের টেস্ট ডিভাইসগুলিতে পাঠান। |
| `hwids` | `{ "list": [string, ...] }` | শুধুমাত্র এই [hwids](/bn/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid)-এ পাঠান। |
| `users` | `{ "list": [string, ...] }` | শুধুমাত্র এই [ইউজার আইডি](/bn/developer/pushwoosh-knowledge-hub/users-userids/)-তে পাঠান। |
| `push_tokens` | `{ "list": [string, ...] }` | শুধুমাত্র এই [পুশ টোকেন](/bn/developer/pushwoosh-knowledge-hub/device-identifiers/#push-token)-এ পাঠান। |
| `payload` | [`Payload`](/bn/developer/api-reference/messaging-api-v2/payload-reference/) | পুশ / SMS / টেলিগ্রাম / Kakao / LINE / WhatsApp / Viber / Facebook Messenger পেলোড। |
| `email_payload` | [`EmailPayload`](/bn/developer/api-reference/messaging-api-v2/email-payload-reference/) | ইমেল পেলোড। |
| `return_unknown_identifiers` | bool | যখন `true`, তখন রেসপন্সের `unknown_identifiers` তালিকায় এমন আইডেন্টিফায়ারগুলো থাকে যা পাওয়া যায়নি। |
| `use_latest_user_device` | bool | শুধুমাত্র যখন আপনি `users`-কে টার্গেট করেন তখন প্রযোজ্য। উপরের `NotifySegment`-এর মতো একই আচরণ — প্রতি ডিভাইসের পরিবর্তে প্রতি ব্যবহারকারী একটি বার্তা পৌঁছে দেয়, `platforms`-এ স্কোপ করা। ডিফল্ট `false`। |
| `campaign`, `campaign_name`, `frequency_capping`, `send_rate`, `message_type`, `dynamic_content_placeholders`, `meta_data` | | উপরে `NotifySegment` দেখুন। |
`test_devices`, `hwids`, `users`, এবং `push_tokens` পারস্পরিকভাবে এক্সক্লুসিভ। ঠিক একটি সেট করতে হবে।
### উদাহরণ: ইউজার আইডি দ্বারা ট্রানজ্যাকশনাল
```bash
curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
-H "Authorization: Token YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"transactional": {
"application": "XXXXX-XXXXX",
"platforms": ["IOS", "ANDROID"],
"users": { "list": ["user-123", "user-456"] },
"payload": {
"content": {
"localized_content": {
"en": { "ios": { "body": "Your order has shipped." } }
}
}
},
"schedule": { "at": "2026-05-01T12:00:00Z" },
"message_type": "MESSAGE_TYPE_TRANSACTIONAL",
"return_unknown_identifiers": true,
"use_latest_user_device": true
}
}'
```
## রেসপন্স
```json
{
"result": {
"message_code": "XXXXX-XXXXX-XXXXX",
"unknown_identifiers": []
}
}
```
| ফিল্ড | টাইপ | বর্ণনা |
|---|---|---|
| `message_code` | string | অনন্য [মেসেজ কোড](/bn/developer/api-reference/api-identifiers/#message-code)। এটি [`/getMessageDetails`](/bn/developer/api-reference/messages-api/#getmessagedetails) এবং মেসেজ পরিসংখ্যান এন্ডপয়েন্টের সাথে ব্যবহার করুন। |
| `unknown_identifiers` | array of string | অ্যাকাউন্টে পাওয়া যায়নি এমন আইডেন্টিফায়ার। শুধুমাত্র যখন `transactional` কাইন্ডে `return_unknown_identifiers: true` সেট করা হয়েছিল তখন পপুলেট করা হয়। |
## শেয়ার্ড টাইপ
### Schedule
```json
{
"at": "2026-05-01T12:00:00Z",
"follow_user_timezone": true,
"past_timezones_behaviour": "PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY"
}
```
| ফিল্ড | টাইপ | বর্ণনা |
|---|---|---|
| `at` | timestamp | পরম পাঠানোর সময় (RFC 3339)। যদি অতীতে হয়, Pushwoosh রিকোয়েস্ট পাওয়ার সময়টি বসিয়ে নেয়। `follow_user_timezone` সেট করা না থাকলে বা `false` হলে এর মানে বার্তাটি সবার কাছে অবিলম্বে চলে যায়। `follow_user_timezone: true`-এর ক্ষেত্রে নিচের সতর্কতা দেখুন। ভবিষ্যতে সর্বোচ্চ ৩০ দিন। |
| `after` | duration | `at`-এর বিকল্প। "এখন" থেকে এই অফসেটের পরে পাঠান (যেমন `"3600s"`)। সর্বোচ্চ 30 দিন। |
| `follow_user_timezone` | bool | যখন `true`, প্রতিটি ডিভাইস তার স্থানীয় টাইমজোনে `at` সময়ে বার্তাটি গ্রহণ করে। |
| `past_timezones_behaviour` | enum | `PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY` (ডিফল্ট), `PAST_TIMEZONES_BEHAVIOUR_DO_NOT_SEND`, বা `PAST_TIMEZONES_BEHAVIOUR_NEXT_DAY`। শুধুমাত্র যখন `follow_user_timezone` `true` হয় অথবা `best_time_to_send` সেট করা থাকে তখন অর্থপূর্ণ। |
| `best_time_to_send` | timestamp | ঐচ্ছিক। শুধু সেগমেন্ট সেন্ডের জন্য। প্রতিটি ডিভাইস এই সময় থেকে 24 ঘণ্টার মধ্যে তার নিজস্ব সেরা ঘণ্টায় বার্তাটি পায়। যেসব ডিভাইসের কোনো সেরা ঘণ্টা নেই, সেগুলি তাদের স্থানীয় টাইমজোনে `at` / `after`-এর তারিখ ও সময়ে এটি পায়। [পাঠানোর সেরা সময়](#best-time-to-send) দেখুন। |
#### পাঠানোর সেরা সময়
`best_time_to_send` হলো Control Panel-এর [সেরা সময়](/bn/product/messaging-channels/push-notifications/send-push-notifications/one-time-push/#best-time-paid-subscription-required) অপশনের API সমতুল্য। `at` / `after` সেই ডিভাইসগুলির জন্য ফলব্যাক নির্ধারণ করে, যাদের সেরা ঘণ্টা নির্ধারণের মতো যথেষ্ট ডেটা নেই। Pushwoosh `at` / `after`-এর UTC তারিখ ও সময় নেয় এবং প্রতিটি ডিভাইসের স্থানীয় টাইমজোনে সেই তারিখ ও সময়ে ফলব্যাক ডেলিভার করে, যেমনটি `follow_user_timezone: true`-এর ক্ষেত্রে হয়। এটি অন্তর্নিহিতভাবে প্রযোজ্য হয়: `follow_user_timezone` সেট না করে রাখুন, কারণ `true` হলে `BestTimeToSendWithUserTimezone` সহ প্রত্যাখ্যান করা হয়। নিচের উদাহরণে, সেরা ঘণ্টা নেই এমন ডিভাইসগুলি 1 মে স্থানীয় সময় 18:00-এ বার্তাটি পায়। যেখানে সেন্ড শুরু হওয়ার সময় সেই স্থানীয় সময় ইতিমধ্যে পেরিয়ে গেছে, সেখানে `past_timezones_behaviour` প্রযোজ্য হয়।
```json
{
"at": "2026-05-01T18:00:00Z",
"best_time_to_send": "2026-05-01T00:00:00Z"
}
```
নিচের সবগুলি শর্ত পূরণ না হলে Pushwoosh রিকোয়েস্টটি `400` দিয়ে প্রত্যাখ্যান করে:
- রিকোয়েস্টটি `segment` ধরন ব্যবহার করে। `transactional` সেন্ড `best_time_to_send` সমর্থন করে না।
- `follow_user_timezone` সেট করা নেই বা `false`।
- `at` / `after` থেকে পাওয়া সেন্ড টাইম ভবিষ্যতে। অতীতের `at`, `after: "0s"`, বা বাদ দেওয়া `after` "এখনই পাঠান" হিসেবে গণ্য হয় এবং প্রত্যাখ্যাত হয়।
- `best_time_to_send` পরবর্তী পূর্ণ ঘণ্টার আগে নয় এবং 30 দিনের বেশি পরে নয়। এটিকে নিচের দিকে পূর্ণ ঘণ্টায় রাউন্ড করা হয়।
- `at` / `after` থেকে পাওয়া সেন্ড টাইম `best_time_to_send` যোগ 24 ঘণ্টার পরে নয়।
ত্রুটির `reason` (`ErrorInfo` বিবরণে) ব্যর্থ হওয়া চেকটির নাম জানায়:
| `reason` | কারণ |
|---|---|
| `BestTimeToSendWithUserTimezone` | `follow_user_timezone` হলো `true`। |
| `BestTimeToSendTooEarly` | `best_time_to_send` পরবর্তী পূর্ণ ঘণ্টার আগে। |
| `BestTimeToSendTooFarInFuture` | `best_time_to_send` 30 দিনের বেশি পরে। |
| `SendDateAfterBestTimeToSend` | `at` / `after` হলো `best_time_to_send` যোগ 24 ঘণ্টার পরে। |
| `BestTimeToSendNotAllowed` | একটি `transactional` সেন্ডে `best_time_to_send` সেট করা হয়েছে। |
| `BestTimeToSendWithSendNow` | `at` / `after` "এখন" হিসেবে নির্ধারিত হয় (অতীতের `at` বা শূন্য `after`)। |
### FrequencyCapping
মার্কেটিং সেন্ডের জন্য প্রতি-ব্যবহারকারী ফ্রিকোয়েন্সি সীমা। ক্যাপিং নিষ্ক্রিয় করতে, `frequency_capping` সম্পূর্ণভাবে বাদ দিন, অথবা `days: 0` এবং `count: 0` একসাথে পাঠান।
```json
{ "days": 7, "count": 3, "exclude": false, "avoid": true }
```
- `days` (int, 1–30, বা `0` ক্যাপিং নিষ্ক্রিয় করতে): লুক-ব্যাক উইন্ডো। অবশ্যই `count`-এর সাথে একসাথে পাঠাতে হবে — যদি একটি `0` হয়, অন্যটিও `0` হতে হবে; একটি `0` এবং অন্যটি নন-জিরো পাঠালে `400` ফেরত আসে।
- `count` (int, 1 বা তার বেশি, বা `0` ক্যাপিং নিষ্ক্রিয় করতে): `days`-এর মধ্যে অনুমোদিত সর্বোচ্চ বার্তা। উপরের `days`-এর মতো একই পেয়ারিং নিয়ম।
- `exclude` (bool): যারা ইতিমধ্যে ক্যাপে পৌঁছেছে তাদের হার্ড-এক্সক্লুড করুন।
- `avoid` (bool): যারা ইতিমধ্যে ক্যাপে পৌঁছেছে তাদের সফট-এভয়েড করুন (তারা এখনও অ্যানালিটিক্সের জন্য গণনা করা হয়)।
### SendRate
```json
{ "value": 500, "bucket": "1s", "avoid": false }
```
সেন্ড থ্রটল করে। `value` হল প্রতি `bucket`-এ বার্তা; সাধারণ `bucket` হল `"1s"`।
### প্ল্যাটফর্ম enum
`IOS`, `ANDROID`, `OSX`, `WINDOWS`, `AMAZON`, `SAFARI`, `CHROME`, `FIREFOX`, `IE`, `EMAIL`, `HUAWEI_ANDROID`, `SMS`, `WEB`, `KAKAO`, `TELEGRAM`, `LINE`, `WHATS_APP`, `VIBER`, `FB_MESSENGER`।
### MessageType enum
- `MESSAGE_TYPE_UNSPECIFIED`: `MESSAGE_TYPE_MARKETING`-এর সমতুল্য।
- `MESSAGE_TYPE_MARKETING`: কন্ট্রোল-গ্রুপ ফিল্টারিং এবং ফ্রিকোয়েন্সি ক্যাপিং-এর অধীন।
- `MESSAGE_TYPE_TRANSACTIONAL`: কন্ট্রোল-গ্রুপ ফিল্টারিং এবং ফ্রিকোয়েন্সি ক্যাপিং এড়িয়ে যায়। অর্ডার কনফার্মেশন, OTP, এবং অনুরূপ ক্রিটিক্যাল ফ্লো-এর জন্য ব্যবহার করুন।
## সম্পর্কিত