ব্যবসার মালিক ও ডেভেলপারদের জন্য গাইড

সহজ ভাষায় SMS API

SMS API কী করে, কখন আপনার ব্যবসার এটি দরকার, এবং আপনার ডেভেলপার যে কয়েকটি মূল ধারণা নিয়ে কাজ করবেন। বিস্তারিত জানতে প্রস্তুত হলে ডেভেলপার ডকুমেন্টেশন দেখুন।

SMS API কী কাজে লাগে?

যখন একজন মানুষ নিজে মেসেজ পাঠান, তখন SMSGELY ড্যাশবোর্ডই সবচেয়ে সুবিধাজনক: যেমন কোনো দোকানমালিক সেলের ঘোষণা দিচ্ছেন, বা স্কুল অফিস অভিভাবকদের গ্রুপে নোটিস পাঠাচ্ছে। কিন্তু অনেক মেসেজ স্বয়ংক্রিয়ভাবে যাওয়া উচিত — ঠিক যে মুহূর্তে আপনার নিজের সিস্টেমে কিছু ঘটে। API (application programming interface) হলো সেই দরজা, যার মাধ্যমে আপনার ওয়েবসাইট, মোবাইল অ্যাপ, ERP বা বিলিং সফটওয়্যার কাউকে ড্যাশবোর্ড না খুলেই SMSGELY-কে SMS পাঠাতে বলতে পারে।

আপনার সফটওয়্যার একটি ছোট, নিরাপদ রিকোয়েস্ট পাঠায়, যার মানে “এই নম্বরে, এই Sender থেকে, এই লেখাটি পাঠাও”। SMSGELY সেটি যাচাই করে, সংরক্ষণ করে, আপনার ওয়ালেট থেকে খরচ রিজার্ভ করে এবং ড্যাশবোর্ড যে পাইপলাইন ব্যবহার করে সেই একই পাইপলাইনে পাঠায়। তাই API দিয়ে পাঠানো মেসেজও একই ডেলিভারি রিপোর্টে দেখা যায়।

সাধারণ ব্যবহার

ওয়ান-টাইম পাসওয়ার্ড (OTP)। সাইন-আপের সময় ফোন নম্বর যাচাই করুন, অথবা লগইন বা পেমেন্ট নিশ্চিত করুন।
অর্ডার আপডেট। অর্ডার গ্রহণ, পাঠানো, ডেলিভারি বা বাতিল হলে গ্রাহককে জানান। অনলাইন শপের মালিকেরা WooCommerce গাইড অনুসরণ করতে পারেন।
অ্যালার্ট ও রিমাইন্ডার। ক্লিনিকের অ্যাপয়েন্টমেন্ট রিমাইন্ডার, স্কুলের ফি রিমাইন্ডার, কিংবা আপনার নিজের টিমের জন্য স্টক কমে যাওয়া বা সার্ভার অ্যালার্ট।
ওয়েবসাইটের ফর্ম। কেউ কোনো জিজ্ঞাসা জমা দিলে SMS পান; দেখুন WordPress গাইড।
নিজের সিস্টেম থেকে বাল্ক SMS। বাল্ক endpoint দিয়ে প্রতি রিকোয়েস্টে সর্বোচ্চ ১,০০০ জন প্রাপককে ব্যক্তিগতকৃত মেসেজ পাঠান, চাইলে পরের কোনো সময়ের জন্য শিডিউলও করতে পারেন।

শুরু করার আগে যা লাগবে

একটি SMSGELY অ্যাকাউন্ট, যার ওয়ালেটে ব্যালান্স আছে। এখানে রেজিস্টার করুন; মূল্য দেখুন মূল্য পাতায়।
একটি API key। Dashboard → Developer → API keys থেকে একটি তৈরি করুন। সম্পূর্ণ key মাত্র একবার দেখানো হয়, তাই সঙ্গে সঙ্গে নিরাপদ কোথাও কপি করে রাখুন। SMSGELY শুধু এর hash করা সংস্করণ সংরক্ষণ করে।
একটি Sender ID। আপনার ব্র্যান্ড নামসহ অনুমোদিত মাস্কিং Sender ID, অথবা প্ল্যাটফর্মের নন-মাস্কিং Sender।

একটি রিকোয়েস্ট, একটি SMS

একটি মেসেজ পাঠাতে এটুকুই যথেষ্ট। নমুনা key ও Sender-এর জায়গায় আপনার নিজেরটি বসান; ডেভেলপাররা একই উদাহরণ JavaScript, PHP ও Python-এ পাবেন SMS পাঠানোর ডকুমেন্টেশনে।

