SMS और समर्थित MMS भेजें

भेजने से पहले

अपने खाते के लिए कॉन्फ़िगर किए गए प्रेषक नंबर से SMS या समर्थित MMS भेजें। यह वास्तविक सेवा में की जाने वाली कार्रवाई है, जिससे प्राप्तकर्ताओं से संपर्क हो सकता है और शुल्क लग सकता है। केवल अधिकृत प्राप्तकर्ताओं को स्वीकृत प्रकार के संदेश भेजें; नीचे दिए गए उदाहरण के नंबर और संदर्भ काल्पनिक हैं।

आपके खाते के लिए आउटबाउंड संदेश भेजने की स्वीकृति और प्रेषक, देश तथा संदेश ट्रैफ़िक से संबंधित लागू अनुमतियाँ आवश्यक हैं। व्यक्तिगत/उपभोक्ता उपयोगकर्ता के सीधे क्रेडेंशियल इस API के लिए पात्र नहीं हैं। स्वीकृत समर्पित API क्रेडेंशियल के लिए पात्रता की अलग प्रक्रिया है; मोबाइल P2P प्रेषकों को अतिरिक्त P2P और अमेरिका/कनाडा संबंधी अनुमतियों की आवश्यकता हो सकती है। API क्रेडेंशियल को किसी भी प्रकार के संदेश भेजने की स्वतः अनुमति मानने के बजाय, MultiTEL से खाते के सही सेटअप की पुष्टि करें।

भेजने का अनुरोध

सक्षम API खाते के अनुमत स्रोत IP पते से HTTPS पर प्रमाणीकरण करें। क्रेडेंशियल को सर्वर पर गोपनीय जानकारी के सुरक्षित भंडार में रखें। फ़ॉर्म-एन्कोडेड फ़ील्ड के साथ POST का उपयोग करें, या कोई फ़ॉर्म अथवा क्वेरी फ़ील्ड न दिए जाने पर JSON ऑब्जेक्ट का उपयोग करें। क्रेडेंशियल या संदेश का पाठ URL में न डालें।

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'from=12025550123' \
  --data-urlencode 'to=12025550124' \
  --data-urlencode 'text=Your requested update is ready.' \
  --data-urlencode 'reference=order-update-example' \
  https://api.multitel.net/v3/sendsms

JSON ऐरे के लिए to में वास्तविक ऐरे का उपयोग करें; फ़ॉर्म फ़ील्ड के अंदर JSON ऐरे की स्ट्रिंग न डालें। शुरुआती एकीकरण परीक्षण में केवल एक प्राप्तकर्ता को संदेश भेजें। समूह और MMS का समर्थन मार्ग के अनुसार अलग होता है, इसलिए उनका उपयोग करने से पहले समर्थित संयोजन की पुष्टि करें।

पूरा परिणाम पढ़ें

केवल उदाहरण के लिए चुने गए फ़ील्ड दिखाए गए हैं; दिखाई गई लागत मूल्य प्रस्ताव नहीं है।

{
  "status": {
    "code": "200",
    "msg": ""
  },
  "response": {
    "sms_log_id_ori": 42,
    "to": "12025550124",
    "from": "12025550123",
    "status": "Success",
    "message": "Message queued",
    "causecode": 0,
    "uniqueid": "fixture-message",
    "cost": "$0.0120",
    "carrier_fee_usd": "0.0020000000",
    "chars": 31,
    "parts": 1,
    "encoding": "GSM-7",
    "permsg": "$0.0120",
    "pid": "fixture-reference"
  }
}

HTTP स्थिति, JSON के status.code और प्रतिक्रिया के status/message को एक साथ जाँचें। परिणाम कोड स्ट्रिंग हो सकते हैं। सहायता के दौरान संबंधित रिकॉर्ड का मिलान करने के लिए sms_log_id_ori और लौटाए गए संदेश/संदर्भ के मान सहेजें। पुराने uniqueid और pid के मान मार्ग के अनुसार बदलते हैं; उनके प्रारूप का अनुमान न लगाएँ और न ही उन्हें क्लाइंट की इडेम्पोटेंसी के टोकन मानें।

Success या Message queued सामान्यतः चुने गए मार्ग द्वारा अनुरोध स्वीकार किए जाने को दर्शाता है, किसी व्यक्ति के हैंडसेट पर संदेश मिलने को नहीं। sent जैसी प्रारंभिक कॉलबैक स्थिति अपने आप अंतिम डिलीवरी की पुष्टि नहीं करती।

संदेश खंड और शुल्क

उपयोग करें: SMS की लंबाई का विश्लेषण — भेजने से पहले पूरे अंतिम पाठ पर। SMS की कीमतें गंतव्य और खाते की सेवा पर निर्भर करती हैं; लागू कैरियर शुल्क प्रत्येक संदेश खंड के लिए जोड़े जाते हैं। भेजने की प्रक्रिया प्राप्तकर्ताओं के लिए कीमतों और लागू शुल्कों को जोड़ती है, फिर इस योग को गणना की गई SMS खंडों की संख्या से गुणा करती है। इस गणना में MMS अनुरोध को एक संदेश माना जाता है।

पुरानी प्रतिक्रिया में cost और permsg मुद्रा राशि की स्वरूपित स्ट्रिंग हैं। carrier_fee_usd कैरियर शुल्क वाले हिस्से को USD में बताता है और यह भेजने की गणना की गई कुल राशि में पहले से शामिल है; इसे दूसरी बार न जोड़ें। अपने खाते के लिए वास्तविक कीमतों और मार्ग की उपलब्धता की जाँच करना आवश्यक है। यह अनुरोध केवल कीमत जानने की कार्रवाई नहीं है।

