डेवलपर्स

API रेफरेंस

भेजने के लिए एक एंडपॉइंट, स्टेटस पढ़ने के लिए एक, और रसीदों के लिए HMAC-साइन्ड वेबहुक। अकाउंट बनते ही कुंजियाँ जारी हो जाती हैं — न कुछ अप्रूव करना है, न किसी को ईमेल करना है।

v1https://api.worldsms.io/v1

शुरुआत करें

एक नए अकाउंट और डिलीवर हुए मैसेज के बीच तीन चीज़ें होती हैं: एक टोकन, कुछ क्रेडिट, और एक कुंजी। इनमें से किसी में भी कोई इंसान शामिल नहीं है।

अकाउंट बनाएं — आपका ब्राउज़र टोकन जनरेट करता है, और वही टोकन ही अकाउंट है।
इसमें राशि जमा करें। भुगतान पेज पर दिए किसी भी कॉइन में न्यूनतम $40।
डैशबोर्ड में एक API कुंजी बनाएं। यह एक बार दिखाई जाती है; हम केवल इसका हैश स्टोर करते हैं, बिल्कुल टोकन की तरह।

खाली बैलेंस पर कोई कुंजी भेज नहीं सकती

कुंजी बनाना जानबूझकर एक फ़ंडेड अकाउंट के पीछे गेट किया गया है। बिना इस्तेमाल पड़ा हुआ क्रेडेंशियल बिना किसी फ़ायदे की देनदारी है, इसलिए जब तक खर्च करने को कुछ न हो तब तक डैशबोर्ड कोई नई कुंजी नहीं बनाएगा।

प्रमाणीकरण

हर रिक्वेस्ट पर बियरर टोकन। कुंजी अकाउंट की पहचान करती है; कोई सेकंड फ़ैक्टर नहीं, रिक्वेस्ट पर कोई सिग्नेचर नहीं, और कोई IP allowlist नहीं — कुंजी ही पूरा क्रेडेंशियल है, इसलिए इसे वैसे ही समझें।

Authorization

Authorization: Bearer ws_live_9f2c…

ट्रांसपोर्ट	केवल HTTPS। सादे HTTP पर रिक्वेस्ट अस्वीकार की जाती है, रीडायरेक्ट नहीं की जाती — रीडायरेक्ट तब तक कुंजी को पहले ही लीक कर चुका होता।
स्कोप	एक कुंजी एक अकाउंट का बैलेंस खर्च करती है। हर भेजने वाले सिस्टम के लिए एक अलग कुंजी बनाएं, ताकि लीक होने पर सीमित दायरे में रिवोक किया जा सके।
निरस्तीकरण	तुरंत। रिवोक की गई कुंजी अगली रिक्वेस्ट पर `401` लौटाती है; पहले से स्वीकृत इन-फ़्लाइट बैच फिर भी पूरे होते हैं।
रिकवरी	कुछ नहीं। हम एक हैश रखते हैं। खोई हुई कुंजी बदली जाती है, कभी वापस नहीं मिलती।

संदेश भेजें

POST/v1/messages

एक कॉल, एक या कई प्राप्तकर्ता, मिश्रित गंतव्य। हर प्राप्तकर्ता की कीमत उसके अपने गंतव्य की दर पर तय होती है और प्रति सेगमेंट बिल की जाती है। कॉल को पूरी तरह स्वीकार या अस्वीकार किया जाता है; यह कभी आपसे आंशिक शुल्क नहीं लेती।

रिक्वेस्ट बॉडी

फ़ील्ड	प्रकार	नोट्स
`to`	string[]	आवश्यक। E.164, प्रति कॉल 5,000 तक। जो नंबर किसी कीमत वाले गंतव्य से मेल नहीं खाते, उन्हें बिलिंग से पहले अस्वीकार कर दिया जाता है।
`text`	string	आवश्यक। UTF-8। सेगमेंट गणना GSM 03.38 के अनुसार होती है — देखें सेगमेंट।
`from`	string	अल्फ़ान्यूमेरिक सेंडर ID, 11 अक्षरों तक। जहां रूट अनुमति देता है वहां ले जाया जाता है; देखें सेंडर ID।
`vars`	object[]	वैकल्पिक मर्ज वैल्यू, प्रति प्राप्तकर्ता एक ऑब्जेक्ट, जो सेगमेंट गिनने से पहले `{{name}}` प्लेसहोल्डर में डाली जाती हैं।
`callback_url`	string	अकाउंट वेबहुक का वैकल्पिक प्रति-बैच ओवरराइड।
`reference`	string	वैकल्पिक। हर रसीद पर वापस भेजा जाता है ताकि आप इसे अपने रिकॉर्ड से जोड़ सकें।

