SMS stats API

Metrics डैशबोर्ड पर हर मान SMS stats API से आता है। इन्हीं एग्रीगेट का उपयोग किसी डैशबोर्ड, डेटा वेयरहाउस या हेल्थ चेक में करें। ये read-only, वर्कस्पेस-स्कोप्ड endpoints एक API key चाहते हैं जिसके पास sms scope का read access हो। समान रेंज और फ़िल्टर के लिए रिस्पॉन्स डैशबोर्ड से मेल खाता है।

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

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

तीन endpoints डैशबोर्ड के शीर्ष भाग को कवर करते हैं:

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

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

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

विंडो चुनना

from और to या तो कैलेंडर दिन (YYYY-MM-DD) या RFC 3339 instant लेते हैं, और कौन-सा endpoint कौन-सा फ़ॉर्म स्वीकार करता है यह भिन्न है:

Endpoint	सीमाएँ	अधिकतम विंडो
/summary	दोनों दिन, या दोनों instant	365 दिन, या instant पर 720 घंटे
/daily	कैलेंडर दिन	365 दिन
/hourly	RFC 3339 instant	720 घंटे (30 दिन)

Instant सीमाएँ hour-grain हैं, यही कारण है कि रोलिंग 24-घंटे की विंडो एक ही request में आ जाती है। /summary पर, किसी दिन को instant के साथ मिलाने पर 422 लौटता है।

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

ब्रेकडाउन

सात endpoints उन्हीं डिलीवरी संख्याओं को एक आयाम से विभाजित करते हैं:

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

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

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

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

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

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

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

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

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

अगले कदम

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

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