समीक्षा किया गया कोड कैरियर के माध्यम से सफलतापूर्वक भेजने की प्रक्रिया के बाद खाते से राशि काटता है, लेकिन कैरियर की स्वीकृति, स्थानीय रूप से डेटा सहेजना और बिलिंग एक ही लेनदेन का हिस्सा नहीं हैं। अपस्ट्रीम अनुरोध स्वीकार किए जाने के बाद भी त्रुटि हो सकती है या समय सीमा समाप्त हो सकती है। क्लाइंट के लिए कोई इडेम्पोटेंसी कुंजी उपलब्ध नहीं कराई गई है: उसी संदर्भ को दोहराने से संदेश फिर भेजा जा सकता है और दोबारा शुल्क लग सकता है।

स्थानीय डिलीवरी और मिश्रित परिणाम

स्थानीय रूप से होस्ट किए गए नंबरों को बाहरी कैरियर से संदेश भेजे बिना MultiTEL के इनबाउंड संदेश प्रवाह में accepted किया जा सकता है। केवल स्थानीय प्राप्तकर्ताओं वाले अनुरोध की प्रतिक्रिया में accepted, message_id, provider और delivery_status शामिल हो सकते हैं। स्थानीय स्वीकृति इस बात की गारंटी नहीं है कि प्राप्तकर्ता के लिए कॉन्फ़िगर किया गया अग्रेषण गंतव्य सफलतापूर्वक काम कर पाया।

local_delivery_results और partial मौजूद होने पर उनकी जाँच करें। किसी प्राप्तकर्ता के लिए accepted true दिख सकता है, जबकि उसका अग्रेषण परिणाम असफल हो। मिश्रित अनुरोध में कैरियर वाले प्राप्तकर्ता accepted हो सकते हैं और स्थानीय हिस्सा असफल हो सकता है। पूरे बैच को अपने आप दोबारा भेजने का प्रयास न करें: पहले प्रत्येक प्राप्तकर्ता के परिणाम का मिलान करें।

इस प्रक्रिया में केवल स्थानीय प्राप्तकर्ताओं वाले अनुरोध की स्वीकृति पर आउटबाउंड लागत शून्य बताई जाती है, जबकि प्राप्तकर्ताओं को उनके सामान्य इनबाउंड संदेश शुल्क फिर भी लग सकते हैं। शून्य आउटबाउंड लागत को इस बात की गारंटी न मानें कि किसी भी खाते पर शुल्क नहीं लगेगा।

कॉलबैक और संबंधित रिकॉर्ड का मिलान

notifyurl दिए जाने पर प्रारंभिक कॉलबैक में status एनवेलप और प्रतिक्रिया फ़ील्ड होते हैं, जिनमें message_id, reference, from, to, status, status_text, error_code, timestamp और accepted शामिल हैं। स्थानीय परिणाम भी मौजूद हो सकते हैं। API क्रेडेंशियल या अनावश्यक संदेश सामग्री लॉग किए बिना संबंधित रिकॉर्ड का मिलान करने वाली जानकारी सहेजें।

यह हैंडलर उस प्रारंभिक कॉलबैक में डिजिटल हस्ताक्षर का फ़ील्ड नहीं जोड़ता। बिना सत्यापन वाले कॉलबैक को किसी अन्य कार्रवाई के लिए अपने आप में पर्याप्त प्राधिकरण न मानें। अपने खाते के लिए समर्थित एकीकरण/वेबहुक सेटअप की जानकारी लें और अनिश्चित परिणामों का मिलान पोर्टल के रिकॉर्ड या सहायता टीम के माध्यम से करें। यह न मानें कि कॉलबैक केवल एक बार या अंतिम डिलीवरी के क्रम में आते हैं।

विफलताएँ और सुरक्षित सुधार

सत्यापन विफल होने पर API कोड 403 का उपयोग किया जा सकता है। खाते की स्वीकृति, P2P और देश संबंधी नीतियों के कारण अस्वीकृति पर भी HTTP 403 सेट किया जा सकता है और मशीन द्वारा पढ़ा जा सकने वाला response.code शामिल हो सकता है। अनुरोध दर की सीमा लागू होने पर दोबारा प्रयास की जानकारी के साथ 429 का उपयोग किया जा सकता है। नीति उपलब्ध न होने या संदेश भेजने/स्थानीय रूप से डेटा सहेजने में विफलता पर 503 या 500 का उपयोग किया जा सकता है; पुराने व्यवहार में अपर्याप्त शेष राशि पर भी 500 लौटाया जा सकता है।

429 मिलने पर Retry-After और दिए गए किसी भी response.retry_after मान का पालन करें। खाते, प्रेषक, देश या प्राप्तकर्ता से संबंधित अस्वीकृति होने पर दोबारा प्रयास करने से पहले उसका कारण ठीक करें। समय सीमा समाप्त होने या भेजने का परिणाम स्पष्ट न होने पर अनुरोध का समय, संदर्भ और लौटाए गए पहचानकर्ता सहेजें, पोर्टल की जाँच करें और दोबारा भेजने से पहले सहायता टीम से संपर्क करें। केवल लॉग प्रविष्टि न मिलना इस बात का प्रमाण नहीं है कि किसी कैरियर ने अनुरोध स्वीकार नहीं किया।