तृतीय-पक्ष नोटिफिकेशन इंटीग्रेशन

त्वरित शुरुआत

Web Admin में लक्षित कंपनी से जुड़ा तृतीय-पक्ष ऐप बनाएँ। App ID और App Secret कॉपी करें; अंतिम परिणाम चाहिए तो वैकल्पिक Callback URL सेट करें।

Engine वैकल्पिक audience से चुने उपयोगकर्ताओं के लिए रिकॉर्ड बनाता है (default में कंपनी के सभी योग्य उपयोगकर्ता) तथा सिस्टम Push केवल योग्य पंजीकृत डिवाइसों पर आज़माता है।

Endpoint और प्रमाणीकरण

API वातावरण:

परीक्षण: https://aim-api-test.proton-system.com
उत्पादन: https://aim-api.proton-system.com

हर server-to-server JSON request में HTTP Basic Authentication के जरिए Authorization: Basic Base64(KEY:SECRET) भेजें, जहाँ KEY App ID और SECRET App Secret है:

Endpoint: POST /openapi/v1/notifications।

curl --request POST 'https://<your-engine-host>/openapi/v1/notifications' \
  --header 'Authorization: Basic <Base64(AppID:AppSecret)>' \
  --header 'Content-Type: application/json' \
  --data '{"requestId":"order-20260819-001","title":"ऑर्डर पूरा हुआ","body":"आपका ऑर्डर पूरा हो गया है।","imageUrls":["https://cdn.example.com/order/001-1.webp","https://cdn.example.com/order/001-2.webp"],"displayFields":[{"label":"स्टोर का नाम","value":"शाओ हान नूडल्स (वांगजिंग)"},{"value":"ORD-10086"}],"tags":["पूरा हुआ","मुख्य स्टोर"]}'

अनुरोध अनुबंध

फ़ील्ड सारांश

फ़ील्ड	आवश्यक	प्रकार	अर्थ
`requestId`	हाँ	string	भेजने वाले का अद्वितीय अनुरोध ID और idempotency key; trim करने के बाद खाली नहीं हो सकता।
`title`	हाँ	string	notification title; trim करने के बाद खाली नहीं हो सकता।
`body`	हाँ	string	notification body; trim करने के बाद खाली नहीं हो सकता।
`imageUrls`	नहीं	string[]	detail में क्रम से दिखने वाले चित्र URL।
`displayFields`	नहीं	object[]	detail में क्रम से दिखने वाले अतिरिक्त text field।
`tags`	नहीं	string[]	केवल detail में क्रम से दिखने वाले plain text tag।
`audience`	नहीं	object	users या company roles तक सीमित करता है; छोड़ने पर पूरी योग्य कंपनी।

चित्र: `imageUrls`

चित्र न हों तो field छोड़ें, null या [] भेजें; अन्यथा क्रम में 1-9 URL भेजें।
हर URL trim होता है, अद्वितीय और username/password के बिना पूर्ण HTTPS URL होना चाहिए।
हर URL अधिकतम 2048 Unicode अक्षर का हो सकता है। एक अमान्य URL पूरा अनुरोध अस्वीकार करता है।
Engine URL रखता है, लेकिन चित्र fetch, probe, proxy या cache नहीं करता।

Detail field: `displayFields`

Subfield	आवश्यक	सीमा	प्रदर्शन
`label`	नहीं	trim के बाद खाली नहीं; अधिकतम 32 Unicode अक्षर	field name।
`value`	हाँ	trim के बाद खाली नहीं; अधिकतम 256 Unicode अक्षर	field value।

{
  "displayFields": [
    { "label": "स्टोर", "value": "Little Han Noodles (Wangjing)" },
    { "value": "ORD-10086" }
  ]
}

field छोड़ना, null या [] भेजना कोई अतिरिक्त पंक्ति नहीं दर्शाता; अधिकतम 10 object हैं।
label न होने या null होने पर value पूरी चौड़ाई की एक पंक्ति में दिखता है।
सामग्री हमेशा plain text है; HTML, Markdown, link, nested data, type और style समर्थित नहीं हैं।

