Sign inGet Started

SMS भेजना

यह गाइड सिंगल-सेंड एंडपॉइंट POST /v1/sms/messages को कवर करती है। एक प्राप्तकर्ता, प्रेषक, बॉडी और कैटेगरी के साथ JSON पेलोड बनाएँ। Bird एक मैसेज ID के साथ 202 Accepted लौटाता है और असिंक्रोनस रूप से डिलीवर करता है। हर रिक्वेस्ट एक प्राप्तकर्ता को एक मैसेज भेजती है। एक साथ कई मैसेज भेजने के लिए बैच सेंडिंग का उपयोग करें। अपने टेक्स्ट की जगह टेम्प्लेट भेजने के लिए text, category, और from के स्थान पर template ऑब्जेक्ट दें।

भेजने से पहले: गंतव्य देश सक्षम करें

आपके वर्कस्पेस में एक default-deny गंतव्य allowlist है जो शुरू में केवल आपके संगठन के होम कंट्री को सक्षम रखती है। Bird किसी अन्य देश को भेजने पर प्रेषक रिज़ॉल्व करने से पहले 422 SMSDestinationNotEnabled के साथ अस्वीकार कर देता है। डैशबोर्ड में SMS > Destinations के तहत उन देशों को सक्षम करें जिन्हें आप सेवा देते हैं।

न्यूनतम सेंड

