SMS भेजना

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

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

आपका वर्कस्पेस SMS केवल उन देशों में भेजता है जो उसकी गंतव्य अनुमति सूची में हैं। आपके संगठन का होम देश उसकी बिज़नेस प्रोफ़ाइल के पंजीकरण पते का देश होता है, या पंजीकरण पते में देश न होने पर बिलिंग पते का देश। आपका वर्कस्पेस खाली अनुमति सूची से शुरू होता है। जब भी होम देश सेट किया जाता है या बदला जाता है, Bird उस देश को अनुमति सूची में जोड़ देता है। अनुमति सूची से बाहर के देश में भेजे गए संदेश को 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);

msg = client.sms.send(
    from_="+15557654321",
    to="+15551234567",
    text="Your verification code is 123456.",
    category="authentication",
)
print(msg.id, msg.status)

msg, err := client.Sms.Send(context.Background(), bird.SmsSendParams{
	From:     "+15557654321",
	To:       "+15551234567",
	Text:     "Your verification code is 123456.",
	Category: bird.SMSCategoryAuthentication,
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$message = $bird->sms->send(
    from: '+15557654321',
    to: '+15551234567',
    text: 'Your verification code is 123456.',
    category: 'authentication',
);
echo $message->getId(), ' ', $message->getStatus();

bird sms send --body-file - <<'JSON'
{
  "to": "+14155550100",
  "from": "+15557654321",
  "text": "Your verification code is 123456.",
  "category": "authentication",
  "options": {
    "smart_encoding": true
  },
  "tags": [
    {
      "name": "campaign",
      "value": "signup"
    }
  ],
  "metadata": {
    "user_id": "usr_12345"
  }
}
JSON

curl -X POST https://eu1.platform.bird.com/v1/sms/messages \
  -H "Authorization: Bearer bk_eu1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+31612345678",
    "from": "Bird",
    "text": "Your Bird verification code is 481920. It expires in 10 minutes.",
    "category": "authentication"
  }'

अपने क्षेत्रीय होस्ट (https://us1.platform.bird.com या https://eu1.platform.bird.com) के साथ उसी से मेल खाने वाली bk_{region}_... कुंजी इस्तेमाल करें। प्रतिक्रिया में स्वीकार किया गया संदेश मिलता है:

कोड उदाहरण

{
  "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 है, क्योंकि कीमत प्रोसेसिंग के दौरान तय होती है। आगे क्या होता है, यह एसिंक्रोनस मॉडल में बताया गया है।

पेलोड बनाना

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

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 गंतव्य और श्रेणी के अनुसार प्रेषक चुनता है। वर्कस्पेस टेम्पलेट के लिए आपका अपना from प्रेषक ज़रूरी है।

प्रेषक ID लेने, हर देश की उसके लिए शर्तें जानने और हर देश में उसका पंजीकरण करने की जानकारी SMS प्रेषक ID में है।

मुख्य टेक्स्ट और श्रेणी

text संदेश का मुख्य टेक्स्ट है, जिसमें कम से कम एक अक्षर होना चाहिए। इसका बिल और डिलीवरी सेगमेंट में होती है; एक भेजने की सीमा 12 सेगमेंट है (लगभग 1,836 GSM-7 अक्षर, या मुख्य टेक्स्ट विस्तारित UCS-2 एन्कोडिंग का उपयोग करे तो 804)। सीमा से लंबा टेक्स्ट काटा नहीं जाता, बल्कि 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, फ़ॉरेन कुंजियाँ, या कुछ भी जो आप हर इवेंट के साथ वापस पाना चाहते हैं।

कोड उदाहरण

{
  "tags": [{ "name": "campaign", "value": "spring-2026" }],
  "metadata": { "user_id": "usr_12345", "order_id": "ord_98765" }
}

फ़ील्ड संदर्भ

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

* फ़्री-टेक्स्ट भेजने के लिए from, text और category ज़रूरी हैं। टेम्पलेट से भेजने पर बॉडी और कैटेगरी टेम्पलेट से मिलती हैं, और text व category अस्वीकार किए जाते हैं। बिल्ट-इन टेम्पलेट from को अस्वीकार करते हैं; वर्कस्पेस टेम्पलेट में यह ज़रूरी है।

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

बिल्ट-इन टेम्पलेट या प्रकाशित वर्कस्पेस टेम्पलेट भेजने के लिए template सेट करें। वर्कस्पेस टेम्पलेट बनाने की सुविधा API प्रीव्यू में है। कैटलॉग, वेरिएबल और सेंडर से जुड़े नियम SMS टेम्पलेट में दिए गए हैं।

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

SMS का बिल प्रति सेगमेंट बनता है। जो संदेश GSM-7 एन्कोडिंग में आ जाता है, उसे एक सेगमेंट में 160 अक्षर मिलते हैं। UCS-2 में, जो इमोजी, CJK या अन्य गैर-GSM अक्षरों से लागू होता है, यह सीमा घटकर 70 हो जाती है। लंबे संदेश कई हिस्सों वाले सेगमेंट में बँट जाते हैं, और हर सेगमेंट की सीमा थोड़ी कम होती है। हर प्रतिक्रिया लागू हुआ segments बताती है: बिल योग्य count, encoding और अक्षरों की संख्या। आपका बिल सेगमेंट के आधार पर बनता है; लागत देखें।

जब किसी बॉडी के GSM-7 से बाहर जाने का एकमात्र कारण टाइपोग्राफ़िक अक्षर हों, तो स्मार्ट एन्कोडिंग उसके सेगमेंट की संख्या कम कर सकती है। options.smart_encoding को true पर सेट करें, तब Bird भेजने से पहले घुमावदार उद्धरण चिह्नों, डैश, एलिप्सिस और ऐसे ही अक्षरों को उनके GSM-7 समकक्षों से बदल देता है। यह डिफ़ॉल्ट रूप से बंद रहती है, क्योंकि यह आपकी लिखी बॉडी को बदल देती है।

पूरे अक्षर सेट, दो स्थान लेने वाले एक्सटेंशन-टेबल अक्षरों, इमोजी के आकार, स्मार्ट एन्कोडिंग किन अक्षरों को बदलती है और सेगमेंट की गणना के लिए अक्षर सीमाएँ देखें।

बैच में भेजना

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",
    },
  ],
});

