आपके अपने नंबरों पर सत्यापन कोड के लिए SMS gateway API

ऑथेंटिकेशन

डैशबोर्ड में REST API के तहत कुंजी बनाएँ। यह bsk_live_ से शुरू होती है और सिर्फ़ एक बार दिखती है, इसलिए इसे सीक्रेट की तरह रखें, जैसे BUSYSMS_API_KEY में। हर अनुरोध में इसे इनमें से किसी एक हेडर में भेजें:

Authorization: Bearer bsk_live_xxxxxxxx
# or
X-API-Key: bsk_live_xxxxxxxx

कुंजी एक व्यक्ति की होती है और सिर्फ़ उसी के फ़ोन देखती है, साथ में वे नंबर जो उसके साथ साझा किए गए हैं। डैशबोर्ड में बनी कुंजी कोड पढ़ सकती है, आपके फ़ोन और नंबरों की सूची देख सकती है, आपके खाते की स्थिति पढ़ सकती है और रुके हुए फ़ोन को जगा सकती है; वह कोई डिवाइस हटा नहीं सकती और न आपका खाता संभाल सकती है, इसलिए लीक हुई कुंजी आपका बिल नहीं बदल सकती। फिर भी कुंजियाँ सर्वर पर ही रखें: जिसके पास कुंजी है, वह आपके कोड पढ़ सकता है।

एंडपॉइंट

बेस URL https://busysms.net/api/v1 है। अनुरोध सामान्य GET होते हैं और जवाब JSON में आते हैं।

• GET /codes: आपके सभी नंबरों में सबसे नया कोड। timeoutMs के साथ यह अगले कोड का 90 सेकंड तक इंतज़ार करता है। फ़िल्टर: service, phone, deviceId।
• GET /devices: आपके गेटवे फ़ोन, उनकी id, नाम, नंबर, प्लेटफ़ॉर्म और ऑनलाइन, सत्यापित व रुकी हुई स्थिति के साथ, और आपके साथ साझा किए गए नंबर।
• GET /numbers: सिर्फ़ आपके नंबर, हर एक के साथ canReceive और, जब वह कोड नहीं पा सकता, एक reason: unverified, verification_pending, inactive, gateway_off या phone_unreachable।
• GET /devices/:id/messages: किसी एक फ़ोन के हाल में कैप्चर हुए मैसेज, सबसे नए पहले। service, limit (डिफ़ॉल्ट 50, अधिकतम 200) और since लेता है।
• GET /account: आपका खाता, उसके ट्रायल और सदस्यता की स्थिति के साथ।

कोड का इंतज़ार करें: curl, Node.js और Python

ज़्यादातर इंटीग्रेशन को जिस कॉल की ज़रूरत होती है, वह है SMS भिजवाने वाली किसी कार्रवाई के ठीक बाद लॉन्ग-पोल। इंतज़ार शुरू करें, साइन-इन ट्रिगर करें, और जैसे ही मेल खाता कोड आता है, अनुरोध लौट आता है।

curl -s -H "Authorization: Bearer $BUSYSMS_API_KEY" \
  "https://busysms.net/api/v1/codes?service=exampleapp&timeoutMs=60000"

const params = new URLSearchParams({ service: "exampleapp", timeoutMs: "60000" });
const res = await fetch(`https://busysms.net/api/v1/codes?${params}`, {
  headers: { Authorization: `Bearer ${process.env.BUSYSMS_API_KEY}` },
});

if (res.status === 402) throw new Error("Trial over or subscription inactive");
if (!res.ok) throw new Error(`BusySMS ${res.status}: ${await res.text()}`);

const { code, message } = await res.json();
if (code) console.log(`${code} from ${message.sender}`);
else console.log("No new code within 60 seconds");

import os
import requests

r = requests.get(
    "https://busysms.net/api/v1/codes",
    params={"service": "exampleapp", "timeoutMs": 60000},
    headers={"Authorization": f"Bearer {os.environ['BUSYSMS_API_KEY']}"},
    timeout=75,
)
if r.status_code == 402:
    raise RuntimeError("Trial over or subscription inactive")
r.raise_for_status()

data = r.json()
if data["code"]:
    print(data["code"], "from", data["message"]["sender"])
else:
    print("No new code within 60 seconds")

