SMS आँकड़े API

Metrics डैशबोर्ड का हर मान SMS आँकड़े API से आता है। इन्हीं एग्रीगेट का उपयोग आप डैशबोर्ड, डेटा वेयरहाउस या हेल्थ चेक में कर सकते हैं। ये एंडपॉइंट केवल पढ़ने के लिए हैं और वर्कस्पेस तक सीमित हैं। इनके लिए ऐसी API कुंजी चाहिए जिसके पास sms स्कोप की पढ़ने की अनुमति हो। समान अवधि और फ़िल्टर के लिए प्रतिक्रिया डैशबोर्ड से मेल खाती है।

टाइप किए गए मेथड TypeScript, Python, PHP और Go SDK में sms.stats के अंतर्गत उपलब्ध हैं। bird CLI इन्हें bird sms stats के रूप में उपलब्ध कराता है, और एजेंट इन तक sms_stats_* MCP टूल के ज़रिए पहुँचता है। पूरे अनुरोध और प्रतिक्रिया स्कीमा API संदर्भ में हैं।

एग्रीगेट और टाइम सीरीज़

डैशबोर्ड के ऊपरी हिस्से के लिए तीन एंडपॉइंट हैं:

• GET /v1/sms/stats/summary पूरी अवधि के लिए एक एग्रीगेट पंक्ति लौटाता है: लाइफ़साइकल गिनतियाँ (accepted, sent, delivered, undelivered, failed, rejected, expired), इनसे निकले delivery_rate और failure_rate, तथा प्रोसेसिंग, डिलीवरी और कुल विलंब के पर्सेंटाइल (p50, p95, p99)। compare=previous_period पास करने पर प्रतिक्रिया में इससे ठीक पहले की बराबर लंबाई वाली अवधि और उसकी तुलना में बदलाव भी शामिल होता है।
• GET /v1/sms/stats/daily और GET /v1/sms/stats/hourly लाइफ़साइकल गिनतियाँ प्रति दिन या प्रति घंटे एक पंक्ति के रूप में लौटाते हैं। दरें और विलंब पूरी अवधि के आँकड़े हैं, इसलिए इन्हें हर बकेट से नहीं, बल्कि /summary से पढ़ें।

दरें दशमलव अनुपात के रूप में लौटाई जाती हैं, इसलिए 0.9739 का delivery_rate 97.39% है। जिस दर का हर शून्य हो, वह null होती है। इसी कारण जिस अवधि में कुछ भी स्वीकार नहीं हुआ, वह 0 दिखाने के बजाय delivery_rate रिपोर्ट करती है। आँकड़े संदेश के भेजने के समय पर आधारित होते हैं। कल स्वीकार हुए संदेश की डिलीवरी आज पुष्ट होने पर वह कल में गिनी जाती है। इसलिए हाल की अवधि में डिलीवरी रिपोर्ट आते रहने तक delivered कम दिखता है, अतः पिछले कुछ घंटों के आँकड़ों को अंतिम नहीं, अस्थायी मानें।

गिनतियाँ अनुमानित अलग-अलग-संदेश एग्रीगेशन से बनती हैं। आगे बढ़ते हुए एक संदेश एक से अधिक लाइफ़साइकल स्टेटस में गिना जा सकता है। इसलिए स्टेटस गिनतियाँ परस्पर अनन्य नहीं हैं, और इन्हें जोड़कर कुल संदेश संख्या नहीं निकालनी चाहिए। आउटबाउंड दर के हर के रूप में स्वीकार किए गए संदेशों का उपयोग करें। ये परिचालन एग्रीगेट बिलिंग लेजर नहीं हैं; मिलान के लिए संदेश और बिलिंग रिकॉर्ड का उपयोग करें।

अवधि चुनना

from और to या तो कैलेंडर दिन (YYYY-MM-DD) लेते हैं या RFC 3339 इंस्टेंट, और कौन-सा एंडपॉइंट कौन-से रूप स्वीकार करता है, यह अलग-अलग है:

इंस्टेंट सीमाएँ घंटे के स्तर पर होती हैं, इसलिए रोलिंग 24 घंटे की विंडो एक ही अनुरोध में मिल जाती है। /summary पर दिन और इंस्टेंट को मिलाने पर 422 मिलता है।

सीमाओं और छोड़े गए डिफ़ॉल्ट मानों की गणना UTC के बजाय किसी दूसरे ज़ोन में करने के लिए timezone को America/New_York जैसे IANA पहचानकर्ता पर सेट करें। जब timezone सेट हो, तब Bird इंस्टेंट सीमाओं में +05:45 जैसे संख्यात्मक UTC ऑफ़सेट अस्वीकार करता है। इसके बजाय Z इंस्टेंट या कैलेंडर दिन इस्तेमाल करें।

ब्रेकडाउन

सात एंडपॉइंट उन्हीं डिलीवरी आँकड़ों को एक-एक आयाम के अनुसार बाँटते हैं:

• संदेश कहाँ गया: /countries (गंतव्य देश) और /carriers (वह कैरियर जिसने उसे संभाला)।
• आपने क्या भेजा: /originators (वह प्रेषक पता जिससे संदेश भेजा गया), /categories और /tags।
• संदेश का अंत कैसे हुआ: /statuses (गतिविधि वाली हर लाइफ़साइकल स्थिति के लिए एक पंक्ति) और /error-codes।

ये सभी /v1/sms/stats/ के अंतर्गत हैं। देश, कैरियर, ओरिजिनेटर, श्रेणी, टैग और त्रुटि-कोड की पंक्तियाँ sort के अनुसार क्रमबद्ध होती हैं और limit से सीमित होती हैं (डिफ़ॉल्ट 50, अधिकतम 200)। इनकी प्रतिक्रियाओं में total शामिल होता है, यानी विंडो में अलग-अलग मानों की संख्या, जिससे आप पहचान सकते हैं कि परिणाम सीमित हुआ है या नहीं। जिन पंक्तियों का सॉर्ट मेट्रिक शून्य हर वाली दर है, वे सबसे अंत में आती हैं। स्थिति ब्रेकडाउन में अधिकतम सात पंक्तियाँ होती हैं, और उसमें sort या limit पैरामीटर नहीं होते।

छह क्रमबद्ध ब्रेकडाउन हर पंक्ति के लिए एक छोटी सीरीज़ भी लौटा सकते हैं। include_trend=true सेट करें और trend_grain=daily या hourly चुनें। ट्रेंड के लिए limit का मान 50 या उससे कम होना चाहिए, और विंडो दैनिक बकेट के लिए अधिकतम 90 दिन या प्रति घंटा बकेट के लिए अधिकतम 720 घंटे की होनी चाहिए।

sort का डिफ़ॉल्ट वॉल्यूम ब्रेकडाउन पर accepted और /error-codes पर failed है। /error-codes एंडपॉइंट कच्चे कैरियर कोड के बजाय Bird के सामान्यीकृत विफलता कारण के अनुसार समूह बनाता है। इसका मान GET /v1/sms/messages पर error_code फ़िल्टर के साथ भी काम करता है, जिससे किसी पंक्ति को उसके संदेशों से जोड़ा जा सकता है।

/tags केवल टैग किए गए संदेश गिनता है, और कई टैग वाला संदेश हर टैग के अंतर्गत एक बार गिना जाता है। इसलिए इसकी पंक्तियों का योग अवधि के कुल योग के बराबर नहीं होता। /summary इस्तेमाल करने के बजाय एक /tags परिणाम का मिलान किसी दूसरे परिणाम से करें।

/statuses पूरे डिलीवरी ब्लॉक के बजाय एक स्टेटस और गिनती लौटाता है। हर पंक्ति उन संदेशों को गिनती है जो उस लाइफ़साइकल स्टेटस में देखे गए; एक संदेश कई पंक्तियों में दिख सकता है।

प्राप्त संदेश

/v1/sms/stats/inbound/ के अंतर्गत छह और एंडपॉइंट यह गिनते हैं कि आपके नंबरों ने क्या प्राप्त किया, न कि आपने क्या भेजा: कुल योग और सीरीज़ के लिए /summary, /daily और /hourly, तथा ब्रेकडाउन के लिए /countries, /operators और /numbers। ये अपने आउटबाउंड समकक्षों जैसे ही विंडो और टाइमज़ोन पैरामीटर लेते हैं।

आउटबाउंड समूह से दो बातें अलग हैं। हर पंक्ति में केवल एक सादी received गिनती होती है, कोई डिलीवरी ब्लॉक या दरें नहीं, क्योंकि इनबाउंड संदेश का कोई डिलीवरी लाइफ़साइकल नहीं होता जिसे एकत्र किया जाए। /operators एंडपॉइंट उन संदेशों को शामिल नहीं करता जिनके भेजने वाले ऑपरेटर की जानकारी कैरियर ने नहीं दी, इसलिए उसी अवधि के लिए इसकी पंक्तियों का योग /inbound/summary से कम हो सकता है। वर्कस्पेस के कुल योग के लिए सारांश का उपयोग करें; ऑपरेटर पंक्तियों में केवल वे संदेश आते हैं जिनका ऑपरेटर बताया गया है।

अगले कदम

SMS एनालिटिक्स इस रिपोर्टिंग को कैंपेन समीक्षा और डिलीवरी जाँच से जोड़ता है।

• मेट्रिक्स: वह डैशबोर्ड देखें जिसमें ये मान दिखाए जाते हैं।
• SMS लॉग: इन एग्रीगेट के पीछे के संदेश देखें।
• इवेंट: इन एग्रीगेट के पीछे की इवेंट स्ट्रीम का उपयोग करें।