सबसे छोटा वैध फ़्री-टेक्स्ट पेलोड एक to प्राप्तकर्ता, एक from प्रेषक, एक text बॉडी, और एक category है।
const msg = await bird.sms.send({
  from: "+15557654321",
  to: "+14155550100",
  text: "Your verification code is 123456.",
  category: "authentication",
});
console.log(msg.id, msg.status);
अपने रीजनल होस्ट (https://us1.platform.bird.com या https://eu1.platform.bird.com) का उपयोग एक मैचिंग bk_{region}_... key के साथ करें। रिस्पॉन्स स्वीकृत मैसेज है:
कोड उदाहरण
{
  "id": "sms_01ky7qmwgpfkybj9ecrnwjx714",
  "direction": "outbound",
  "status": "accepted",
  "to": "+31612345678",
  "from": "Bird",
  "text": "Your Bird verification code is 481920. It expires in 10 minutes.",
  "category": "authentication",
  "segments": { "count": 1, "encoding": "GSM_7BIT", "characters": 64 },
  "cost": null,
  "carrier": null,
  "mcc_mnc": null,
  "sent_at": null,
  "delivered_at": null,
  "created_at": "2026-07-23T14:56:34.326Z"
}
status: accepted का मतलब है कि Bird के पास मैसेज है और वह उस पर काम कर रहा है; cost null है क्योंकि प्राइसिंग प्रोसेसिंग के दौरान होती है। आगे क्या होता है यह async मॉडल में कवर किया गया है।

पेलोड बनाना

प्राप्तकर्ता

to E.164 फ़ॉर्मैट में एक प्राप्तकर्ता है: एक शुरुआती +, कंट्री कोड, और सब्सक्राइबर नंबर, जैसे +31612345678। एक मैसेज एक प्राप्तकर्ता को जाता है, कोई cc, bcc, या प्राप्तकर्ता ऐरे नहीं। कई लोगों तक पहुँचने के लिए बैच भेजें।

प्रेषक

from फ़्री-टेक्स्ट सेंड पर आवश्यक है और यह वह प्रेषक है जो प्राप्तकर्ता को दिखता है। यह दो में से एक आकार लेता है, और कौन सा काम करेगा यह गंतव्य देश पर निर्भर करता है:
  • अल्फ़ान्यूमेरिक सेंडर ID: 3 से 11 अक्षर, अंक, स्पेस, डैश, अंडरस्कोर या डॉट, जिनमें कम से कम एक अक्षर हो और किसी भी सिरे पर कोई सेपरेटर न हो, जैसे Bird या Acme-Co। इसमें एक अक्षर होना ज़रूरी है, इसलिए विराम चिह्न वाली अंक श्रृंखला जैसे 555 555 अस्वीकार कर दी जाती है। कुछ देशों में पंजीकरण आवश्यक है, और कुछ अन्य देश, जिनमें US शामिल है, अल्फ़ान्यूमेरिक सेंडर का समर्थन नहीं करते। प्राप्तकर्ता इन पर उत्तर नहीं दे सकते।
  • आपके वर्कस्पेस का स्वामित्व वाला नंबर, E.164 में या बिना प्रीफ़िक्स अंकों के। कोई भी पूरी तरह अंकों वाला from न्यूमेरिक माना जाता है और आपके सेंडर्स में खोजा जाता है, इसलिए कोई भी ऐसा मनमाना नंबर जो आपके पास नहीं है अस्वीकार कर दिया जाता है। यह लॉन्ग कोड, टोल-फ़्री नंबर, या शॉर्ट कोड के रूप में काम करता है या नहीं, यह नंबर से तय होता है, इससे नहीं कि आपने कितने अंक लिखे। 6 अंकों वाला from शॉर्ट कोड इसलिए नहीं है क्योंकि उसमें 6 अंक हैं; यह शॉर्ट कोड है अगर आपके पास मौजूद नंबर शॉर्ट कोड है।
गंतव्य के लिए अमान्य प्रेषक को कारण बताते हुए 422 के साथ अस्वीकार कर दिया जाता है (उदाहरण के लिए SMSAlphaNotSupported जहाँ अल्फ़ान्यूमेरिक सेंडर उपलब्ध नहीं हैं)। टेम्प्लेट सेंड पर from स्वीकार नहीं किया जाता: Bird गंतव्य और कैटेगरी के लिए प्रेषक का चयन करता है।
सेंडर ID क्लेम करना, हर देश को इसके लिए क्या चाहिए यह पढ़ना, और प्रति देश रजिस्ट्रेशन SMS sender IDs में कवर किया गया है।

बॉडी और कैटेगरी

text मैसेज बॉडी है, कम से कम एक कैरेक्टर। इसकी बिलिंग और डिलीवरी सेगमेंट में होती है; एक सेंड अधिकतम 12 सेगमेंट (लगभग 1,836 GSM-7 कैरेक्टर, या 804 अगर बॉडी विस्तारित UCS-2 एन्कोडिंग का उपयोग करती है) तक सीमित है। सीमा से अधिक बॉडी को काटने की बजाय 422 के साथ अस्वीकार कर दिया जाता है।
category फ़्री-टेक्स्ट सेंड पर आवश्यक है और मैसेज को transactional, marketing, authentication, या service के रूप में वर्गीकृत करता है। यह Bird और कैरियर्स को बताता है कि आप क्यों भेज रहे हैं। वन-टाइम सत्यापन कोड के लिए authentication का उपयोग करें; प्रमोशन के लिए marketing। मैसेज के उद्देश्य से मेल खाती कैटेगरी चुनें।

टैग और मेटाडेटा

दोनों आपके डेटा को सेंड से जोड़ते हैं, लेकिन उनके काम अलग-अलग हैं:
  • tags स्ट्रक्चर्ड {name, value} पेयर हैं (प्रति सेंड अधिकतम 20; नाम 1 से 32 कैरेक्टर, वैल्यू 1 से 64, केवल ASCII [A-Za-z0-9_-], केस-सेंसिटिव, एक सेंड में नाम यूनीक)। ये फ़र्स्ट-क्लास फ़िल्टर डाइमेंशन हैं: टैग के अनुसार मैसेज लिस्ट फ़िल्टर करें। इन्हें campaign या experiment_variant जैसे लो-कार्डिनैलिटी लेबल के लिए उपयोग करें।
  • metadata एक आर्बिट्रेरी JSON ऑब्जेक्ट है (सीरियलाइज़्ड अधिकतम 2 KB)। यह स्टोर किया जाता है, API रीड पर लौटाया जाता है, और हर webhook इवेंट पर इको किया जाता है, लेकिन यह फ़िल्टर डाइमेंशन नहीं है। इसे राउंड-ट्रिप कॉन्टेक्स्ट के लिए उपयोग करें: इंटरनल ID, फ़ॉरेन key, कुछ भी जो आप हर इवेंट के साथ वापस चाहते हैं।
कोड उदाहरण
{
  "tags": [{ "name": "campaign", "value": "spring-2026" }],
  "metadata": { "user_id": "usr_12345", "order_id": "ord_98765" }
}

फ़ील्ड रेफ़रेंस

फ़ील्डटाइपआवश्यकसीमाएँ / नोट्स
tostring (E.164)हाँप्रति मैसेज एक प्राप्तकर्ता
fromstringहाँ*स्वामित्व वाला E.164 नंबर, अल्फ़ान्यूमेरिक सेंडर ID (3–11 chars, कम से कम एक अक्षर), या शॉर्ट कोड (5–6 अंक)
textstringहाँ*कम से कम 1 कैरेक्टर; अधिकतम 12 सेगमेंट
categorystringहाँ*transactional, marketing, authentication, या service
tags{name, value}[]नहींअधिकतम 20; नाम 1–32 chars, वैल्यू 1–64 chars; केवल [A-Za-z0-9_-]
metadataobjectनहींआर्बिट्रेरी JSON, सीरियलाइज़्ड अधिकतम 2 KB
optionsobjectनहींप्रति-मैसेज प्रोसेसिंग सेटिंग्स। केवल smart_encoding उपलब्ध है; देखें सेगमेंट और एन्कोडिंग
* फ़्री-टेक्स्ट सेंड पर आवश्यक। टेम्प्लेट सेंड इसके बजाय टेम्प्लेट से बॉडी, कैटेगरी, और प्रेषक प्रदान करता है, और इन तीनों फ़ील्ड को अस्वीकार करता है।

टेम्प्लेट के साथ भेजना

text कंपोज़ करने के बजाय, सेंड के template ऑब्जेक्ट को Bird के बिल्ट-इन टेम्प्लेट में से एक का रेफ़रेंस दें। टेम्प्लेट बॉडी, कैटेगरी, और प्रेषक प्रदान करता है, इसलिए text, category, from, और media_urls इसके साथ स्वीकार नहीं किए जाते। कैटलॉग, हर टेम्प्लेट के वेरिएबल, और पूरा टेम्प्लेट-सेंड कॉन्ट्रैक्ट SMS templates में हैं।

सेगमेंट और एन्कोडिंग

SMS की बिलिंग प्रति सेगमेंट होती है। GSM-7 एन्कोडिंग में फ़िट होने वाले मैसेज को प्रति सिंगल सेगमेंट 160 कैरेक्टर मिलते हैं; UCS-2 (emoji, CJK, या अन्य नॉन-GSM कैरेक्टर से ट्रिगर) 70 तक गिर जाता है। लंबे मैसेज मल्टीपार्ट सेगमेंट में विभाजित होते हैं जिनकी प्रति-सेगमेंट सीमा थोड़ी कम होती है। हर रिस्पॉन्स रिज़ॉल्व्ड segments रिपोर्ट करता है: बिल योग्य count, encoding, और कैरेक्टर काउंट। सेगमेंट वह इकाई है जिस पर आपकी बिलिंग होती है; देखें लागत।
जब टाइपोग्राफ़िक कैरेक्टर ही बॉडी के GSM-7 से बाहर होने का एकमात्र कारण हों, तो स्मार्ट एन्कोडिंग इसके सेगमेंट काउंट को कम कर सकती है। options.smart_encoding को true सेट करें और Bird भेजने से पहले कर्ली कोट्स, डैश, एलिप्सिस, और समान कैरेक्टर को GSM-7 समकक्षों से बदल देता है। यह डिफ़ॉल्ट रूप से बंद है क्योंकि यह आपकी कंपोज़ की गई बॉडी को बदलता है।
पूर्ण कैरेक्टर सेट, एक्सटेंशन-टेबल कैरेक्टर जो दो स्लॉट लेते हैं, emoji साइज़िंग, स्मार्ट एन्कोडिंग क्या बदलती है, और सेगमेंट गणित के लिए Character limits देखें।

बैच सेंडिंग

POST /v1/sms/batches एक अनुरोध में 100 तक स्वतंत्र संदेश भेजता है। बैच अनुरोध sms_batch अनुरोध दर सीमित करने की नीति का उपयोग करते हैं, जो एकल भेजने के लिए sms_send नीति से अलग है। बॉडी एक JSON ऑब्जेक्ट है जिसका messages ऐरे पेलोड बनाना से संदेश ऑब्जेक्ट रखता है:
const result = await bird.sms.sendBatch({
  messages: [
    {
      from: "+15557654321",
      to: "+15551111111",
      text: "Hi Alice!",
      category: "marketing",
    },
    {
      from: "+15557654321",
      to: "+15552222222",
      text: "Hi Bob!",
      category: "marketing",
    },
  ],
});
वैलिडेशन सब-या-कुछ-नहीं है: अगर बैच में कोई भी संदेश अमान्य है, तो पूरा अनुरोध 422 के साथ अस्वीकार हो जाता है और कुछ भी नहीं भेजा जाता, इसलिए बैच कभी आंशिक रूप से लागू नहीं होता। सफलता पर 202 प्रतिक्रिया में हर स्वीकृत संदेश सबमिशन क्रम में data के अंतर्गत होता है, साथ ही accepted_count के साथ एक summary भी। वहाँ से हर संदेश स्वतंत्र है: एक प्राप्तकर्ता की विफलता दूसरों को प्रभावित नहीं करती।

एसिंक मॉडल: 202 का मतलब क्या है

सफल भेजने पर 202 Accepted एक मैसेज ID और status: accepted के साथ लौटता है। अनुरोध विफलताएँ तुरंत लौटती हैं: एक अमान्य फ़ील्ड, सेगमेंट सीमा से अधिक बॉडी, कोई गंतव्य देश जो आपने सक्षम नहीं किया है, या अमान्य सेंडर 422 लौटाता है। बिना वॉलेट बैलेंस वाले वर्कस्पेस को 402 मिलता है।
डिलीवरी एसिंक्रोनस रूप से होती है। जब Bird संदेश कैरियर को सौंपता है तो वह sent में चला जाता है। फिर एक डिलीवरी रसीद इवेंट और वेबहुक तथा रीड एंडपॉइंट के माध्यम से delivered, undelivered, failed, या expired सेट करती है। इस डिज़ाइन के तीन परिणाम हैं:
  • लागत स्वीकृति के बाद मूल्यांकित होती है। संदेश पर cost स्वीकृति समय पर null होता है और प्रोसेसिंग के दौरान Bird द्वारा मूल्य निर्धारित होने पर भरा जाता है। अब तक की लागत देखने के लिए संदेश वापस पढ़ें या डिलीवरी इवेंट की प्रतीक्षा करें; लागत और बिलिंग घटकों और कब कोई घटक बिना मूल्य रहता है, इसका विवरण देता है।
  • 202 के बाद भी संदेश अस्वीकार हो सकता है। अगर प्रोसेसिंग के दौरान शुल्क विफल होता है, तो संदेश sms.rejected वेबहुक के साथ rejected पर समाप्त होता है और आपसे बिल नहीं लिया जाता; खाली वॉलेट last_error.code: insufficient_balance के रूप में सामने आता है।
  • रीड 202 से थोड़ा पीछे रह सकते हैं। संदेश 202 के तुरंत बाद रीड एंडपॉइंट पर दिखने लगता है, इसलिए भेजने के तुरंत बाद किया गया 404 कुछ ही क्षणों में हल हो जाता है।

आरक्षित फ़ील्ड

Bird वर्तमान में निम्नलिखित अनुरोध फ़ील्ड को 422 SMSUnsupportedFeature के साथ अस्वीकार करता है:
scheduled_at, validity_period, media_urls, messaging_profile_id, broadcast_id, campaign_id, audience_id, contact_id, topic_id, personalization, options.max_price_per_segment, options.track_clicks
इन फ़ील्ड को भेजने में शामिल न करें।

सुरक्षित रूप से फिर से प्रयास करना

हर लॉजिकल भेजने के लिए एक अद्वितीय मान के साथ Idempotency-Key हेडर भेजें। अगर अनुरोध सफल होता है लेकिन प्रतिक्रिया नहीं मिलती, तो वही अनुरोध और कुंजी दोबारा भेजें। Bird डुप्लिकेट संदेश भेजने के बजाय मूल परिणाम लौटाता है। कुंजी प्रारूप और अवधारण के लिए idempotency देखें।

लागत और बिलिंग

आउटबाउंड SMS प्रति सेगमेंट बिल होता है। आप क्या भुगतान करते हैं यह गंतव्य देश और कैरियर पर निर्भर करता है; कुछ रूट तृतीय-पक्ष अधिभार जोड़ते हैं, जैसे US 10DLC कैरियर शुल्क।
संदेश का cost शुल्क को नामित घटकों में विभाजित करता है। transaction_amount वह है जो Bird ने संदेश वहन करने के लिए लिया, passthrough_amount कोई भी पारित तृतीय-पक्ष शुल्क है, और amount मूल्यांकित घटकों का योग है, currency_code में अंकित। जिस घटक का मूल्य निर्धारित नहीं हुआ वह "0.00000" के बजाय null है, इसलिए जिस संदेश का अधिभार कभी हल नहीं हुआ वह amount को केवल वहन शुल्क के रूप में रिपोर्ट करता है। मैसेज संदर्भ हर फ़ील्ड का दस्तावेज़ीकरण करता है।
अधिभार सर्वोत्तम प्रयास है। Bird डिलीवरी रसीद रिकॉर्ड करते समय इसे एक सीमित विंडो में हल करता है। अगर उस विंडो में हल नहीं होता, तो passthrough_amount स्थायी रूप से null रहता है: Bird इसे फिर से प्रयास नहीं करता, और amount वहन शुल्क ही रहता है।
इनबाउंड SMS दो पंक्तियों पर बिल होता है: प्रति-सेगमेंट इनबाउंड दर, और जहाँ लागू हो वहाँ इनबाउंड कैरियर अधिभार। दोनों प्राप्त संदेश के अपने cost पर रिपोर्ट होते हैं: दर transaction_amount के रूप में, अधिभार passthrough_amount के रूप में। अपने आउटबाउंड समकक्ष के विपरीत, इनबाउंड अधिभार संदेश स्वीकृति के समय मूल्यांकित होता है, डिलीवरी के समय नहीं, इसलिए यह बाद में कभी नहीं भरा जाता।
प्रति संदेश लागत और सेगमेंट SMS लॉग में देखें।

अगले कदम

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

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

इस विषय के लिए डॉक्यूमेंटेशन, गाइड और उदाहरणों के साथ आगे बढ़ें। संसाधन अंग्रेज़ी में हैं।

अभ्यास करें और इम्प्लीमेंटेशन ब्रीफ़ पाएँ