किसी दूसरे प्रदाता से SMS माइग्रेट करें

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

माइग्रेशन की चेकलिस्ट:

अपने गंतव्य देश सक्षम करें
प्रेषक सेट अप करें
POST /v1/sms/messages के लिए भेजने की कॉल मैप करें
अपनी ऑप्ट-आउट सूची साथ लाएँ
डिलीवरी रिपोर्ट को वेबहुक पर ले जाएँ
कटओवर से पहले सिम्युलेटेड गंतव्यों पर परीक्षण करें

चरण 3, 4 और 5 इस पर निर्भर करते हैं कि आप कौन-सा प्रदाता छोड़ रहे हैं। आपकी प्रदाता गाइड में फ़ील्ड-दर-फ़ील्ड पेलोड मैपिंग, स्टेटस और इवेंट का अनुवाद, और अपनी ऑप्ट-आउट सूची निकालने का तरीका दिया गया है।

चरण 1 और 2 से शुरू करें। SMS माइग्रेशन में सबसे ज़्यादा समय सेंडर पंजीकरण में लगता है: कैरियर और रजिस्ट्री की समीक्षा कोड बदलने से भी अधिक समय ले सकती है। कटओवर की तारीख तय करने से पहले दोनों का दायरा तय करें।

1. अपने गंतव्य देश सक्षम करें

आपके वर्कस्पेस में गंतव्यों की एक अनुमति सूची होती है जो डिफ़ॉल्ट रूप से सब कुछ रोकती है, और शुरुआत में केवल आपके संगठन का अपना देश सक्षम होता है। किसी और देश में भेजने पर Bird के सेंडर तय करने से पहले ही 422 SMSDestinationNotEnabled लौटता है। इसलिए जब तक आप वह देश नहीं खोलते, तब तक सही ढंग से पोर्ट किया गया इंटीग्रेशन भी अपने पहले अंतरराष्ट्रीय संदेश पर विफल होता है।

जिन भी देशों में आप अभी भेजते हैं, उन सभी को SMS > Destinations में सक्षम करें। यह सूची याद के भरोसे नहीं, बल्कि अपने मौजूदा प्रदाता के संदेश लॉग से लें। जो देश छूट जाता है, वह कटओवर के दिन बिना किसी सूचना के एक कमी बन जाता है। जो देश आप सक्षम करते हैं पर कभी उपयोग नहीं करते, वह अनावश्यक जोखिम है। डिफ़ॉल्ट रूप से रोकना SMS पंपिंग से होने वाले नुकसान को भी सीमित करता है, जिसमें प्रीमियम नंबर श्रेणियों पर भेजे गए धोखाधड़ी वाले ट्रैफ़िक का बिल आपसे लिया जाता है।

2. सेंडर सेट करें

फ़्री-टेक्स्ट भेजने पर from वह सेंडर है जो आपके प्राप्तकर्ता को दिखता है। यह तीन में से किसी एक रूप में होता है: अल्फ़ान्यूमेरिक सेंडर ID, E.164 प्रारूप में ऐसा फ़ोन नंबर जो आपके वर्कस्पेस का हो, या शॉर्ट कोड। कौन-से रूप काम करते हैं, यह गंतव्य देश पर निर्भर करता है। जो सेंडर उस देश में मान्य नहीं है, उसे कारण बताने वाले 422 के साथ अस्वीकार किया जाता है। हर रूप के नियम SMS भेजना में दिए गए हैं।

हर रूप कैसे प्राप्त करें:

