SMS इवेंट

हर संदेश एक लाइफ़साइकल से गुज़रता है, और Bird हर चरण पर एक इवेंट emit करता है। यह पेज पूरी इवेंट शब्दावली है; इवेंट आपके endpoint तक कैसे पहुँचाए जाते हैं (signatures, retries, replay) यह Webhooks गाइड में शामिल है।

डिलीवरी लाइफ़साइकल, इवेंट टाइप के रूप में एक पथ:

sms.accepted: Bird के पास संदेश है और वह उसे कैरियर को सौंपने की तैयारी कर रहा है।
sms.sent: Bird ने संदेश कैरियर को सौंप दिया है और डिलीवरी रसीद की प्रतीक्षा कर रहा है।
एक टर्मिनल इवेंट:
- sms.delivered: कैरियर ने हैंडसेट तक डिलीवरी की पुष्टि की।
- sms.undelivered: कैरियर ने एक अस्थायी नॉन-डिलीवरी रिपोर्ट की, जैसे अनुपलब्ध हैंडसेट।
- sms.failed: एक स्थायी विफलता ने डिलीवरी रोक दी।
- sms.expired: कैरियर ने प्रयास बंद कर दिया और संदेश को expired रिपोर्ट किया।

टर्मिनल इवेंट कैरियर की डिलीवरी रसीद को सामने लाते हैं, जिसे SMS प्लेटफ़ॉर्म डिलीवरी रिपोर्ट या DLR कहते हैं।

अपवाद sms.rejected है: संदेश को अस्वीकार किया गया (किसी पॉलिसी जाँच द्वारा, ऐसे शुल्क द्वारा जो पूरा नहीं हो सका, या किसी कैरियर द्वारा जिसने इसे लौटा दिया) बजाय इसके कि प्रयास किया गया और खो गया। प्रोसेसिंग के दौरान अस्वीकृत संदेश के एकमात्र इवेंट के रूप में sms.rejected होता है।

Bird उत्तर भी प्राप्त करता है। जब कोई सब्सक्राइबर आपके किसी नंबर पर संदेश भेजता है, तो Bird संदेश संग्रहित करता है और sms.received emit करता है, ताकि आप polling के बिना कार्रवाई कर सकें। पेलोड में बॉडी, सेगमेंट ब्रेकडाउन, दोनों नंबर, और ऑपरेटर शामिल होता है जब कैरियर उसकी रिपोर्ट करता है।

Bird उत्तर का मूल्यांकन उस नंबर के कीवर्ड नियमों के अनुसार करता है। STOP जैसा कोई समर्थित stop कीवर्ड sender-and-subscriber suppression रिकॉर्ड करता है और फिर भी sms.received emit करता है।

इवेंट type एक open enum है: Bird समय के साथ नए इवेंट टाइप जोड़ सकता है, इसलिए किसी अपरिचित type को त्रुटि के बजाय भविष्य का इवेंट मानें। जिन टाइप को आप हैंडल करते हैं उन्हें मैच करें और बाकी को अनदेखा करें।

इवेंट एन्वेलप

इवेंट आपके webhook endpoint पर Standard Webhooks नेस्टेड एन्वेलप में आते हैं जैसा Webhooks गाइड में वर्णित है: तीन फ़ील्ड, type, timestamp, और एक टाइप-विशिष्ट data ऑब्जेक्ट। इवेंट की पहचान बॉडी में नहीं होती: यह webhook-id HTTP हेडर में होती है, जो एक ही डिलीवरी के retries में स्थिर रहता है और आपकी deduplication key है।

फ़ील्ड	विवरण
type	इस पेज पर दिए गए इवेंट टाइप में से एक, जैसे sms.delivered
timestamp	इवेंट कब हुआ (RFC 3339); इसके अनुसार सॉर्ट करें, आगमन क्रम के अनुसार कभी नहीं, क्योंकि डिलीवरी क्रमबद्ध नहीं होतीं
data	इवेंट-विशिष्ट पेलोड

हर SMS इवेंट के data में sms_id, workspace_id, और to व from एड्रेस होते हैं। यह send के tags और metadata को भी echo करता है ताकि आप बिना अलग लुकअप के इवेंट को रूट और correlate कर सकें। जब send में कोई नहीं था तो हर एक null होता है।

यही ऑब्जेक्ट cost भी रखता है, जो उस इवेंट तक संदेश का शुल्क है, transaction_amount और passthrough_amount में विभाजित और उनका योग amount में। जिस इवेंट ने कुछ प्राइस नहीं किया उस पर यह null होता है। क्योंकि डिलीवरी क्रमबद्ध नहीं होतीं, cost को पूरा ऑब्जेक्ट बदलने के बजाय एक-एक कम्पोनेंट करके मर्ज करें: हर कम्पोनेंट के लिए, नवीनतम timestamp वाले इवेंट का मान रखें। एक amount केवल अपने पेलोड के कम्पोनेंट का योग करता है, इसलिए इसे अंतिम कुल के बजाय अब तक का शुल्क समझें। लागत और बिलिंग बताता है कि हर कम्पोनेंट का क्या अर्थ है।

कोड उदाहरण

{
  "type": "sms.delivered",
  "timestamp": "2026-06-10T14:30:00Z",
  "data": {
    "sms_id": "sms_01krdgeqcxet5s7t44vh8rt9mg",
    "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
    "to": "+15551234567",
    "from": "+12025550188",
    "carrier": "Example Wireless",
    "mcc_mnc": "310260",
    "cost": {
      "amount": "0.00990",
      "currency_code": "USD",
      "transaction_amount": "0.00790",
      "passthrough_amount": "0.00200"
    },
    "tags": [{ "name": "campaign", "value": "spring-2026" }],
    "metadata": { "order_id": "ord_123" }
  }
}

