# Notify
`POST` `https://api.pushwoosh.com/messaging/v2/notify`
एक एकल संदेश बनाता है और शेड्यूल करता है।
## अनुरोध संरचना
अनुरोध बॉडी एक `NotifyRequest` है जिसमें ठीक दो में से एक प्रकार होता है:
- [`segment`](#notifysegment): सेगमेंट कोड द्वारा एक ऑडियंस सेगमेंट को लक्षित करें, या — पहले एक सेगमेंट बनाए बिना — एक [seglang](/hi/developer/api-reference/segmentation-filters-api/segmentation-language/) एक्सप्रेशन या एक संरचित फ़िल्टर एक्सप्रेशन।
- [`transactional`](#notifytransactional): hwids, यूज़र आईडी, पुश टोकन, या परीक्षण उपकरणों की एक स्पष्ट सूची में भेजें।
```json title="Shape"
{
"segment": { ... }, // या
"transactional": { ... },
"transaction_id": "unique-uuid"
}
```
| फ़ील्ड | प्रकार | विवरण |
|---|---|---|
| `transaction_id` | string | वैकल्पिक। अनुरोध के लिए इडेम्पोटेंसी कुंजी — `segment` और `transactional` दोनों के साथ काम करती है। 5 मिनट के भीतर समान `transaction_id` के साथ एक दोहराया गया कॉल डुप्लिकेट संदेश भेजने के बजाय मूल `message_code` लौटाता है। प्रति तार्किक भेजने के लिए एक UUID या किसी अन्य अद्वितीय मान का उपयोग करें। |
## NotifySegment
उन उपयोगकर्ताओं को लक्षित करता है जो एक ऑडियंस सेगमेंट या फ़िल्टर एक्सप्रेशन से मेल खाते हैं। `code`, `expression`, या `filter_expression` में से ठीक एक सेट करें। `expression` और `filter_expression` के लिए, पहले से कोई सेगमेंट बनाने की आवश्यकता नहीं है — एक्सप्रेशन का मूल्यांकन केवल इस भेजने के लिए इनलाइन किया जाता है।
| फ़ील्ड | प्रकार | विवरण |
|---|---|---|
| `schedule` | [`Schedule`](#schedule) | कब और कैसे भेजना है। आवश्यक। |
| `application` | string | [एप्लिकेशन कोड](/hi/developer/api-reference/api-identifiers/#application-code)। |
| `platforms` | array of [`Platform`](#platform-enum) | प्लेटफ़ॉर्म जिन्हें संदेश लक्षित करता है। |
| `code` | string | पहले से सहेजे गए सेगमेंट का [सेगमेंट कोड](/hi/developer/api-reference/api-identifiers/#segment--filter-code)। `expression` और `filter_expression` के साथ परस्पर अनन्य। |
| `expression` | string | [Seglang](/hi/developer/api-reference/segmentation-filters-api/segmentation-language/) एक्सप्रेशन, केवल इस भेजने के लिए मूल्यांकित — कोई सहेजा गया सेगमेंट आवश्यक नहीं है। `code` और `filter_expression` के साथ परस्पर अनन्य। |
| `filter_expression` | `FilterExpression` | `expression` के समान तर्क, एक seglang स्ट्रिंग के बजाय एक संरचित ऑब्जेक्ट के रूप में। `code` और `expression` के साथ परस्पर अनन्य। `FilterExpression` स्कीमा सार्वजनिक रूप से प्रलेखित नहीं है — यदि आपको संरचित रूप की आवश्यकता है तो इसे Pushwoosh समर्थन से अनुरोध करें। |
| `payload` | [`Payload`](/hi/developer/api-reference/messaging-api-v2/payload-reference/) | पुश / SMS / टेलीग्राम / काकाओ / लाइन / व्हाट्सएप / वाइबर / फेसबुक मैसेंजर पेलोड। `email_payload` के साथ परस्पर अनन्य। |
| `email_payload` | [`EmailPayload`](/hi/developer/api-reference/messaging-api-v2/email-payload-reference/) | ईमेल पेलोड। |
| `campaign` | string | इस संदेश को एट्रिब्यूट करने के लिए [अभियान कोड](/hi/developer/api-reference/api-identifiers/#campaign-code)। |
| `campaign_name` | string | इस संदेश का आंतरिक नाम, जो Message History में पंक्ति के शीर्षक के रूप में और उसके एक्सपोर्ट में दिखाया जाता है। ऊपर दिए `campaign` से इसका कोई संबंध नहीं है। यह संदेशों को समूहीकृत नहीं करता और डिलीवरी को प्रभावित नहीं करता। अधिकतम 255 वर्ण, ट्रिम किया गया। इसे छोड़ दें या खाली रहने दें, ताकि पंक्ति का शीर्षक पेलोड की अपनी सामग्री से बने। |
| `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` होता है, तो सेगमेंट द्वारा मेल खाने वाले प्रत्येक डिवाइस के बजाय प्रत्येक उपयोगकर्ता के सबसे हाल ही में सक्रिय डिवाइस (नवीनतम लास्ट एप्लिकेशन ओपन वाले) पर संदेश वितरित करता है। `platforms` तक सीमित: केवल उन प्लेटफ़ॉर्म पर डिवाइस पर विचार किया जाता है, और यदि किसी के पास लास्ट एप्लिकेशन ओपन डेटा नहीं है, तो भेजने को छोड़ने के बजाय पहले मेल खाने वाले डिवाइस का उपयोग किया जाता है। डिफ़ॉल्ट `false` (प्रत्येक डिवाइस पर भेजें)। |
| `control_group` | string | इस संदेश पर लागू किए जाने वाले इस भेजने के अपने होल्ड-आउट ग्रुप का कोड या नाम। यह तय नहीं करता कि कौन से [कंट्रोल ग्रुप](/hi/product/audience-data-and-segmentation/control-groups/) लागू होते हैं: इस फ़ील्ड के सेट होने या न होने से कोई फ़र्क नहीं पड़ता, एप्लिकेशन का हर सक्षम कंट्रोल ग्रुप यूज़र्स को मार्केटिंग भेजने से बाहर रखता है। `holdout_percentage` के साथ एक साथ उपयोग नहीं किया जा सकता। |
| `holdout_percentage` | uint32 | सेगमेंट के इस हिस्से (`1`–`20`) को एप्लिकेशन के सक्षम कंट्रोल ग्रुप के अतिरिक्त, केवल इसी भेजने तक सीमित एक कंट्रोल ग्रुप में निकालता है, ताकि साझा कंट्रोल ग्रुप को खर्च किए बिना किसी एक कैंपेन के प्रभाव को मापा जा सके। `0` (डिफ़ॉल्ट) इसे बंद रखता है। `control_group` के साथ एक साथ उपयोग नहीं किया जा सकता। |
होल्डआउट में चुने गए डिवाइस को डिलीवरी से उसी तरह बाहर रखा जाता है जैसे एप्लिकेशन के [कंट्रोल ग्रुप](/hi/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 | [एप्लिकेशन कोड](/hi/developer/api-reference/api-identifiers/#application-code)। |
| `platforms` | array of [`Platform`](#platform-enum) | प्लेटफ़ॉर्म जिन्हें संदेश लक्षित करता है। |
| `test_devices` | bool | यदि `true` है, तो केवल ऐप के परीक्षण उपकरणों पर भेजें। |
| `hwids` | `{ "list": [string, ...] }` | केवल इन [hwids](/hi/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid) पर भेजें। |
| `users` | `{ "list": [string, ...] }` | केवल इन [यूज़र आईडी](/hi/developer/pushwoosh-knowledge-hub/users-userids/) पर भेजें। |
| `push_tokens` | `{ "list": [string, ...] }` | केवल इन [पुश टोकन](/hi/developer/pushwoosh-knowledge-hub/device-identifiers/#push-token) पर भेजें। |
| `payload` | [`Payload`](/hi/developer/api-reference/messaging-api-v2/payload-reference/) | पुश / SMS / टेलीग्राम / काकाओ / लाइन / व्हाट्सएप / वाइबर / फेसबुक मैसेंजर पेलोड। |
| `email_payload` | [`EmailPayload`](/hi/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 | अद्वितीय [संदेश कोड](/hi/developer/api-reference/api-identifiers/#message-code)। इसे [`/getMessageDetails`](/hi/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` के लिए नीचे दी गई चेतावनी देखें। भविष्य में अधिकतम 30 दिन। |
| `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 में [सर्वश्रेष्ठ समय](/hi/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` | `best_time_to_send` किसी `transactional` भेजने पर सेट है। |
| `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"` है।
### प्लेटफ़ॉर्म एनम
`IOS`, `ANDROID`, `OSX`, `WINDOWS`, `AMAZON`, `SAFARI`, `CHROME`, `FIREFOX`, `IE`, `EMAIL`, `HUAWEI_ANDROID`, `SMS`, `WEB`, `KAKAO`, `TELEGRAM`, `LINE`, `WHATS_APP`, `VIBER`, `FB_MESSENGER`।
### MessageType एनम
- `MESSAGE_TYPE_UNSPECIFIED`: `MESSAGE_TYPE_MARKETING` के बराबर।
- `MESSAGE_TYPE_MARKETING`: कंट्रोल-ग्रुप फ़िल्टरिंग और फ़्रीक्वेंसी कैपिंग के अधीन।
- `MESSAGE_TYPE_TRANSACTIONAL`: कंट्रोल-ग्रुप फ़िल्टरिंग और फ़्रीक्वेंसी कैपिंग को छोड़ देता है। ऑर्डर पुष्टिकरण, OTPs, और इसी तरह के महत्वपूर्ण प्रवाहों के लिए उपयोग करें।
## संबंधित