अल्फ़ान्यूमेरिक सेंडर ID आप स्वयं SMS > Senders में बनाते हैं। जहाँ गंतव्य देश में सेंडर ID का पंजीकरण अनिवार्य है, वहाँ पंजीकरण वहीं जमा करें और उस पर ट्रैफ़िक भेजने से पहले स्वीकृति की प्रतीक्षा करें।
लोकल लॉन्ग कोड पर अमेरिकी व्यावसायिक ट्रैफ़िक के लिए लागू 10DLC ब्रांड और कैंपेन चाहिए, जिन्हें SMS > 10DLC में सेट किया जाता है। टोल-फ़्री नंबरों और समर्पित शॉर्ट कोड के अपने अलग सत्यापन या आवेदन कार्यक्रम हैं। अमेरिका अल्फ़ान्यूमेरिक सेंडर ID बिल्कुल स्वीकार नहीं करता, इसलिए जो यूरोपीय सेंडर ID बाकी हर जगह काम करती है, उसका अमेरिका में कोई समकक्ष नहीं है।
नंबर Numbers वर्कफ़्लो से मिलते हैं। उपलब्धता और किसी भी प्रबंधित प्रोविज़निंग की शर्तें नंबर के प्रकार और गंतव्य पर निर्भर करती हैं। सही तरीके के लिए SMS नंबर देखें। अल्फ़ान्यूमेरिक सेंडर जोड़ने से कोई नंबर प्राप्त नहीं होता।
अपने मौजूदा नंबर बनाए रखना आप स्वयं नहीं कर सकते: Bird में ऐसा कोई पोर्ट-इन प्रवाह नहीं है जिसे आप डैशबोर्ड से चला सकें। अगर आपके सब्सक्राइबर उन नंबरों पर जवाब देते हैं जो अभी आपके हैं, तो कटओवर की तारीख तय करने से पहले सपोर्ट के साथ पोर्ट का अनुरोध करें। पोर्ट और कोड बदलाव को दो अलग घटनाओं के रूप में योजना में रखें।

सिस्टम-टेम्पलेट से भेजने में अनुरोध का एक अलग रूप उपयोग होता है। इसके लिए भी लागू गंतव्य और प्राप्तकर्ता की अनुमति चाहिए। टेम्पलेट स्वयं संदेश का मुख्य भाग, श्रेणी और सेंडर देता है, इसलिए इसके साथ from स्वीकार नहीं किया जाता और Bird गंतव्य के लिए मान्य सेंडर चुनता है।

3. भेजने वाली कॉल को मैप करें

एकल संदेश भेजने का एंडपॉइंट POST /v1/sms/messages है। to, from, text और category के साथ एक JSON पेलोड बनाएँ। सफल कॉल sms_ उपसर्ग वाली संदेश ID के साथ 202 Accepted लौटाती है। डिलीवरी प्रतिक्रिया के बाद होती है, और उसकी जानकारी आपको वेबहुक इवेंट और रीड एंडपॉइंट से मिलती है। पूरा पेलोड SMS भेजना में है; आपके मौजूदा पेलोड से फ़ील्ड-दर-फ़ील्ड मैपिंग आपकी प्रदाता गाइड में है।

कोड पोर्ट करने से पहले इन अंतरों का ध्यान रखें:

हर अनुरोध में एक प्राप्तकर्ता। Bird में प्राप्तकर्ताओं की कोई ऐरे नहीं है। अगर आपका मौजूदा प्रदाता एक कॉल से कई नंबरों पर भेजता है, तो यहाँ हर प्राप्तकर्ता के लिए एक कॉल करें, या एक ही अनुरोध में स्वतंत्र संदेशों का एक बैच भेजें।
फ़्री टेक्स्ट पर category ज़रूरी है, और उसका मान transactional, marketing, authentication या service होता है। ज़्यादातर प्रदाता उद्देश्य को कैंपेन या प्रेषक से अनुमान लगाते हैं; यहाँ आप इसे हर संदेश में बताते हैं। जिस गंतव्य देश में प्रेषक का पंजीकरण ज़रूरी है, वहाँ पंजीकरण किसी एक श्रेणी के लिए स्वीकृत होता है, और उस श्रेणी से बाहर भेजा गया संदेश 422 SenderCategoryNotPermitted के साथ अस्वीकार हो जाता है। प्रेषक की active स्थिति से यह पहले पता नहीं चलता, क्योंकि वह किसी श्रेणी के संदर्भ के बिना बताई जाती है; इसके बजाय हर देश की आवश्यकताएँ पढ़ें। पोर्ट करते समय हर संदेश की सही श्रेणी तय करें, सबको एक ही मान पर न छोड़ें।
संदेश के मुख्य भाग की सीमा सेगमेंट में तय है, और Bird उसे छोटा नहीं करता। लंबा मुख्य भाग 422 के साथ अस्वीकार हो जाता है। गैर-GSM-7 अक्षर एक सेगमेंट की क्षमता को आधे से भी कम कर देते हैं। इसलिए अगर आपका मौजूदा प्रदाता घुमावदार उद्धरण चिह्नों और डैश को चुपचाप बदल देता था, तो पहले जैसी सेगमेंट संख्या बनाए रखने के लिए options.smart_encoding सेट करें। यह डिफ़ॉल्ट रूप से बंद रहता है, क्योंकि यह आपके लिखे मुख्य भाग को बदल देता है।
फ़िल्टर आयामों के लिए tags और संदर्भ के लिए metadata का उपयोग करें। टैग {name, value} जोड़े होते हैं, जिनसे आप एनालिटिक्स को फ़िल्टर और विभाजित कर सकते हैं। मेटाडेटा मनचाहा JSON होता है, जिसे Bird सहेजता है, रीड पर लौटाता है और हर वेबहुक इवेंट में वापस भेजता है। आपके पुराने प्रदाता का एकल क्लाइंट संदर्भ फ़ील्ड आमतौर पर metadata से मेल खाता है।
एकल संदेशों की शेड्यूलिंग और आउटबाउंड MMS के लिए अलग योजना चाहिए। scheduled_at, media_urls, validity_period और प्रति-प्राप्तकर्ता personalization आरक्षित फ़ील्ड हैं, जो 422 SMSUnsupportedFeature के साथ अस्वीकार होते हैं। आपके इंटीग्रेशन के ये हिस्से बाकी के साथ नहीं जाते: शेड्यूल किए गए संदेशों को अपनी कतार में रखें और तय समय पर भेजने वाला एंडपॉइंट कॉल करें। ऑडियंस कैंपेन के लिए Broadcasts का अलग से मूल्यांकन करें; ब्रॉडकास्ट केवल एंडपॉइंट फ़ील्ड का नया नाम नहीं है।
सीमित बार फिर से प्रयास करने के लिए Idempotency-Key का उपयोग करें। हर तार्किक संदेश के लिए एक अनोखी कुंजी भेजें, और तीन घंटे की रीप्ले अवधि में उसी अनुरोध के हर फिर से प्रयास में वही कुंजी दोबारा इस्तेमाल करें। रीप्ले डुप्लिकेट अनुरोध घटाते हैं, पर ठीक एक बार डिलीवरी की गारंटी नहीं देते। Idempotency देखें।

4. अपनी ऑप्ट-आउट सूची साथ लाएँ

पहला प्रोडक्शन संदेश भेजने से पहले अपने ऑप्ट-आउट इम्पोर्ट करें। जिसने आपके पुराने प्रदाता को संदेश बंद करने को कहा था, उसे संदेश भेजना वह अनुपालन विफलता है जो माइग्रेशन को बुरी तरह खत्म करती है। कैरियर या नियामक को इससे फ़र्क नहीं पड़ता कि रिकॉर्ड किस विक्रेता से खोया।

Bird का सप्रेशन एक प्रेषक और सब्सक्राइबर के जोड़े पर लागू होता है, जो आपके पुराने प्रदाता के सेवा, प्रोफ़ाइल या खाता स्तर के ब्लॉक से सीमित हो सकता है। व्यक्ति की वास्तविक सहमति वापसी को हर संबंधित प्रेषक और कार्यक्रम में बनाए रखें। हर जोड़ा POST /v1/sms/suppressions से जोड़ें:

कोड उदाहरण

while IFS=, read -r destination originator; do
  curl -s -X POST https://us1.platform.bird.com/v1/sms/suppressions \
    -H "Authorization: Bearer $BIRD_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"destination\": \"$destination\", \"originator\": \"$originator\"}"
done < opt-outs.csv

यही इम्पोर्ट CLI से bird sms suppressions add --destination +15550001234 --originator +15557654321 के रूप में भी चलाया जा सकता है।

इम्पोर्ट के बारे में दो बातें जानना ज़रूरी है:

सेंडर-विशिष्ट सप्रेशन के लिए दोनों छोर आवश्यक हैं। पूरे वर्कस्पेस पर लागू ऑप्ट-आउट अलग प्राथमिकता स्वामी के अधीन आता है। यह कॉल आइडेम्पोटेंट है: 201 एक नया सप्रेशन दर्ज करता है और 200 पहले से मौजूद मैन्युअल सप्रेशन लौटाता है, इसलिए अधूरे इम्पोर्ट को दोबारा चलाना सुरक्षित है।
इम्पोर्ट की गई जोड़ियों को reason: manual मिलता है, जो लेन-देन संबंधी श्रेणी सहित हर श्रेणी को रोकता है। यह उस सप्रेशन से ज़्यादा सख़्त है जिसे Bird स्टॉप कीवर्ड मिलने पर ख़ुद दर्ज करता है। अगर किसी सब्सक्राइबर ने केवल मार्केटिंग से ऑप्ट-आउट किया था, तो सोच-समझकर तय करें कि उस जोड़ी को इम्पोर्ट करना है या नहीं।