उदाहरण

send.sh

# one call, many recipients, mixed destinations
curl -X POST https://api.worldsms.io/v1/messages \
  -H "Authorization: Bearer $WORLDSMS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "ACME",
    "to":   ["+447700900123", "+33612345678"],
    "text": "Your code is 480913"
  }'

202 Accepted

{
  "batch_id": "b_7Kq2xR9wLm",
  "accepted": 2,
  "rejected": 0,
  "segments": 1,
  "cost_usd": 0.0353
}

यूनाइटेड किंगडम को $0.0137 और फ़्रांस को $0.0216 — रेट कार्ड प्रति गंतव्य लागू होता है, न कि औसत मिलाकर।

बैचिंग

बैच तुरंत स्वीकार किया जाता है और प्रति अकाउंट 200 मैसेज प्रति मिनट की दर से भेजा जाता है, इसलिए 50,000 प्राप्तकर्ताओं में लगभग 4 घंटे 10 मिनट लगते हैं। समय-संवेदनशील ट्रैफ़िक को मार्केटिंग भेजने के पीछे कतार में नहीं लगना चाहिए: इसके लिए अलग कुंजी का उपयोग करें।

मैसेज स्टेटस

GET/v1/messages/{batch_id}

पोलिंग समर्थित और रेट-लिमिटेड है; वेबहुक ही इच्छित रास्ता है। रिस्पॉन्स बैच को एक साथ जोड़ता है और प्रति-प्राप्तकर्ता स्थिति सूचीबद्ध करता है।

200 OK

{
  "batch_id":    "b_7Kq2xR9wLm",
  "status":      "done",
  "sending":     0,
  "delivered":   1,
  "undelivered": 1,
  "refund_usd":  0.0216
}

refund_usd एक बार निपटाया जाता है, जब बैच पूरा होता है। जब तक आप इसे पढ़ पाते हैं, यह पहले ही आपके बैलेंस में वापस आ चुका होता है।

बैलेंस

GET/v1/balance

बड़ा सेंड करने से पहले जांच लें। बैलेंस आंतरिक रूप से इंटीजर माइक्रो-डॉलर में रखे जाते हैं — दरें चार दशमलव तक जाती हैं, और लेजर में फ़्लोट का कोई काम नहीं — और यहाँ छह अंकों तक राउंड करके दिखाए जाते हैं।

200 OK

{ "balance_usd": 412.905400, "currency": "USD" }

डिलीवरी रसीदें

हर प्राप्तकर्ता के लिए एक रसीद तब जारी होती है जब कैरियर उसे रिपोर्ट करता है। ये चार ही स्थितियाँ हैं; कोई “unknown” बकेट नहीं है जिसका चुपचाप मतलब हो “हमने इसे खो दिया”।

स्टेट	अर्थ	बिल किया गया
`queued`	स्वीकृत, और बैच में अपनी बारी का इंतज़ार कर रहा है।	हाँ
`sent`	कैरियर को सौंप दिया गया, अभी पुष्टि नहीं हुई।	हाँ
`delivered`	हैंडसेट ने इसे स्वीकार किया।	हाँ
`undelivered`	बंद, प्रतिबंधित, या सेंडर को अस्वीकार कर दिया गया।	रिफंड किया गया

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

वेबहुक

डैशबोर्ड में या callback_url के साथ प्रति बैच एक एंडपॉइंट सेट करें। हम JSON POST करते हैं और 5 सेकंड के भीतर एक 2xx की उम्मीद रखते हैं। Non-2xx को एक्सपोनेंशियल बैकऑफ़ के साथ लगभग एक घंटे में छह बार रीट्राई किया जाता है, फिर ड्रॉप कर दिया जाता है।

पेलोड

अपने एंडपॉइंट पर POST करें

{
  "event":     "message.delivered",
  "batch_id":  "b_7Kq2xR9wLm",
  "to":        "+447700900123",
  "destination": "gb",
  "segments":  1,
  "cost_usd":  0.0137,
  "reference": "order-4471",
  "ts":        1785312041
}

