Sign inGet Started

एजेंट नियंत्रण: सीमित स्कोप वाली कुंजियाँ, खर्च सीमाएँ और सुरक्षित रूप से फिर से प्रयास करना

जो एजेंट Bird के ज़रिए संदेश भेजता है, उसके पास एक क्रेडेंशियल होता है और वह आपका बैलेंस खर्च करता है। पाँच नियंत्रण तय करते हैं कि वह क्या कर सकता है। पहला नियंत्रण स्वयं क्रेडेंशियल है। बाकी चार तभी तक लागू रहते हैं, जब तक एजेंट का क्रेडेंशियल उन्हें बदल नहीं सकता, इसलिए शुरुआत क्रेडेंशियल से करें।

नियंत्रणयह किसे सीमित करता हैसीमा पर पहुँचने पर कॉलर को क्या मिलता हैइसे कौन सेट करता है
क्रेडेंशियलवे ऑपरेशन जिन्हें एजेंट कॉल कर सकता है403वह व्यक्ति जो कुंजी बनाता है या साइन-इन को स्वीकृति देता है
आइडेम्पोटेंसी कुंजीअनुरोध को फिर से प्रयास करने पर दोहराए गए संदेशमूल प्रतिक्रिया, दोबारा लौटाई गईकॉलर, हर अनुरोध पर
SMS गंतव्य अनुमति सूचीवे देश जहाँ SMS API संदेश भेजा जा सकता है422 SMSDestinationNotEnabledsms_management लिखने की अनुमति वाला क्रेडेंशियल
SMS दैनिक खर्च सीमाएक दिन में किसी एक देश पर SMS खर्च422 SMSDestinationDailySpendExceededsms_management लिखने की अनुमति वाला क्रेडेंशियल
प्रीपेड वॉलेटपे-एज़-यू-गो खर्चSMS और WhatsApp के लिए 402। सशुल्क ईमेल का शुल्क उसके भेजे जाने के बाद लिया जाता है।संगठन का स्वामी या बिलिंग एडमिन

इस पेज पर बताई गई गंतव्य अनुमति सूची और दैनिक खर्च सीमा SMS पर लागू होती हैं। Verify और Voice की अपनी-अपनी गंतव्य सेटिंग हैं, और उनकी शुरुआती स्थिति अलग होती है। ईमेल और WhatsApp में न गंतव्य अनुमति सूची है और न दैनिक खर्च सीमा, इसलिए वहाँ एजेंट को क्रेडेंशियल के स्कोप और वॉलेट ही सीमित करते हैं।

चुनें कि एजेंट कौन-सा क्रेडेंशियल रखेगा

एजेंट दो प्रकार के क्रेडेंशियल में से किसी एक से Bird को कॉल करता है। दोनों में अंतर यह है कि उनकी पहुँच कितनी दूर तक है।

  • API कुंजी (bk_) में वही स्कोप होते हैं जो आप उसे देते हैं, और वह एक ही वर्कस्पेस से जुड़ी होती है। वह कोई दूसरी कुंजी जारी नहीं कर सकती, और संगठन की बिलिंग, सदस्यों या सेटिंग तक नहीं पहुँच सकती। आपका कोड इसे बेयरर टोकन के रूप में भेजता है। CLI और लोकल MCP सर्वर (bird mcp) में BIRD_API_KEY सेट होने पर वे सहेजे गए साइन-इन के बजाय उसी कुंजी का उपयोग करते हैं।
  • OAuth टोकन (bt_) वह क्रेडेंशियल है जो किसी व्यक्ति के साइन इन करने के बाद CLI और MCP सर्वर के पास रहता है। इसमें वे अनुमतियाँ होती हैं जिन्हें उस व्यक्ति ने स्वीकृत किया, और कभी भी उस व्यक्ति की अपनी अनुमतियों से अधिक नहीं। इनमें api_keys लिखने की अनुमति, sms_management लिखने की अनुमति और संगठन की बिलिंग शामिल हो सकती हैं। ऐसे टोकन वाला एजेंट कुंजियाँ जारी कर सकता है, देश सक्षम कर सकता है और इस पेज पर बताई गई सीमाएँ बढ़ा सकता है।

OAuth टोकन कितना कुछ कर सकता है, यह इस पर निर्भर करता है कि वह कैसे बनाया गया:

  • bird auth login केवल पढ़ने की पहुँच माँगता है। --scope आपके बताए गए अनुमति-समूह को माँगता है, और --yolo वे सभी अनुमतियाँ माँगता है जिन्हें आप सौंप सकते हैं। परिणाम को आप ब्राउज़र में स्वीकृत करते हैं।
  • होस्ट किया गया MCP क्लाइंट वे सभी अनुमतियाँ माँग सकता है जिन्हें आप सौंप सकते हैं। सहमति स्क्रीन पर आप चुन सकते हैं कि कौन-सी अनुमतियाँ देनी हैं। स्वीकृत करने से पहले वे अनुमतियाँ हटा दें जिनकी एजेंट को ज़रूरत नहीं है।
  • Self-serve signup में कोई सहमति स्क्रीन नहीं होती। इससे बनने वाले क्रेडेंशियल के पास वे सभी अनुमतियाँ होती हैं जो नए संगठन का मालिक सौंप सकता है, जिनमें संगठन बिलिंग भी शामिल है।

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

