Sign inGet Started

अपना पहला SMS भेजें

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

शुरू करने से पहले सुनिश्चित करें कि आपके संगठन के वॉलेट में धनराशि है। SMS भेजने का खर्च वॉलेट से कटता है, और जिस भेजने का खर्च बैलेंस से पूरा नहीं होता, उसे Bird 402 WalletInsufficientBalance के साथ अस्वीकार कर देता है। टॉप-अप करने का तरीका भुगतान के तरीके और वॉलेट में बताया गया है।

अगर आपका अभी कोई खाता नहीं है, तो सेल्फ़-सर्व साइनअप बिना ब्राउज़र के, टर्मिनल से CLI या curl के ज़रिए खाता बनाता है। अगर आपका कोड rest.messagebird.com पर MessageBird API को कॉल करता है, तो वह API और उसकी एक्सेस कुंजियाँ इस क्विकस्टार्ट के API से अलग हैं। MessageBird से आ रहे हैं में बताया गया है कि ये खाते आपस में कैसे जुड़े हैं, और Bird Connectivity Platform से SMS माइग्रेट करें पुराने भेजने वाले कॉल के हर फ़ील्ड का मिलान बताता है।

1. एक API कुंजी बनाएँ

डैशबोर्ड में Platform tools > API keys पर जाएँ और sms:write स्कोप वाली एक कुंजी बनाएँ, जिससे संदेश भेजे और पढ़े जा सकते हैं। केवल इस स्कोप वाली कुंजी SMS गंतव्य देश सक्षम नहीं कर सकती, दैनिक SMS खर्च सीमाएँ नहीं बदल सकती और धनराशि नहीं जोड़ सकती: एजेंट नियंत्रण में बताया गया है कि भेजने वाली कुंजी पर कौन-सी सीमाएँ लागू होती हैं। कुंजियाँ किसी एक क्षेत्र तक सीमित होती हैं और bk_us1_... या bk_eu1_... जैसी दिखती हैं। प्रीफ़िक्स में दिया क्षेत्र बताता है कि आपको किस API होस्ट को कॉल करना है: https://us1.platform.bird.com या https://eu1.platform.bird.com।

Bird डैशबोर्ड में API Keys पेज, जिसमें कुंजियाँ उनके मास्क किए गए प्रीफ़िक्स, स्कोप और पिछली बार उपयोग के समय के साथ सूचीबद्ध हैं

टर्मिनल से Bird CLI में bird api-keys create यही कुंजी जारी करता है। कुंजी जारी करने के लिए api_keys:write स्कोप चाहिए, और CLI लॉगिन किसी कुंजी को केवल वही स्कोप दे सकता है जो उसके अपने पास हैं। यह लॉगिन sms_management:write भी माँगता है, जिसकी ज़रूरत चरण 2 में होती है। अगर आपने टर्मिनल से bird auth create-org के ज़रिए खाता बनाया है, तो लॉगिन वाली पंक्ति छोड़ दें: साइनअप द्वारा सहेजे गए क्रेडेंशियल के पास ये स्कोप पहले से हैं, और नया लॉगिन उसे कम स्कोप वाले क्रेडेंशियल से बदल देता है।

कोड उदाहरण
bird auth login --scope api_keys:write --scope sms:write --scope sms_management:write
bird api-keys create --name "SMS quickstart key" --scope sms:write

पूरी कुंजी केवल एक बार, बनाते समय दिखाई जाती है। इसे किसी सुरक्षित जगह कॉपी करें, फिर cURL उदाहरणों के लिए इसे एक्सपोर्ट करें:

कोड उदाहरण
export BIRD_API_KEY="bk_us1_..."

जब तक BIRD_API_KEY सेट है, CLI आपके लॉगिन की जगह इस कुंजी का उपयोग करता है। यह कुंजी SMS गंतव्य नहीं बदल सकती, इसलिए चरण 2 का CLI कमांड ऐसे शेल में चलाएँ जिसमें यह वेरिएबल सेट न हो।

2. गंतव्य देश सक्षम करें

Bird केवल उन्हीं देशों में SMS भेजता है जो आपके वर्कस्पेस के लिए सक्षम हैं। किसी अन्य देश में भेजने पर 422 SMSDestinationNotEnabled त्रुटि आती है। अपने फ़ोन नंबर के देश को SMS > Destinations में सक्षम करें। अगर वह पहले से सक्षम दिखता है, तो चरण 3 पर जाएँ।

टर्मिनल से Bird CLI भी यही बदलाव करता है। देश का दो-अक्षर वाला ISO कोड दें, जैसे संयुक्त राज्य अमेरिका के लिए US। अगर आपके CLI लॉगिन के पास SMS सेटिंग्स की एक्सेस नहीं है, तो कमांड वह bird auth login कमांड प्रिंट करता है जो यह एक्सेस जोड़ता है:

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

MCP सर्वर से जुड़े एजेंट sms_destinations_update टूल का उपयोग करते हैं। सार्वजनिक API में डेस्टिनेशन के लिए कोई ऑपरेशन नहीं है। किसी बदलाव को भेजे जाने वाले संदेशों पर लागू होने में एक मिनट तक लग सकता है।