batch = client.sms.send_batch(
    messages=[
        {
            "from_": "+15557654321",
            "to": "+15551111111",
            "text": "Hi Alice!",
            "category": "marketing",
        },
        {
            "from_": "+15557654321",
            "to": "+15552222222",
            "text": "Hi Bob!",
            "category": "marketing",
        },
    ]
)
for msg in batch.data:
    print(msg.id, msg.status)

batch, err := client.Sms.SendBatch(context.Background(), bird.SmsSendBatchParams{
	Messages: []bird.SmsSendParams{
		{
			From: "+15557654321", To: "+15551111111",
			Text: "Hi Alice!", Category: bird.SMSCategoryMarketing,
		},
		{
			From: "+15557654321", To: "+15552222222",
			Text: "Hi Bob!", Category: bird.SMSCategoryMarketing,
		},
	},
})
if err != nil {
	log.Fatal(err)
}
for _, msg := range batch.Data {
	fmt.Println(msg.Id, *msg.Status)
}

$batch = $bird->sms->sendBatch(messages: [
    (new SMSMessageSendRequest())
        ->setFrom('+15557654321')
        ->setTo('+15551111111')
        ->setText('Hi Alice!')
        ->setCategory('marketing'),
    (new SMSMessageSendRequest())
        ->setFrom('+15557654321')
        ->setTo('+15552222222')
        ->setText('Hi Bob!')
        ->setCategory('marketing'),
]);
foreach ($batch->getData() ?? [] as $item) {
    echo $item->getId(), ' ', $item->getStatus(), "\n";
}

curl -X POST "https://{region}.platform.bird.com/v1/sms/batches" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "to": "+15551111111",
        "from": "+15557654321",
        "text": "Hi Alice!",
        "category": "marketing"
      },
      {
        "to": "+15552222222",
        "from": "+15557654321",
        "text": "Hi Bob!",
        "category": "marketing"
      }
    ]
  }'

सत्यापन या तो पूरा सफल होता है या पूरा विफल: अगर बैच का कोई भी संदेश अमान्य है, तो पूरा अनुरोध 422 के साथ अस्वीकार हो जाता है और कुछ भी नहीं भेजा जाता। इसलिए बैच कभी आंशिक रूप से लागू नहीं होता। सफल होने पर 202 प्रतिक्रिया में हर स्वीकृत संदेश जमा करने के क्रम में data के अंतर्गत होता है, साथ में accepted_count वाला summary भी। इसके बाद हर संदेश स्वतंत्र होता है: एक प्राप्तकर्ता की विफलता का असर दूसरों पर कभी नहीं पड़ता।

एसिंक मॉडल: 202 का मतलब

सफल भेजने पर संदेश ID और status: accepted के साथ 202 Accepted लौटता है। अनुरोध की विफलताएँ तुरंत लौटती हैं: अमान्य फ़ील्ड, सेगमेंट सीमा से बड़ी बॉडी, ऐसा गंतव्य देश जिसे आपने सक्षम नहीं किया है, या अमान्य सेंडर होने पर 422 लौटता है। जिस वर्कस्पेस के वॉलेट में बैलेंस नहीं है, उसे 402 मिलता है।

डिलीवरी एसिंक्रोनस रूप से होती है। जब Bird संदेश को कैरियर को सौंपता है, तो संदेश sent स्थिति में चला जाता है। इसके बाद डिलीवरी रसीद इवेंट और वेबहुक तथा रीड एंडपॉइंट के ज़रिए delivered, undelivered, failed या expired सेट करती है। इस डिज़ाइन के तीन परिणाम हैं:

लागत स्वीकृति के बाद तय होती है। संदेश पर cost स्वीकृति के समय null होता है, और प्रोसेसिंग के दौरान Bird भेजने की कीमत तय करते ही भर जाता है। अब तक तय हुआ शुल्क देखने के लिए संदेश को दोबारा पढ़ें या डिलीवरी इवेंट की प्रतीक्षा करें; लागत और बिलिंग में इसके घटक बताए गए हैं और यह भी कि कोई घटक कब बिना कीमत के रहता है।
202 के बाद भी संदेश अस्वीकार हो सकता है। अगर प्रोसेसिंग के दौरान शुल्क नहीं कट पाता, तो संदेश rejected स्थिति में समाप्त होता है, sms.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-Key हेडर के साथ सुरक्षित रूप से फिर से प्रयास करें।
अपना पहला SMS भेजना: एक वीडियो जो डैशबोर्ड में यही सेटअप चरण-दर-चरण दिखाता है

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

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

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