हर कुंजी का स्कोप केवल उन उत्पादों तक रखें जिनकी उसे ज़रूरत है

एक API कुंजी में स्कोप की एक सूची होती है, और हर स्कोप read या write स्तर पर एक उत्पाद क्षेत्र होता है। जो कुंजी केवल SMS भेजती है, उसके पास sms:write होता है। कुंजी के स्कोप से बाहर का अनुरोध 403 लौटाता है, इसलिए लीक हुई या गलत इस्तेमाल की गई कुंजी केवल उसी तक पहुँचती है जो आपने उसे दिया है।

किसी कुंजी के स्कोप चाहे जो हों, उसकी तीन विशेषताएँ हमेशा लागू रहती हैं:

  • कोई कुंजी दूसरी कुंजी जारी नहीं कर सकती। कुंजियाँ जारी करने और बदलने के लिए api_keys:write चाहिए, जो API कुंजियों को उपलब्ध नहीं है। इसे कोई व्यक्ति डैशबोर्ड सत्र में या CLI या MCP साइन-इन पर स्वीकृत करता है।
  • कुंजी अपने वर्कस्पेस तक ही सीमित रहती है। वह बिलिंग, संगठन के सदस्यों या संगठन की सेटिंग्स तक नहीं पहुँच सकती।
  • कुंजी की समय-सीमा समाप्त हो सकती है। कुंजी बनाते समय expires_at सेट करें, और उस समय के बाद कुंजी 401 लौटाती है। आप किसी भी समय कुंजी बदल या रद्द कर सकते हैं।

कुंजी डैशबोर्ड में या टर्मिनल से बनाएँ। CLI साइन-इन किसी कुंजी पर केवल वही स्कोप लगा सकता है जो उसके अपने पास हैं, इसलिए यह साइन-इन api_keys:write के साथ sms:write भी माँगता है:

कोड उदाहरण
bird auth login --scope api_keys:write --scope sms:write
bird api-keys create --name "Support agent" --scope sms:write

प्रमाणीकरण और API कुंजियाँ में स्कोप तालिका है, और इसमें समय-सीमा समाप्ति, बदलना और रद्द करना शामिल है।

दो बार भेजे बिना भेजने का फिर से प्रयास करें

जिस एजेंट को प्रतिक्रिया नहीं मिलती, वह यह नहीं जान सकता कि उसका अनुरोध स्वीकार हुआ या नहीं। हर इच्छित भेजने के लिए एक अद्वितीय मान के साथ Idempotency-Key हेडर भेजें, और जब परिणाम अज्ञात हो तो वही अनुरोध उसी कुंजी के साथ दोहराएँ। Bird मूल प्रतिक्रिया लौटाता है और संदेश को एक ही बार स्वीकार करता है। दोहराई गई प्रतिक्रिया में Idempotency-Replay: true होता है।

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

SDK हर बदलाव करने वाली कॉल के लिए एक कुंजी बनाते हैं और अपने स्वचालित फिर से प्रयासों में उसी का दोबारा उपयोग करते हैं। CLI पर --idempotency-key पास करें। इडेम्पोटेंसी में कुंजी का फ़ॉर्मेट, रिटेंशन अवधि, और किसी कुंजी को अलग अनुरोध के साथ दोबारा उपयोग करने पर क्या होता है, यह बताया गया है।

हर SMS गंतव्य देश को अनुमति दें

SMS गंतव्य अनुमति सूची डिफ़ॉल्ट रूप से सब कुछ अस्वीकार करती है। SMS API के ज़रिए भेजा गया संदेश सूची में सक्षम किसी देश को जाता है, वरना प्रेषक तय होने से पहले ही 422 SMSDestinationNotEnabled के साथ अस्वीकार हो जाता है, इसलिए कोई संदेश स्वीकार नहीं होता। किसी अनपेक्षित देश की ओर भेजने वाले एजेंट को मना कर दिया जाता है। यह नियम आपके अपने कोड, bird sms send और sms_send MCP टूल से भेजे गए संदेशों पर लागू होता है।

सत्यापन कोड इस सूची का उपयोग नहीं करते। Verify की अपनी सूची Verify गंतव्य में है, जहाँ हर देश शुरुआत से सक्षम रहता है। इसलिए verify लिखने की अनुमति वाला क्रेडेंशियल SMS से ऐसे देश को भी कोड भेज सकता है जिसे यह अनुमति सूची रोकती है। अगर एजेंट के पास verify है, तो उस पेज पर भी वे देश बंद करें जिन्हें आप सेवा नहीं देते।