3. संदेश भेजें

बिल्ट-इन bird_otp_verification टेम्पलेट अपने फ़ोन पर भेजें। यह आपके द्वारा दिए गए code मान के साथ "493021 is your verification code. Do not share it." के रूप में दिखता है। अपनी भाषा के लिए Bird SDK को उसके SDK क्विकस्टार्ट का पालन करके इंस्टॉल करें।

SDK टैब में उदाहरण वाली API कुंजी बदलें, और +14155550100 की जगह E.164 फ़ॉर्मैट में अपना मोबाइल नंबर डालें। CLI आपके लॉगिन का उपयोग करता है, या जब तक वह वेरिएबल सेट है तब तक BIRD_API_KEY का, और cURL टैब BIRD_API_KEY का उपयोग करता है।

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const msg = await bird.sms.send({
  to: "+14155550100",
  template: { slug: "bird_otp_verification", parameters: { code: "493021" } },
});

console.log(msg.id, msg.status);

यदि आपकी कुंजी bk_eu1_ से शुरू होती है, तो इसके बजाय https://eu1.platform.bird.com को कॉल करें।

API जवाब में 202 Accepted और संदेश लौटाता है। संदेश का id sms_ से शुरू होता है, और उसका status accepted होता है: यानी Bird के पास संदेश है और वह उसे एसिंक्रोनस रूप से डिलीवर करता है। अगले चरण के लिए id संभालकर रखें। संदेश उस साझा सेंडर से आता है जिसे Bird ने आपके देश के लिए चुना है।

4. डिलीवरी स्थिति जाँचें

संदेश को उसकी ID से प्राप्त करें। भेजने के तुरंत बाद पढ़ने पर 404 मिल सकता है, जब तक संदेश रीड एंडपॉइंट पर दिखाई न देने लगे। ऐसा 202 के कुछ ही देर बाद होता है। थोड़ी देर बाद इसे फिर से पढ़ें। SMS_MESSAGE_ID की जगह चरण 3 से मिली id डालें, और SDK टैब में उदाहरण वाली API कुंजी की जगह अपनी कुंजी डालें। Go SDK में SMS संदेश पढ़ने के लिए कोई टाइप्ड मेथड नहीं है, इसलिए Go टैब SDK के client.Get अनुरोध मेथड के ज़रिए API पाथ को कॉल करता है।

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const msg = await bird.sms.get("SMS_MESSAGE_ID");

console.log(msg.id, msg.status);

status फ़ील्ड बताता है कि संदेश कहाँ है:

  • accepted: संदेश Bird के पास है और उसने अभी तक इसे किसी कैरियर को नहीं सौंपा है।
  • sent: संदेश कैरियर के पास है, और sent_at दर्ज करता है कि Bird ने इसे कब सौंपा।
  • delivered: कैरियर ने डिलीवरी की पुष्टि की है, और delivered_at दर्ज करता है कि कब।
  • undelivered, failed, rejected या expired: संदेश फ़ोन तक नहीं पहुँचा। last_error कारण बताता है, और डिलीवरी त्रुटियाँ हर कारण को समझाता है।

तब तक पोल करें जब तक स्थिति accepted और sent से आगे न बढ़ जाए, या हर बदलाव वेबहुक से पाने के लिए SMS इवेंट की सदस्यता लें। हर संदेश अपनी इवेंट टाइमलाइन के साथ Messages पेज पर भी दिखता है।

विफल भेजे गए संदेश को ठीक करें

  • 422 SMSDestinationNotEnabled: प्राप्तकर्ता का देश आपके वर्कस्पेस के लिए सक्षम नहीं है। उसे चरण 2 की तरह सक्षम करें, एक मिनट तक प्रतीक्षा करें, और फिर से भेजें।
  • 402 WalletInsufficientBalance: वॉलेट में संदेश का खर्च उठाने लायक राशि नहीं है। वॉलेट टॉप अप करें, फिर दोबारा भेजें।
  • 403 InsufficientScope: API कुंजी में sms स्कोप नहीं है। कुंजी के स्कोप संपादित करें या sms:write वाली नई कुंजी बनाएँ।

अगले चरण

  • SMS भेजना: सेंडर और श्रेणी के साथ अपना टेक्स्ट भेजें, बैच में भेजें, और सुरक्षित रूप से फिर से प्रयास करें।
  • SMS सेंडर ID: हर देश के लिए सेंडर चुनें और जहाँ देश को ज़रूरत हो वहाँ उसे पंजीकृत करें।
  • SMS टेम्पलेट: बिल्ट-इन टेम्पलेट कैटलॉग और उसके वेरिएबल।
  • SMS इवेंट: इवेंट के प्रकार और हर स्थिति बदलाव की वेबहुक डिलीवरी।
  • SMS API संदर्भ: पूरा अनुरोध और प्रतिक्रिया स्कीमा।

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