SMS टेम्पलेट

टेम्पलेट एक दोबारा इस्तेमाल होने वाला संदेश है, जिसे आप संदर्भ से भेजते हैं और उसमें एक-बार के सत्यापन कोड या ऑर्डर नंबर जैसे मान देते हैं। Bird के बिल्ट-इन system टेम्पलेट ऑथेंटिकेशन और ट्रांज़ैक्शनल संदेशों के लिए हैं। वर्कस्पेस टेम्पलेट बनाने की सुविधा API प्रीव्यू में है; डैशबोर्ड में बिल्ट-इन कैटलॉग ही दिखता रहता है।

टेम्पलेट संदेश की वह श्रेणी तय करता है, जिससे गंतव्य के अनुपालन की जाँच होती है। बिल्ट-इन टेम्पलेट गंतव्य के लिए प्रेषक भी चुनते हैं, इसलिए आप from छोड़ देते हैं। वर्कस्पेस टेम्पलेट के लिए आपको अपना प्रेषक देना होता है, ठीक मुक्त-टेक्स्ट संदेश भेजने की तरह।

डैशबोर्ड में टेम्पलेट देखना

SMS के अंतर्गत Templates पेज पर बिल्ट-इन टेम्पलेट सूचीबद्ध हैं। नाम से खोजें या स्थिति और श्रेणी के अनुसार फ़िल्टर करें।

SMS Templates टैब: टेम्पलेट की तालिका के ऊपर Status और Category फ़िल्टर के साथ एक खोज बॉक्स; हर पंक्ति में नाम, Active स्थिति, श्रेणी, EN भाषा चिप और System स्कोप दिखता है, और कॉलम Name, Status, Category, Language, Scope और Updated हैं।

हर पंक्ति में वे फ़ील्ड दिखते हैं, जिनकी ज़रूरत टेम्पलेट चुनने और भेजने के लिए होती है:

Name: टेम्पलेट का प्रदर्शित नाम और उसका slug (उदाहरण के लिए bird_order_confirmation)। स्लग वह हैंडल है, जिसे आप भेजते समय पास करते हैं; यह बनाते समय तय हो जाता है और बदलता नहीं।
Status: बिल्ट-इन टेम्पलेट Active होते हैं और भेजने के लिए तैयार रहते हैं। वर्कस्पेस टेम्पलेट प्रकाशित होने तक Draft रहते हैं, फिर Active हो जाते हैं। साझा स्थिति फ़ील्ड में नए मान भी आ सकते हैं, इसलिए इसे खुला सेट मानें।
Category: सामग्री का वर्गीकरण (transactional, marketing या authentication), जो टेम्पलेट से भेजे गए संदेशों पर लागू होता है।
Language: वे भाषाएँ जिनमें टेम्पलेट उपलब्ध है, BCP 47 टैग के रूप में। पहली कुछ भाषाएँ चिप के रूप में दिखती हैं, और जब कोई टेम्पलेट कई भाषाओं में स्थानीयकृत होता है तो बाकी के लिए +N दिखता है।
Scope: Bird के बिल्ट-इन टेम्पलेट के लिए System। Workspace उन टेम्पलेट को दर्शाता है जिन्हें आप API प्रीव्यू के ज़रिए बनाते हैं।
Updated: टेम्पलेट में आखिरी बार कब बदलाव हुआ। बिल्ट-इन टेम्पलेट में कोई तारीख नहीं दिखती।

टेम्पलेट में क्या होता है

नाम, श्रेणी और भाषाओं के साथ, हर टेम्पलेट वे variables तय करता है जिन्हें वह भेजते समय भरता है। हर variable में एक key, type, एक required फ़्लैग और पढ़ने योग्य constraint होता है। बिल्ट-इन टेम्पलेट में टाइप किए गए स्लॉट होते हैं; वर्कस्पेस टेम्पलेट सामान्य text स्लॉट मान लेते हैं और स्केलर पैरामीटर मान स्वीकार करते हैं। sensitive variable को संग्रहीत संदेश सामग्री में बदल दिया जाता है। डिलीवरी के लिए ज़रूरी टेक्स्ट ट्रांसपोर्ट कतारों में फिर भी रहता है। हर ज़रूरी variable दें और कोई अघोषित कुंजी न भेजें।

