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

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

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

1. एक API key बनाएँ

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

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

export BIRD_API_KEY="bk_us1_..."

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 server से जुड़े एजेंट 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 आपके लॉगिन का उपयोग करता है, और 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);

from bird import APIError, Bird

with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
    try:
        message = client.sms.send(
            to="+14155550100",
            template="bird_otp_verification",
            parameters={"code": "493021"},
        )
        print(message.id, message.status)
    except APIError as err:
        print("send failed:", err)

package main

import (
	"context"
	"fmt"
	"log"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey("bk_XXXXXXXXXXXXXXXXXXXXXXXX"))
	if err != nil {
		log.Fatal(err)
	}

	msg, err := client.Sms.Send(context.Background(), bird.SmsSendParams{
		To:         "+14155550100",
		Template:   "bird_otp_verification",
		Parameters: map[string]any{"code": "493021"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

<?php

declare(strict_types=1);

require __DIR__ . '/../vendor/autoload.php';

use MessageBird\Bird;

$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');

$message = $bird->sms->send(
    to: '+14155550100',
    template: 'bird_otp_verification',
    parameters: ['code' => '493021'],
);

echo $message->getId(), ' ', $message->getStatus(), "\n";

bird sms send \
  --parameters '{"code":"493021"}' \
  --template bird_otp_verification \
  --to +14155550100

curl -X POST https://us1.platform.bird.com/v1/sms/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550100",
    "template": {
      "slug": "bird_otp_verification",
      "parameters": { "code": "493021" }
    }
  }'

यदि आपकी कुंजी 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);

from bird import APIError, Bird

with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
    try:
        message = client.sms.get("SMS_MESSAGE_ID")
        print(message.id, message.status)
    except APIError as err:
        print("read failed:", err)

package main

import (
	"context"
	"fmt"
	"log"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey("bk_XXXXXXXXXXXXXXXXXXXXXXXX"))
	if err != nil {
		log.Fatal(err)
	}

	var msg bird.SMSMessage
	if err := client.Get(context.Background(), "/v1/sms/messages/SMS_MESSAGE_ID", &msg); err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

<?php

declare(strict_types=1);

require __DIR__ . '/../vendor/autoload.php';

use MessageBird\Bird;

$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');

$message = $bird->sms->get('SMS_MESSAGE_ID');

echo $message->getId(), ' ', $message->getStatus(), "\n";

bird sms get SMS_MESSAGE_ID

curl https://us1.platform.bird.com/v1/sms/messages/SMS_MESSAGE_ID \
  -H "Authorization: Bearer $BIRD_API_KEY"

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

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

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

विफल भेजने को ठीक करें

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

अगले कदम

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