किसी देश को SMS > Destinations में, bird sms destinations update से, या sms_destinations_update MCP टूल से सक्षम करें:

कोड उदाहरण
bird sms destinations update --destination NL=true

अनुमति सूची बदलने के लिए write स्तर पर sms_management स्कोप चाहिए। जिस क्रेडेंशियल के पास केवल sms है, वह सक्षम देशों को भेज सकता है, पर और देश सक्षम नहीं कर सकता। भेजने वाले एजेंट को sms दें, और sms_management उस क्रेडेंशियल के लिए रखें जो वर्कस्पेस कॉन्फ़िगर करता है।

SMS भेजना में बताया गया है कि अनुमति सूची किस स्थिति से शुरू होती है और गृह देश कैसे जोड़ा जाता है।

हर देश के लिए दैनिक SMS खर्च सीमित करें

हर गंतव्य देश पर आपके वॉलेट की मुद्रा में एक दैनिक खर्च सीमा लगाई जा सकती है। जब उस देश पर दिन का खर्च सीमा तक पहुँच जाता है, तो वहाँ के नए संदेश UTC मध्यरात्रि तक 422 SMSDestinationDailySpendExceeded के साथ अस्वीकार किए जाते हैं। शून्य की सीमा उस देश को पूरी तरह रोक देती है।

SMS से भेजे गए सत्यापन कोड इस सीमा में गिने जाते हैं। सीमा पूरी होने पर Verify उस देश को SMS से कोड भेजना बंद कर देता है और उस देश के लिए सक्षम अगला चैनल आज़माता है। जब कोई चैनल नहीं बचता, तो सत्यापन 422 NoAvailableChannel के साथ विफल हो जाता है।

सीमा उन्हीं तीन जगहों पर सेट करें जहाँ अनुमति सूची सेट होती है। यह कमांड नीदरलैंड्स को सक्षम करती है और उसे प्रतिदिन 25 EUR तक सीमित करती है, ऐसे वर्कस्पेस में जिसका वॉलेट EUR में है:

कोड उदाहरण
bird sms destinations update --destination "NL=true;25EUR"

यह सीमा सटीक नहीं है। सीमा में किया गया बदलाव भेजने की प्रक्रिया तक पहुँचने में एक मिनट तक लेता है। खर्च तब गिना जाता है जब किसी संदेश का शुल्क लगता है, इसलिए पहले से स्वीकार किए गए संदेश अपनी लागत जितनी राशि से दिन का कुल खर्च सीमा से ऊपर ले जा सकते हैं। सीमा तय करते समय इतना अंतर रखें। bird sms destinations list हर देश की सीमा और उसके मुकाबले दिन का उपयोग दिखाता है।

सीमा तय करने के लिए वही sms_management लिखने की अनुमति चाहिए जो अनुमति-सूची के लिए चाहिए, इसलिए केवल sms वाला क्रेडेंशियल अपनी सीमा नहीं बढ़ा सकता। SMS भेजना में पूरे नियम हैं।

प्रीपेड वॉलेट से कुल खर्च सीमित करें

पे-एज़-यू-गो भेजे गए संदेश आपके संगठन के प्रीपेड वॉलेट से भुगतान लेते हैं। जब बैलेंस किसी संदेश का खर्च नहीं उठा पाता, तब क्या होता है, यह चैनल पर निर्भर करता है:

  • SMS और WhatsApp को API पर 402 के साथ अस्वीकार कर दिया जाता है। जो संदेश पहले ही स्वीकार हो चुका था और जिसका शुल्क विफल हो जाता है, वह rejected पर समाप्त होता है और उसका बिल नहीं बनता।
  • सशुल्क Email प्लान पर ईमेल का शुल्क भेजने के कुछ ही समय बाद लगता है, इसलिए बैलेंस थोड़ी देर के लिए शून्य से नीचे जा सकता है। जब वॉलेट में कोई बैलेंस या क्रेडिट नहीं बचता, तो धनराशि जोड़े जाने तक नए ईमेल 402 के साथ अस्वीकार किए जाते हैं।
  • डिलीवरी के समय लगने वाला शुल्क अगर बैलेंस से नहीं चुकाया जा सकता, तो उसे छोड़ दिया जाता है, और संदेश फिर भी प्राप्तकर्ता तक पहुँचता है।

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

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

भुगतान के तरीके और वॉलेट में टॉप-अप, स्वचालित टॉप-अप और कम बैलेंस की सूचनाएँ बताई गई हैं।

अगले कदम

इस विषय के लिए दस्तावेज़, गाइड और उदाहरणों के साथ आगे बढ़ें।