टेम्पलेट एक या अधिक languages में उपलब्ध होता है, और जब किसी भेजे गए संदेश में कोई भाषा नहीं दी जाती, तो उसे default_language मिलती है। अगर आप ऐसी भाषा माँगते हैं जिसमें टेम्पलेट उपलब्ध नहीं है, तो Bird फ़ॉलबैक करता है: पहले उसी भाषा के व्यापक रूप पर, फिर डिफ़ॉल्ट भाषा पर, क्योंकि SMS टेम्पलेट में on_missing_language का डिफ़ॉल्ट fallback होता है। बिल्ट-इन टेम्पलेट language_source_required: false का उपयोग करते हैं। वर्कस्पेस टेम्पलेट किसी भाषा को अनिवार्य कर सकते हैं या on_missing_language: fail सेट कर सकते हैं; ये नीतियाँ तुरंत लागू होती हैं, जबकि सामग्री और डिफ़ॉल्ट भाषा के बदलाव प्रकाशन पर लागू होते हैं।

API से टेम्पलेट की सूची पाना

GET /v1/sms/templates टेम्पलेट सारांशों का कर्सर-पेजिनेटेड पेज लौटाता है। next_cursor के शून्य (null) होने तक starting_after का उपयोग करके उसका पालन करें; एक पेज पूरा कैटलॉग नहीं होता। टेम्पलेट पढ़ने के लिए sms_management स्कोप वाली API कुंजी चाहिए, जो भेजने में उपयोग होने वाले sms स्कोप से अलग है। scope, category, status या language से फ़िल्टर करें, या q से खोजें:

for await (const tpl of bird.smsTemplates.list({ scope: "system" })) {
  console.log(tpl.id, tpl.slug);
}

for template in client.sms_templates.list(scope="system"):
    print(template.id, template.slug)

for tpl, err := range client.SmsTemplates.List(context.Background(), bird.SMSTemplateListParams{
	Scope: "system",
}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(tpl.Id, *tpl.Slug)
}

foreach ($bird->smsTemplates->list(['scope' => 'system']) as $template) {
    echo $template->getId(), ' ', $template->getSlug(), "\n";
}

bird sms templates list

curl "https://eu1.platform.bird.com/v1/sms/templates?category=authentication" \
  -H "Authorization: Bearer bk_eu1_..."

टेम्पलेट सारांशों में पहचान, श्रेणी, स्थिति, उपलब्ध भाषाएँ और ड्राफ़्ट/लाइव संस्करण संदर्भ होते हैं। इनमें स्रोत टेक्स्ट और variables नहीं होते। GET /v1/sms/templates/{template_ref} से slug या ID द्वारा टेम्पलेट प्राप्त करें। संपादन योग्य वर्कस्पेस सामग्री देखने के लिए उसका draft_version_id उपयोग करें, या भेजे जाने वाले संदेश जो उपयोग करते हैं उसे देखने के लिए उसका live_version_id। नए वर्कस्पेस टेम्पलेट का प्रकाशन से पहले कोई लाइव संस्करण नहीं होता।

चुने गए संस्करण को GET /v1/sms/templates/{template_ref}/versions/{version_id} से पढ़ें। प्रतिक्रिया में variables और भाषा के अनुसार कुंजीबद्ध सामग्री मैप होता है। एक भाषा प्राप्त करने के लिए /languages/{language} जोड़ें। सूची का language फ़िल्टर प्रकाशित सामग्री से मेल खाता है; केवल ड्राफ़्ट वाली भाषाएँ मेल नहीं खातीं।

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

API प्रीव्यू में वर्कस्पेस टेम्पलेट बनाना

sms_management लिखने की अनुमति वाली API कुंजी का उपयोग करें। JSON अनुरोध अपनी कुंजी के क्षेत्रीय API होस्ट पर Authorization: Bearer <API_KEY> और Content-Type: application/json के साथ भेजें। हर बदलाव को उसकी अपनी Idempotency-Key दें। उस कुंजी का दोबारा उपयोग केवल उसी अनुरोध का फिर से प्रयास करते समय करें।

POST /v1/sms/templates और {"slug":"order-shipped","category":"transactional"} के साथ टेम्पलेट बनाएँ। 201 प्रतिक्रिया में id और draft_version_id होते हैं। टेम्पलेट एक खाली अंग्रेज़ी ड्राफ़्ट के साथ शुरू होता है। अगले कॉल के लिए दोनों ID सहेजें।
PUT /v1/sms/templates/{id}/versions/{draft_version_id}/languages/en और {"text":"Your order {{ order_number }} has shipped."} के साथ टेक्स्ट सहेजें। 200 प्रतिक्रिया में draft_revision शामिल होता है।
POST /v1/sms/templates/{id}/versions/{draft_version_id}/submit के साथ प्रकाशित करें और उस रिविज़न को {"expected_revision":1} के रूप में भेजें (1 की जगह लौटाया गया मान रखें)। valid: true वाली 200 प्रतिक्रिया प्रकाशित वर्ज़न की पहचान बताती है। 422 का अर्थ है कि ड्राफ़्ट की सामग्री अमान्य है। लौटाई गई भाषा संबंधी समस्याएँ ठीक करें और नई idempotency कुंजी के साथ फिर से भेजें।