कोड हटाने से पहले मौजूदा कीवर्ड और प्राथमिकता व्यवहार की समीक्षा करें। जहाँ Bird की देश सूची लागू होती है, वहाँ यह समर्थित कीवर्ड का जवाब देता है और सप्रेशन दर्ज करता है। असमर्थित अनुरोधों, व्यापक प्राथमिकताओं और अन्य संपर्क चैनलों की हैंडलिंग बनाए रखें। कस्टम कैंपेन कीवर्ड और जवाबों के लिए कीवर्ड नियम का उपयोग होता है। कवरेज और दायरे के लिए ऑप्ट-आउट और कीवर्ड देखें।

5. डिलीवरी रिपोर्ट को वेबहुक पर ले जाएँ

POST /v1/webhooks के साथ एक एंडपॉइंट रजिस्टर करें और उसे इवेंट प्रकारों की एक स्पष्ट सूची के लिए सब्सक्राइब करें। ज़्यादातर प्रोवाइडर से आने पर यही संरचनात्मक बदलाव करना पड़ता है: हर मैसेज या हर नंबर के लिए कॉलबैक URL के बजाय आपके वर्कस्पेस में एंडपॉइंट होते हैं, और हर एंडपॉइंट उन्हीं इवेंट के लिए सब्सक्राइब करता है जो उसे चाहिए।

Bird के इवेंट नाम resource.action का पालन करते हैं। सफल क्रम पहले sms.accepted, फिर sms.sent, फिर sms.delivered है। बाकी स्थितियों को sms.undelivered, sms.failed, sms.expired और sms.rejected कवर करते हैं, और sms.received आपके नंबरों पर आए जवाब लाता है। आपके मौजूदा प्रोवाइडर की स्टेटस शब्दावली का अनुवाद आपकी प्रोवाइडर गाइड में है, और हर इवेंट का पेलोड SMS इवेंट में है।

सहसंबंध बिना बदलाव के पोर्ट हो जाता है। हर इवेंट में sms_id, workspace_id, to और from होते हैं, और भेजते समय दिए गए tags और metadata भी लौटते हैं। इसलिए आपका हैंडलर मैसेज खोजने के बजाय आपके अपने पहचानकर्ता सीधे इवेंट से पढ़ लेता है।

हैंडलर के साथ पोर्ट करने के लिए दो प्रक्रियाएँ:

डिलीवरी Standard Webhooks के अनुसार साइन की जाती हैं, जिसमें webhook-id, webhook-timestamp और webhook-signature हेडर और {id}.{timestamp}.{raw body} पर HMAC-SHA256 का उपयोग होता है। जो प्रोवाइडर अपनी योजना से साइन करते हैं, उनके लिए सत्यापन बदलना होगा; तरीका वेबहुक और इवेंट में है।
डिलीवरी कम से कम एक बार होती है और क्रम में नहीं होती। webhook-id के आधार पर डुप्लिकेट हटाएँ और पेलोड के timestamp के आधार पर क्रमबद्ध करें, पहुँचने के क्रम से कभी नहीं।

इनबाउंड संदेश भी इसी मॉडल पर चलते हैं। हर नंबर के लिए अलग इनबाउंड URL कॉन्फ़िगर करने के बजाय पूरे वर्कस्पेस के लिए एक बार sms.received की सदस्यता लें। ध्यान रखें कि जो जवाब किसी स्टॉप कीवर्ड से मेल खाता है, उसके लिए भी Bird सप्रेशन दर्ज करने के बाद sms.received भेजता है।

6. सिम्युलेटेड गंतव्यों पर परीक्षण करें