क्रम उतना मायने नहीं रखता जितना आपको डर हो सकता है: अनुरोध शुरू होने से लगभग एक सेकंड पहले तक आया कोड भी नया गिना जाता है, उससे पुराना नहीं। टेस्ट में पहले अनुरोध शुरू करें और फिर SMS ट्रिगर करें; OTP ऑटोमेशन गाइड दिखाती है कि Playwright, Selenium और Cypress में यह कैसे करें।

जवाब में क्या आता है

हर /codes जवाब का ढाँचा एक जैसा होता है (यहाँ message ऑब्जेक्ट छोटा करके दिखाया गया है):

{
  "code": "482913",
  "message": {
    "otpCode": "482913",
    "phone": "+447700900123",
    "sender": "ExampleApp",
    "service": "exampleapp",
    "serviceLabel": "ExampleApp",
    "bodyPreview": "Your ExampleApp verification code is 482913",
    "receivedAt": 1792674000000,
    "deviceName": "Test phone"
  }
}

जब समय रहते कुछ नया नहीं आता तो code null होता है: इंतज़ार के दौरान API कभी पुराने कोड पर नहीं लौटता। receivedAt epoch मिलीसेकंड में होता है। service एक छोटी id है जो BusySMS हर मैसेज को देता है: कोई जाना-पहचाना ब्रांड, जैसे google, telegram या microsoft, नहीं तो भेजने वाले के नाम का slug। सिर्फ़ उसी भेजने वाले के कोड का इंतज़ार करने के लिए इसे service= के रूप में भेजें।

एरर और उन्हें कैसे संभालें

• 401: कुंजी नहीं है, गलत फ़ॉर्मैट में है या रद्द कर दी गई है। रद्द कुंजी पर जवाब में key_revoked आता है।
• 402 payment_required: ट्रायल खत्म हो गया है और कोई सक्रिय सदस्यता नहीं है। कोड पढ़ना रुक जाता है, लेकिन /devices जवाब देता रहता है ताकि आप देख सकें कि क्या गड़बड़ है, और जवाब में billingUrl होता है।
• 403: डिवाइस किसी और खाते का है, या कुंजी के पास इस रूट का स्कोप नहीं है (insufficient_scope)।
• 404: ऐसा कोई डिवाइस नहीं।
• 409 number_unverified: उस फ़ोन का नंबर अभी सत्यापित नहीं हुआ है, इसलिए उसके मैसेज पढ़े नहीं जा सकते।
• 429: रेट लिमिट लगी है। दोबारा कोशिश करने से पहले retryAfterMs तक रुकें।

सीमाएँ और अच्छे तरीके

• एक इंतज़ार ज़्यादा से ज़्यादा 90 सेकंड चलता है। अगर कोड आने में ज़्यादा समय लग सकता है, तो एक अनुरोध खुला रखने के बजाय नए टाइमआउट के साथ फिर से कॉल करें।
• कई नंबर हों तो फ़िल्टर करें: पाने वाले नंबर के साथ phone=, या अपने किसी एक फ़ोन के लिए deviceId=, ताकि किसी दूसरे साइन-इन के लिए आया कोड न लौटे।
• अगर इंतज़ार शुरू होते समय आपका कोई भी फ़ोन कैप्चर नहीं कर रहा, तो BusySMS फ़ोन पर नोटिफ़िकेशन भेजकर गेटवे फिर से चालू करने को कहता है। यह कभी रिमोट से कैप्चर चालू नहीं करता; किसी इंसान को टैप करना होता है।
• कैप्चर हुए मैसेज 7 दिन तक रखे जाते हैं, फिर मिटा दिए जाते हैं।
• कोड पढ़ने के लिए सक्रिय ट्रायल या सदस्यता चाहिए: 7 दिन के मुफ़्त ट्रायल के बाद $5 प्रति सत्यापित नंबर प्रति माह। प्रति अनुरोध कोई शुल्क नहीं।

REST API से आगे

यही कोड AI एजेंट को BusySMS MCP सर्वर से मिलते हैं (देखें AI एजेंट के लिए SMS कोड), और लोगों को Chrome एक्सटेंशन से, जो वेबसाइट में कोड आपके लिए भर देता है।

आपके साथ साझा किए गए नंबर भी शामिल हैं। जब कोई साथी किसी नंबर के कोड साझा करता है, तो /codes उन्हें आपके अपने कोड के साथ लौटाता है, और phone= से आप सिर्फ़ उस नंबर को चुन सकते हैं।

सवाल-जवाब

अक्सर पूछे जाने वाले सवाल