विवरण टैग: `tags`

tag न हों तो field छोड़ें, null या [] भेजें; अन्यथा display order में अधिकतम 8 strings भेजें।
हर tag trim होकर 1-20 Unicode अक्षर का होना चाहिए। खाली, non-string, बहुत लंबा या trim के बाद duplicate value पूरे request को INVALID_REQUEST करता है।
Tag non-interactive plain text हैं; वे केवल notification detail में दिखते हैं और क्रम बनाए रखते हैं।

प्राप्तकर्ता: `audience`

`type`	Selector	ID का अर्थ
`USERS`	`userIds`	कंपनी सदस्य ID
`ROLES`	`roles`	CompanyRole ID; किसी भी role के योग्य member को संदेश मिलता है।

Web Admin की कंपनी सदस्य सूची से कंपनी सदस्य ID कॉपी करें। सदस्य उसी कंपनी का होना चाहिए जिससे third-party application जुड़ा है।

{
  "audience": { "type": "USERS", "userIds": ["companyMemberId"] }
}

{
  "audience": { "type": "ROLES", "roles": ["roleId"] }
}

audience छोड़ने या null भेजने पर जुड़ी कंपनी के सभी योग्य सक्रिय users लक्ष्य होते हैं।
संबंधित सूची में 1-100 raw string हों; ID trim होते हैं, खाली मान हटते हैं और set को deduplicate व sort किया जाता है।
अनुपस्थित, disabled, deleted या दूसरी कंपनी के ID अनदेखे होते हैं; बाकी valid target को संदेश मिलता है।
कोई valid target न बचे तो भी अनुरोध recipientCount=0 के साथ पूरा होता है; पूरी कंपनी को fallback नहीं होता।
दूसरा selector छोड़ा या null किया जा सकता है। अन्य मिश्रण, अज्ञात type/field, अनुपस्थित या खाली सूची, non-string item और 100 से अधिक item पर INVALID_REQUEST मिलता है।

सीमाएँ और idempotency

पूरा body अधिकतम 256 KiB है। requestId, title, body क्रमशः 128, 100 और 1000 Unicode अक्षर तक हैं।
हर App ID के लिए प्रति मिनट 10 और प्रति घंटा 100 अनुरोध की सीमा है।
समान requestId और बराबर normalized content संग्रहीत परिणाम लौटाते हैं। चित्र, fields और tags में क्रम मायने रखता है; audience set में नहीं।
अलग content पर IDEMPOTENCY_CONFLICT मिलता है। अंतिम status SUCCESS, PARTIAL_SUCCESS या FAILED हो सकता है।

स्वीकृति प्रतिक्रिया

मान्य अनुरोध HTTP 202 लौटाता है:

{
  "requestId": "order-20260819-001",
  "notificationId": "00000000-0000-0000-0000-000000000001",
  "status": "ACCEPTED"
}

ACCEPTED का अर्थ केवल यह है कि Engine ने अनुरोध वितरण के लिए सहेजा है; यह APNs/FCM या डिवाइस पर प्रदर्शन की पुष्टि नहीं है।

Callback परिणाम

Callback URL सेट होने पर Engine अंतिम परिणाम भेजता है:

{
  "requestId": "order-20260819-001",
  "status": "PARTIAL_SUCCESS",
  "recipientCount": 8,
  "pushAcceptedCount": 1,
  "pushFailedCount": 1
}

recipientCount सूचना केंद्र के प्राप्तकर्ता उपयोगकर्ताओं की संख्या है। pushAcceptedCount और pushFailedCount Push Outbox बैच की संख्याएँ हैं; ये उपयोगकर्ता या डिवाइस की संख्या अथवा सिस्टम बैनर पहुँचने का प्रमाण नहीं हैं।

Callback परीक्षण

एडमिन पैनल से हर Callback परीक्षण एक अलग प्रोब इवेंट भेजता है:

{
  "requestId": "callback-test-<unique-id>",
  "status": "SUCCESS",
  "recipientCount": 1,
  "pushAcceptedCount": 1,
  "pushFailedCount": 0,
  "test": true
}