Bird कुछ परीक्षण गंतव्यों के लिए डिलीवरी के परिणाम कृत्रिम रूप से बनाता है। इससे आप बिना हैंडसेट के अपने पोर्ट किए गए भेजने के पथ और वेबहुक हैंडलर को असली API प्रतिक्रियाओं और असली हस्ताक्षरित डिलीवरी पर परख सकते हैं। ये वही नंबर हैं जिन्हें कई प्रदाता परीक्षण क्रेडेंशियल के लिए इस्तेमाल करते हैं, और इनमें से किसी पर भेजा गया संदेश कभी किसी कैरियर तक नहीं पहुँचता।

गंतव्य	आपके इंटीग्रेशन को क्या मिलता है
`+15005550001`	सबमिशन के समय `invalid_destination` के साथ अस्वीकार
`+15005550002`	`sms.sent`, फिर `unreachable` के साथ `sms.undelivered`
`+15005550003`	`sms.sent`, फिर `provider_unavailable` के साथ `sms.failed`
`+15005550004`	`sms.sent`, फिर `blocked_by_carrier` के साथ `sms.failed`
`+15005550006`	`sms.sent`, फिर `sms.delivered`
`+15005550009`	`sms.sent`, फिर `recipient_opted_out` के साथ `sms.failed`

तीन शर्तें लागू होती हैं, और नए वर्कस्पेस पर पहली दो शर्तों में लोग अक्सर चूक जाते हैं:

ये अमेरिकी नंबर हैं, इसलिए Destinations में संयुक्त राज्य अमेरिका सक्षम होना चाहिए, और from ऐसा सेंडर होना चाहिए जो अमेरिका के लिए मान्य हो। वहाँ अल्फ़ान्यूमेरिक सेंडर ID अस्वीकार कर दी जाती है।
सिम्युलेटेड भेजने का शुल्क लगता है, गंतव्य की सामान्य दर पर। कोई संदेश हैंडसेट तक नहीं पहुँचता, लेकिन वॉलेट से शुल्क वास्तव में कटता है, इसलिए अपने स्मोक टेस्ट का आकार उसी हिसाब से तय करें।
परिणाम केवल गंतव्य से तय होता है। कोई अलग टेस्ट क्रेडेंशियल नहीं है, और बंद करने के लिए कोई टेस्ट मोड भी नहीं है।

एक व्यावहारिक स्मोक टेस्ट +15005550006 पर भेजता है और जाँचता है कि आपका हैंडलर sms.accepted से sms.sent और फिर sms.delivered तक क्रम से जाता है; +15005550002 और +15005550009 पर भेजता है और जाँचता है कि आपकी विफलता और ऑप्ट-आउट हैंडलिंग सही error कोड पर चलती है; और आपके नियंत्रण वाले हैंडसेट पर एक वास्तविक संदेश भेजता है, ताकि पुष्टि हो सके कि सेंडर और संदेश का मुख्य भाग आपकी अपेक्षा के अनुसार दिखते हैं।

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

किसी विशेष प्रदाता से माइग्रेट करना

Twilio: फ़ॉर्म-एनकोडेड PascalCase से JSON तक, Messaging Services से सेंडर तक, StatusCallback से सब्सक्राइब किए गए वेबहुक तक
Plivo: src और dst से from और to तक, Powerpacks से सेंडर तक, DND जोड़ियों से सप्रेशन तक
Telnyx: Bird के सबसे क़रीब भेजने का अनुरोध, मैसेजिंग प्रोफ़ाइलों को सेंडर और सब्सक्रिप्शन में अलग करना, प्रोफ़ाइल-स्तर के ऑप्ट-आउट से जोड़ियों तक
Bandwidth: दो होस्ट से एक तक, applicationId कॉलबैक से वर्कस्पेस वेबहुक तक, और ऐसी ऑप्ट-आउट सूची जो आपके अपने एप्लिकेशन में पहले से है
Sinch: बैच से एकल भेजने तक, body से text तक, समूह सदस्यता को सप्रेशन के रूप में दोबारा बनाना
Infobip: तीन-स्तरीय पेलोड को समतल करना, प्रति-खाता बेस URL से क्षेत्रीय होस्ट तक, Blocklist को जोड़ियों में फैलाना
Bird Connectivity Platform: rest.messagebird.com API, originator और recipients से from और to तक, reportUrl GET कॉलबैक से हस्ताक्षरित वेबहुक तक

अगले कदम

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

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

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