SMS इवेंट

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

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

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

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

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

Bird उत्तर भी प्राप्त करता है। जब कोई सब्सक्राइबर आपके किसी नंबर पर संदेश भेजता है, तो Bird संदेश संग्रहित करता है और sms.received जारी करता है, ताकि आप बार-बार जाँच किए बिना कार्रवाई कर सकें। पेलोड में बॉडी, सेगमेंट ब्रेकडाउन, दोनों नंबर, और कैरियर द्वारा रिपोर्ट किए जाने पर ऑपरेटर शामिल होता है। इसमें tags या metadata जैसे भेजने के अनुरोध वाले फ़ील्ड नहीं होते, क्योंकि प्राप्त संदेश का कोई भेजने का अनुरोध नहीं होता।

Bird उत्तर का मूल्यांकन उस नंबर के कीवर्ड नियमों के अनुसार करता है। STOP जैसा कोई समर्थित स्टॉप कीवर्ड प्रेषक और सब्सक्राइबर की जोड़ी के लिए सप्रेशन दर्ज करता है और फिर भी sms.received जारी करता है।

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

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

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

हर प्रति-संदेश SMS इवेंट के data में sms_id, workspace_id, और to व from पते होते हैं। आपके भेजे गए संदेश के इवेंट भेजने के अनुरोध के tags और metadata को भी लौटाते हैं, ताकि आप बिना अलग लुकअप के इवेंट को रूट कर सकें और आपस में जोड़ सकें। जब भेजने के अनुरोध में इनमें से कोई मान नहीं था, तो वह 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

तब ट्रिगर होता है जब Bird भेजने का अनुरोध स्वीकार करता है और संदेश को कैरियर को सौंपने की तैयारी शुरू करता है। पेलोड में segments जुड़ता है, यानी स्वीकृति के समय Bird द्वारा गिना गया ब्रेकडाउन; इसके count के आधार पर बिल बनता है। इसके बाद का हर आउटबाउंड इवेंट segments दोहराता है, इसलिए शुल्क का मिलान करने के लिए इनमें से कोई एक इवेंट पर्याप्त है।

sms.sent

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

sms.delivered

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

विफलता इवेंट

हर विफलता इवेंट के पेलोड में एक error ऑब्जेक्ट जुड़ता है: एक Bird-स्थिर code (उदाहरण के लिए unreachable या blocked_by_carrier), एक मानव-पठनीय description, दिए जाने पर मूल carrier_error_code, और occurred_at। SMS डिलीवरी त्रुटियाँ सामान्यीकृत कारणों और संख्यात्मक प्रदाता कोड की सूची देता है। sms.sent और sms.delivered की तरह, विफलता इवेंट में भी carrier और mcc_mnc होते हैं; जब किसी कैरियर रसीद ने इन्हें पहचाना नहीं, तो हर एक अनुपस्थित होता है।

sms.undelivered

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

sms.failed

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

sms.rejected

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

sms.expired

कैरियर ने डिलीवर करने का प्रयास बंद कर दिया और संदेश को समय-सीमा समाप्त के रूप में रिपोर्ट किया। समय-सीमा समाप्ति की जानकारी कैरियर की डिलीवरी रसीद से आती है: Bird अपनी कोई वैधता अवधि सेट नहीं करता और ऐसा कोई टाइमर नहीं चलाता जो संदेश को समाप्त करे। error बताता है कि कैरियर के प्रयास छोड़ने तक संदेश डिलीवर क्यों नहीं हुआ था, आमतौर पर unreachable: हैंडसेट पूरे समय बंद रहा या कवरेज से बाहर रहा।

सप्रेशन इवेंट

प्रति-संदेश लाइफ़साइकल के अलावा, एक इवेंट वर्कस्पेस की सप्रेशन सूची में बदलाव की रिपोर्ट करता है: sms_suppression.created तब ट्रिगर होता है जब कोई सप्रेशन शुरू होता है, चाहे किसी सब्सक्राइबर ने स्टॉप कीवर्ड भेजा हो, कैरियर ने ऑप्ट-आउट रिपोर्ट किया हो, या किसी ने इसे मैन्युअल रूप से जोड़ा हो। पेलोड में suppression_id, destination के रूप में सब्सक्राइबर का नंबर, वह originator जिस पर रोक लागू होती है (SMS सप्रेशन प्रेषक और सब्सक्राइबर की सटीक जोड़ी है), reason, और workspace_id होते हैं, ताकि आपका सिस्टम बार-बार जाँच किए बिना सूची की प्रतिलिपि रख सके:

{
  "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 टैब पर दर्ज किया गया वर्कस्पेस-व्यापी ऑप्ट-आउट एक घोषित प्राथमिकता है, सप्रेशन नहीं, और इससे यह इवेंट ट्रिगर नहीं होता।

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

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

अगले कदम

• वेबहुक और इवेंट: एंडपॉइंट सेट करें, सिग्नेचर सत्यापित करें, और फिर से प्रयास व रीप्ले को हैंडल करें।
• SMS लॉग: इन इवेंट से बनने वाली प्रति-संदेश टाइमलाइन देखें।
• SMS भेजना: tags और metadata सेट करें, जो आपके भेजे गए संदेश के हर इवेंट में वापस लौटाए जाते हैं।