जब test का मान true हो, संरचना जाँचकर 2xx लौटाएँ, लेकिन प्रोब को भेजे गए किसी नोटिफिकेशन अनुरोध से न जोड़ें और व्यावसायिक डिलीवरी स्थिति न बदलें। गिनतियाँ स्थिर परीक्षण मान हैं; वे वास्तविक प्राप्तकर्ता या Push Outbox बैच नहीं हैं।

अंतिम status SUCCESS, PARTIAL_SUCCESS या FAILED होता है। किसी भी 2xx से पुष्टि करें।

अन्यथा 1 मिनट, 5 मिनट, 30 मिनट, 2 घंटे, 6 घंटे और 24 घंटे बाद पुनः प्रयास होता है। अभी HMAC हस्ताक्षर नहीं है: HTTPS अनिवार्य करें, गैर-परीक्षण परिणामों के requestId मिलाएँ, पहुँच सीमित रखें और Callback को idempotent रूप से संभालें।

त्रुटि संदर्भ

HTTP	Code	अर्थ
400	`INVALID_REQUEST`	Content-Type, JSON, आकार या फ़ील्ड अमान्य हैं।
401	`INVALID_APP_CREDENTIALS`	App ID या App Secret अमान्य है।
403	`APPLICATION_INACTIVE`	ऐप या कंपनी निष्क्रिय है।
409	`IDEMPOTENCY_CONFLICT`	requestId अलग सामग्री के साथ दोहराया गया।
429	`RATE_LIMITED`	ऐप की दर सीमा पार हुई।
503	`NOTIFICATION_UNAVAILABLE`	सेवा अस्थायी रूप से उपलब्ध नहीं है।

सुरक्षा और वितरण सीमा

App ID और App Secret केवल server-to-server क्रेडेंशियल हैं। इन्हें browser, mobile app, सार्वजनिक repository, URL या client storage में न रखें। रिसाव पर App Secret रीसेट करें।
निजी target ID कभी application logs में नहीं लिखे जाते। निजी selector और target ID GraphQL, Push, Callback, realtime या navigation payload में भी नहीं जाते।
audience न होने पर कंपनी के सभी योग्य सक्रिय उपयोगकर्ता शामिल होते हैं; audience होने पर केवल resolve हुए valid target। हर valid recipient को सूचना केंद्र रिकॉर्ड मिलता है और वह recipientCount में गिना जाता है।
सिस्टम Push केवल उस सक्रिय PushInstallation पर आज़माया जाता है जो BUSINESS श्रेणी की अनुमति देता है; फिर भी हर डिवाइस पर सिस्टम बैनर की गारंटी नहीं है।
पूरी imageUrls सूची केवल अधिकृत notification detail में उपलब्ध रहती है, लेकिन native system banner में चित्र दिखाने के लिए Engine imageUrls का पहला URL APNs/FCM को भेज सकता है। displayFields और tags Push या Callback में नहीं जाते और non-interactive plain text रहते हैं; इनमें secret, access token, payment data या sensitive value न रखें।
title और body चित्रों के बिना भी पूर्ण और समझने योग्य होने चाहिए। चित्र डाउनलोड या रेंडर विफल होने पर accepted, Callback या Push status नहीं बदलता।
Mobile client प्रति चित्र अधिकतम 5 MiB स्वीकार करता है और पूरी चित्र डाउनलोड प्रक्रिया की समय-सीमा 10 सेकंड है। Client 3xx redirect का अनुसरण नहीं करता, इसलिए हर URL को चित्र सीधे लौटाना होगा।
Mobile client हर चित्र सीधे public CDN से डाउनलोड करता है। authentication या Cookie रहित URL दें, उन्हें कम से कम 90 दिन उपलब्ध रखें और ध्यान रखें कि CDN को उपयोगकर्ता का IP, request time और User-Agent मिलेगा।
स्थिर ऐतिहासिक प्रदर्शन के लिए immutable object URL इस्तेमाल करें।