लाइफ़साइकल इवेंट

sms.accepted

तब fire होता है जब Bird send स्वीकार करता है और उसे कैरियर को सौंपने की तैयारी शुरू करता है। पेलोड में segments जुड़ता है, वह ब्रेकडाउन Bird जो accept समय पर गिना गया; इसका count वह है जिस पर send का बिल बनता है।

sms.sent

तब fire होता है जब Bird ने संदेश कैरियर को सौंप दिया है और डिलीवरी रसीद की प्रतीक्षा कर रहा है। पेलोड में carrier और mcc_mnc (हैंडलिंग नेटवर्क और उसका mobile country/network code) जुड़ते हैं। जब कैरियर रिपोर्ट नहीं करता तो हर एक null के बजाय अनुपस्थित होता है। प्रोसेसिंग विलंब मापने के लिए, इस इवेंट के timestamp की तुलना sms.accepted से करें।

sms.delivered

कैरियर ने पुष्टि की कि संदेश हैंडसेट तक पहुँच गया। पेलोड में carrier और mcc_mnc जुड़ते हैं, जब रसीद ने इन्हें पहचाना नहीं तो हर एक अनुपस्थित होता है।

विफलता इवेंट

हर विफलता इवेंट के पेलोड में एक error ऑब्जेक्ट जुड़ता है: एक Bird-स्थिर code (उदाहरण के लिए unreachable या blocked_by_carrier), एक मानव-पठनीय description, raw carrier_error_code जब कोई दिया गया हो, और occurred_at।

sms.undelivered

एक गैर-स्थायी नॉन-डिलीवरी: हैंडसेट बंद था या पहुँच से बाहर था।

sms.failed

एक स्थायी डिलीवरी विफलता ने संदेश रोक दिया।

sms.rejected

संदेश को प्रोसेसिंग के दौरान Bird की जाँचों द्वारा, पूरा न हो सकने वाले शुल्क द्वारा, या किसी कैरियर द्वारा अस्वीकार किया गया जिसने इसे लौटा दिया। rejection डिलीवरी प्रयास सफल होने से पहले संदेश रोक देता है। एक खाली वॉलेट error code insufficient_balance के साथ यहाँ समाप्त होता है, और जिस संदेश का शुल्क पूरा नहीं हो सका उसका बिल नहीं बनता।

sms.expired

कैरियर ने डिलीवर करने का प्रयास बंद कर दिया और संदेश को expired रिपोर्ट किया। Expiry कैरियर की डिलीवरी रसीद से आती है: Bird अपनी कोई validity window सेट नहीं करता और कोई टाइमर नहीं चलाता जो संदेश समाप्त करे। error बताता है कि जब कैरियर ने हार मानी तब संदेश अभी भी अनडिलीवर्ड क्यों था, आमतौर पर unreachable: हैंडसेट पूरे समय बंद रहा या कवरेज से बाहर रहा।

Suppression इवेंट

प्रति-संदेश लाइफ़साइकल से परे, एक इवेंट वर्कस्पेस की suppression सूची में बदलाव की रिपोर्ट करता है: sms_suppression.created तब fire होता है जब कोई suppression खुलता है, चाहे किसी सब्सक्राइबर ने stop कीवर्ड भेजा हो, कैरियर ने opt-out रिपोर्ट किया हो, या किसी ने मैन्युअली जोड़ा हो। पेलोड में suppression_id, सब्सक्राइबर का नंबर destination के रूप में, वह originator जिससे ब्लॉक बंधा है (SMS suppression sender-and-subscriber की सटीक जोड़ी है), reason, और workspace_id होता है, ताकि आपका सिस्टम polling के बिना सूची को मिरर कर सके:

कोड उदाहरण

{
  "type": "sms_suppression.created",
  "timestamp": "2026-08-25T14:52:03.192524705Z",
  "data": {
    "suppression_id": "ssu_01krdgeqcxet5s7t44vh8rt9mg",
    "destination": "+15550001234",
    "originator": "+15557654321",
    "reason": "keyword_stop",
    "workspace_id": "ws_01ky7m21hjffh9s8kq76gyb1xf"
  }
}

Preferences टैब पर रिकॉर्ड किया गया वर्कस्पेस-व्यापी opt-out एक stated preference है, suppression नहीं, और यह इवेंट fire नहीं करता।

संदेश की टाइमलाइन पढ़ना

Webhooks इवेंट आपके सिस्टम तक पहुँचाते हैं। एक बार की समीक्षा के लिए, SMS log उसी स्ट्रीम को timestamps, कैरियर विवरण, और errors के साथ टाइमलाइन के रूप में रेंडर करता है। टाइमलाइन प्रोग्रामेटिक रूप से प्राप्त करने के लिए, GET /v1/sms/messages/{message_id}/events कॉल करें। केवल नवीनतम स्थिति पढ़ने के लिए, GET /v1/sms/messages/{message_id} कॉल करें।

अगले कदम

Webhooks और इवेंट: endpoint सेट करें, signatures सत्यापित करें, और retries व replay हैंडल करें।
SMS log: इन इवेंट द्वारा संचालित प्रति-संदेश टाइमलाइन देखें।
SMS भेजना: हर इवेंट पर echo होने वाले tags और metadata सेट करें।

संबंधित संसाधन