हस्ताक्षर सत्यापित किया जा रहा है

हर डिलीवरी में X-WorldSMS-Signature और X-WorldSMS-Timestamp होता है। सिग्नेचर आपके वेबहुक सीक्रेट का उपयोग करके HMAC-SHA256(timestamp + "." + body) है। कॉन्स्टेंट टाइम में तुलना करें, और पाँच मिनट से पुराना टाइमस्टैम्प अस्वीकार करें ताकि पकड़ी गई डिलीवरी को बाद में आप पर रीप्ले न किया जा सके।

verify.php

// $secret is the webhook secret from the dashboard
$raw  = file_get_contents('php://input');
$ts   = $_SERVER['HTTP_X_WORLDSMS_TIMESTAMP'] ?? '';
$sig  = $_SERVER['HTTP_X_WORLDSMS_SIGNATURE'] ?? '';

// A stale timestamp is a replay, however well it is signed.
if (abs(time() - (int) $ts) > 300) { http_response_code(408); exit; }

$mine = hash_hmac('sha256', $ts . '.' . $raw, $secret);
if (!hash_equals($mine, $sig)) { http_response_code(401); exit; }

http_response_code(204);

Idempotent रहें

आपके एंडपॉइंट के टाइमआउट होने के बाद होने वाली रीट्राई, पहली डिलीवरी जैसी ही दिखती है। batch_id + to + event पर की बनाएं और दोहराव को नो-ऑप की तरह मानें।

एरर

हर विफलता एक स्थिर error स्लग वाला JSON बॉडी लौटाती है। स्लग पर मिलान करें, कभी टेक्स्ट पर नहीं — टेक्स्ट में सुधार होते रह सकते हैं।

HTTP	स्लग	क्या करें
400	`invalid_body`	गलत JSON या कोई ज़रूरी फ़ील्ड गायब।
401	`key_rejected`	गायब, रद्द या गलत टाइप की गई कुंजी। दोबारा कोशिश नहीं की जा सकती।
402	`insufficient_credit`	बैच की लागत बैलेंस से अधिक है। कुछ नहीं भेजा गया; टॉप-अप करें और फिर से सबमिट करें।
422	`no_valid_recipients`	हर नंबर किसी मूल्य-निर्धारित गंतव्य से मेल खाने में विफल रहा।
422	`sender_id_invalid`	`from` 11 अक्षरों से लंबा है या इसमें केवल अंकों वाली स्ट्रिंग है जिसे नंबर के रूप में पढ़ा जाएगा।
429	`rate_limited`	धीमा करें। `Retry-After` में सेकंडों की संख्या दी गई है।
503	`route_unavailable`	गंतव्य अस्थायी रूप से रूट करने योग्य नहीं है। दोबारा कोशिश की जा सकती है।

402 Payment Required

{
  "error":       "insufficient_credit",
  "message":     "Batch costs $84.20, balance is $12.05.",
  "required_usd": 84.20,
  "balance_usd":  12.05
}

सीमाएँ

रिक्वेस्ट	प्रति कुंजी प्रति मिनट 60, बर्स्ट 20। उसके बाद `Retry-After` के साथ `429`।
प्रति कॉल प्राप्तकर्ता	5,000। बड़ी सूचियों को कई कॉल में बांटें, या डैशबोर्ड में फ़ाइल अपलोड करें।
बॉडी साइज़	2 MB.
थ्रूपुट	कितनी भी कुंजियां सबमिट करें, प्रति अकाउंट प्रति मिनट 200 संदेश।
कुंजियाँ	कोई सीमा नहीं। प्रत्येक भेजने वाले सिस्टम के लिए एक कुंजी अभीष्ट तरीका है।

रेट लिमिट API कॉल पर लागू होती है, मैसेज पर नहीं: 5,000 प्राप्तकर्ताओं को ले जाने वाला एक कॉल लिमिट के विरुद्ध एक ही रिक्वेस्ट गिना जाता है।

कुंजियाँ तुरंत जारी की जाती हैं। कोई मंज़ूरी चरण नहीं है।

खाते में राशि जमा करें और डैशबोर्ड तुरंत एक बना देता है।

कुछ विशिष्ट पूछें