प्रकाशित करने के लिए हर भाषा में टेक्स्ट खाली नहीं होना चाहिए और सभी भाषाओं में एक जैसे वेरिएबल होने चाहिए। प्रकाशन तुरंत लागू होता है और इसके लिए प्रदाता की स्वीकृति नहीं चाहिए। API प्रीव्यू, डुप्लिकेट बनाना, ड्राफ़्ट को लाइव सामग्री पर रीसेट करना और किसी प्रकाशित वर्ज़न पर रोलबैक करना भी सपोर्ट करता है। डैशबोर्ड में संपादन उपलब्ध नहीं है।

टेम्पलेट सेटिंग अपडेट करने या रोलबैक करने से पहले मौजूदा रिविज़न पढ़ें। भाषा सहेजते समय भी रिविज़न गार्ड शामिल किया जा सकता है। पुराना गार्ड होने पर 409 लौटता है। प्रीव्यू चुने गए वर्ज़न और पैरामीटर से भेजने से पहले रेंडर किया गया टेक्स्ट, तय हुई भाषा, एन्कोडिंग और सेगमेंट की संख्या बताता है।

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

भेजते समय text की जगह template ऑब्जेक्ट सेट करें। category और media_urls न दें। नीचे दिए गए बिल्ट-इन टेम्पलेट के लिए from भी न दें। वर्कस्पेस टेम्पलेट के लिए from ज़रूरी है और उसका एक प्रकाशित वर्ज़न होना चाहिए।

बिल्ट-इन ऑथेंटिकेशन टेम्पलेट साझा सेंडर ब्रांड भी चुनता है: bird_otp_verification_ttl Authifly का उपयोग करता है, जबकि bird_otp_verification_ttl_bird_verify Bird Verify का उपयोग करता है। गंतव्य तय करता है कि सेंडर ब्रांड नाम, शॉर्ट कोड या फ़ोन नंबर के रूप में दिखेगा।

बिल्ट-इन टेम्पलेट भेजें:

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

client.sms.send(
    to="+14155550100",
    template="bird_otp_verification",
    parameters={"code": "123456"},
)

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

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

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

curl -X POST "https://eu1.platform.bird.com/v1/sms/messages" \
  -H "Authorization: Bearer bk_eu1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550100",
    "template": {
      "slug": "bird_otp_verification_ttl",
      "language": "en",
      "parameters": { "code": "481920", "ttl": "10" }
    }
  }'

slug कैटलॉग में टेम्पलेट का हैंडल है (आप टेम्पलेट को उसके id से भी पहचान सकते हैं)। language स्थानीयकृत मुख्य टेक्स्ट चुनता है। टेम्पलेट की डिफ़ॉल्ट भाषा के लिए इसे छोड़ दें। parameters टेम्पलेट के हर वेरिएबल के लिए मान देता है, जिसकी कुंजी वेरिएबल का नाम होती है। कोई ज़रूरी वेरिएबल न होने, अघोषित कुंजी होने, किसी मान के अपने वेरिएबल की शर्त से मेल न खाने, या सीरियलाइज़ करने पर 16 KB से बड़ा parameters ऑब्जेक्ट होने पर अनुरोध 422 के साथ अस्वीकार हो जाता है।

202 प्रतिक्रिया में चुना गया from, टेम्पलेट की श्रेणी, टेम्पलेट और वर्ज़न की ID, सोर्स हैश, और अनुरोध की गई व तय हुई भाषाएँ शामिल होती हैं। ऑथेंटिकेशन संदेश का टेक्स्ट **REDACTED** के रूप में लौटाया जाता है। स्वीकार किए गए संदेश रेंडर की गई सामग्री और चुना गया वर्ज़न बनाए रखते हैं, भले ही आप बाद में टेम्पलेट प्रकाशित करें, रोलबैक करें या हटा दें।

भेजने से जुड़ी बाकी सभी बातें (प्राप्तकर्ता, टैग, मेटाडेटा, गंतव्य अनुमति-सूची और एसिंक 202 मॉडल) ठीक वैसे ही काम करती हैं जैसे फ़्री-टेक्स्ट भेजने में करती हैं।

अगले चरण

SMS भेजना: भेजने वाले पेलोड में template फ़ील्ड जोड़ें।
SMS लॉग: भेजा गया संदेश खोजें और उसके जीवनचक्र को ट्रैक करें।
इवेंट: हर संदेश के डिलीवरी इवेंट प्राप्त करें।
टेम्पलेट के साथ SMS भेजना: एक वीडियो, जिसमें टर्मिनल से पहले से स्वीकृत टेम्पलेट में से एक भेजा जाता है

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

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