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

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

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

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

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

पूरी कुंजी केवल एक बार, बनाते समय दिखाई जाती है। इसे किसी सुरक्षित जगह कॉपी करें, फिर 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 सर्वर से जुड़े एजेंट 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 कुंजी में sms स्कोप नहीं है। कुंजी के स्कोप संपादित करें या sms:write वाली नई कुंजी बनाएँ।

अगले चरण

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