curl https://<api-url-from-your-dashboard>/sms \
  -H "Authorization: Bearer smsgely_abcd1234ef_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-confirmed" \
  -d '{
    "to": "01712345678",
    "message": "Your order #1042 is confirmed. Thanks, ShopBD",
    "sender": "YOURBRAND",
    "client_reference": "order-1042"
  }'

cURL দিয়ে একটি SMS পাঠান (নমুনা API key)

রেসপন্স সঙ্গে সঙ্গে আসে — স্ট্যাটাস queued, parts-এর সংখ্যা এবং encoding (সাধারণ ইংরেজির জন্য gsm7, বাংলার জন্য unicode) সহ। উপরে দেখানো খরচটি কেবল উদাহরণ। এরপর মেসেজটি নিচে বর্ণিত স্ট্যাটাসগুলোর মধ্য দিয়ে এগোয়।

মূল ধারণাগুলো

অথেন্টিকেশন ও scope

প্রতিটি রিকোয়েস্টের Authorization: Bearer হেডারে আপনার key থাকে। প্রতিটি key-এর কিছু scope থাকে, যা ঠিক করে key দিয়ে কী করা যাবে: sms:send, sms:read, contacts:read, contacts:write এবং reports:read। যে ওয়েবসাইট শুধু মেসেজ পাঠায়, তার কেবল sms:send দরকার। চাইলে একটি key-কে আপনার সার্ভারের IP ঠিকানায় সীমাবদ্ধও করতে পারেন। বিস্তারিত পড়ুন অথেন্টিকেশন অংশে।

Idempotency: ভুল করে ডুপ্লিকেট নয়

নেটওয়ার্কে সমস্যা হয়, আর সফটওয়্যার আবার চেষ্টা করে। কোনো রিকোয়েস্টে Idempotency-Key হেডার থাকলে এবং ২৪ ঘণ্টার মধ্যে একই key ও একই body দিয়ে সেটি আবার এলে, SMSGELY দ্বিতীয় SMS না পাঠিয়ে প্রথমবারের ফলাফলই ফেরত দেয়। এভাবেই একই অর্ডারের জন্য গ্রাহককে দুবার মেসেজ পাঠানো এড়ানো যায়। বিস্তারিত আছে API রেফারেন্সে।

স্ট্যাটাস

একটি মেসেজ queued থেকে processing, submitted (প্রোভাইডার গ্রহণ করেছে এবং চার্জ হয়েছে), sent হয়ে আদর্শভাবে delivered-এ পৌঁছায়। এটি failed বা rejected (চার্জ হয় না), cancelled, অথবা প্রোভাইডারের উত্তর অস্পষ্ট হলে unknown অবস্থাতেও শেষ হতে পারে। দেখুন মেসেজ স্ট্যাটাস এবং SMS গাইডের সহজ ভাষার টেবিল।

Webhook

বারবার “ডেলিভারি হয়েছে কি?” জিজ্ঞেস করার বদলে, কোনো স্ট্যাটাস বদলালে বা কোনো ক্যাম্পেইন শেষ হলে আপনার সার্ভার একটি সাইন করা নোটিফিকেশন পেতে পারে। Dashboard → Developer → Webhooks থেকে সেটআপ করুন এবং সিগনেচার যাচাই করতে webhook গাইড অনুসরণ করুন।

এরর ও সীমা

সমস্যা হলে স্পষ্ট এরর কোড ফেরত আসে, যেমন ওয়ালেটে ব্যালান্স কম থাকলে INSUFFICIENT_BALANCE, বা মাস্কিং ID এখনো অনুমোদনের অপেক্ষায় থাকলে MASKING_NOT_APPROVED। প্রতিটি key-এর প্রতি মিনিটে রিকোয়েস্টের একটি সীমাও (rate limit) আছে। পূর্ণ তালিকা আছে এরর অংশে।

এরপর কোথায় যাবেন

ডেভেলপাররা এরপর ডেভেলপার ডকুমেন্টেশন দেখুন। ব্যবসার মালিকেরা এই পাতাটি তাঁদের ডেভেলপারকে পাঠাতে পারেন, আর key নিরাপদে রাখা হচ্ছে কি না নিশ্চিত করতে পড়তে পারেন SMS API নিরাপত্তা চেকলিস্ট (ইংরেজিতে)।

আপনার API key নিন

অ্যাকাউন্ট খুলুন, ওয়ালেট টপ-আপ করুন এবং কয়েক মিনিটেই ড্যাশবোর্ড থেকে সীমিত scope-এর একটি API key তৈরি করুন।

ফ্রি অ্যাকাউন্ট খুলুন ডকুমেন্টেশন পড়ুন