অর্ডার সিস্টেম, ERP সিঙ্ক বা শপের অ্যাপ আপনিই বানিয়েছেন। এখন ব্যবসা চায়, অর্ডার শিপ হলেই কাস্টমার WhatsApp পাক। সরাসরি Meta-র Cloud API ধরলে টেমপ্লেট সামলানো, phone number ID, টোকেন আর উত্তরের জন্য একটা ইনবক্স, সব নিজেকে বানাতে হয়। প্রথম মেসেজের আগেই কয়েক সপ্তাহ চলে যায়।
SaleMag-এর REST API সেই স্তরটা তৈরি অবস্থায় দেয়। আপনার কোড একটা এন্ডপয়েন্ট কল করে, আর উত্তর আসে সেই ইনবক্সে, যেটা সাপোর্ট টিম আগে থেকেই ব্যবহার করে।
REST API হলো কিছু HTTPS এন্ডপয়েন্ট, যার মাধ্যমে আরেকটা প্রোগ্রাম JSON রিকোয়েস্ট পাঠিয়ে ডেটা পড়ে বা বদলায়। SaleMag-এর REST API আপনার সিস্টেমকে আপনার SaleMag ওয়ার্কস্পেসের কন্টাক্ট, ক্যাম্পেইন, WhatsApp নম্বর আর এআই এজেন্টের সাথে যুক্ত করে।
SaleMag REST API দিয়ে কী করা যায়?
SaleMag REST API দিয়ে কোড থেকে কন্টাক্ট, ক্যাম্পেইন, মেসেজ, কথোপকথন, এআই এজেন্ট, অটোমেশন, সোশ্যাল পোস্ট আর অ্যানালিটিক্স সামলানো যায়। সব এন্ডপয়েন্ট /api/v1-এর নিচে, উত্তর আসে JSON-এ:
| বিষয় | এন্ডপয়েন্ট | স্কোপ |
|---|---|---|
| অ্যাকাউন্ট | GET /me, ওয়ার্কস্পেস, প্ল্যানের ব্যবহার, সাবস্ক্রিপশন, নোটিফিকেশন, অডিট লগ, টোকেন |
লাগে না |
| কন্টাক্ট | লিস্ট, তৈরি, পড়া, আপডেট, ডিলিট | contacts:read, contacts:write |
| সেগমেন্ট | লিস্ট, তৈরি, সেগমেন্টের কন্টাক্ট | contacts:read, contacts:write |
| ক্যাম্পেইন | লিস্ট, তৈরি, পড়া, আপডেট, launch, pause, রিসিপিয়েন্ট | campaigns:read, campaigns:write |
| মেসেজ | POST /messages/send: WhatsApp (টেমপ্লেট বা টেক্সট) আর SMS |
messages:write |
| কথোপকথন | কথোপকথনের লিস্ট, কথোপকথনের মেসেজ | conversations:read |
| এআই এজেন্ট | এজেন্টের লিস্ট, এজেন্টের সাথে চ্যাট, নলেজ বেস আর ডকুমেন্ট | ai:read, ai:write |
| অটোমেশন | লিস্ট, কোনো কন্টাক্টের জন্য চালু | automations:write |
| সোশ্যাল | অ্যাকাউন্টের লিস্ট, পোস্ট পাবলিশ বা শিডিউল | social:write |
| অ্যানালিটিক্স | মেসেজ আর কথোপকথনের হিসাব, এআই ব্যবহার, ক্যাম্পেইন ফানেল | analytics:read |
| ওয়েবহুক | এন্ডপয়েন্টের লিস্ট, তৈরি, ডিলিট | webhooks:write |
কন্টাক্টের লিস্ট আসে কার্সর পেজিনেশনে, প্রতিবার ২৫টা: পরের ব্যাচের জন্য meta.next_cursor ধরুন।
SaleMag API-তে অথেনটিকেশন কীভাবে হয়?
SaleMag API-তে অথেনটিকেশন হয় পার্সোনাল অ্যাক্সেস টোকেনে, বেয়ারার হেডারে পাঠিয়ে; প্রতিটি টোকেন কাজ করে শুধু বাছাই করা স্কোপে। API Tokens পেজে টোকেন বানান:
Authorization: Bearer {token}
- পুরো টোকেন কপি করুন, শুরুর সংখ্যা আর
|সহ। এটা একবারই দেখায়, আর হ্যাশ করে রাখা হয়। - মেয়াদের তারিখ দিন, অথবা খোলা রাখুন।
- ১২টা স্কোপ থেকে বাছুন:
contacts:read,contacts:write,campaigns:read,campaigns:write,messages:write,conversations:read,webhooks:write,ai:read,ai:write,automations:write,social:writeআরanalytics:read। কোনোটা না বাছলে টোকেন পুরো অ্যাক্সেস (*) পায়। - মালিকের ওয়ার্কস্পেস রোলও খাটে, তাই টোকেন তার বানানো মানুষের চেয়ে বেশি কিছু করতে পারে না।
দরকারি স্কোপ ছাড়া কল করলে 403 আসে, সাথে required_scope ফিল্ডে কোন স্কোপ লাগবে তার নাম।
API দিয়ে WhatsApp মেসেজ পাঠাব কীভাবে?
API দিয়ে WhatsApp মেসেজ পাঠাতে messages:write স্কোপসহ কন্টাক্ট id দিয়ে POST /api/v1/messages/send কল করুন। কন্টাক্টটা SaleMag-এ E.164 ফোন নম্বরসহ থাকতে হবে, তাই আগে বানিয়ে নিন:
curl -X POST \
-H "Authorization: Bearer $SALEMAG_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"phone_e164":"+8801700000001","first_name":"Rahim","opt_in_whatsapp":true}' \
https://your-salemag-domain/api/v1/contacts
নতুন কন্টাক্ট data-র ভেতরে তার id-সহ ফেরত আসে। তারপর অনুমোদিত টেমপ্লেট পাঠান:
curl -X POST \
-H "Authorization: Bearer $SALEMAG_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"contact_id":42,"channel":"whatsapp","template_name":"order_confirmation","template_vars":{"1":"ORD-99"}}' \
https://your-salemag-domain/api/v1/messages/send
সফল হলে আসে {"provider_message_id": "wamid...", "status": "sent"}।
এর ওপর কিছু বানানোর আগে যা জানা দরকার:
| নিয়ম | বিস্তারিত |
|---|---|
| কোন নম্বর থেকে | আপনার ওয়ার্কস্পেসের প্রথম সক্রিয় WhatsApp Business API নম্বর |
| টেমপ্লেট না টেক্সট | টেমপ্লেটের জন্য template_name, সাধারণ টেক্সটের জন্য body |
| ২৪ ঘণ্টার উইন্ডো | এর বাইরে শুধু অনুমোদিত মেসেজ টেমপ্লেট পৌঁছায় |
| টেমপ্লেট ভেরিয়েবল | template_vars টেমপ্লেটের বডিতে বসে, ক্রম অনুযায়ী |
| টেমপ্লেটের ভাষা | টেমপ্লেটের en সংস্করণ যায় |
| SMS | channel-এ sms দিন; যায় আপনার ডিফল্ট SMS গেটওয়ে দিয়ে |
| ইমেইল | এই এন্ডপয়েন্টে এখনো নেই; 422 ফেরত দেয় |
কাস্টমারের উত্তর আসে ইউনিফায়েড ইনবক্সে। একসাথে অনেককে পাঠাতে API দিয়ে ক্যাম্পেইন বানিয়ে চালু করুন; দেখুন Broadcasting।
SaleMag API-র রেট লিমিট কত?
SaleMag API-তে পুরো /api/v1-এ প্রতি ইউজারে মিনিটে ৬০টা রিকোয়েস্ট চলে, মেসেজ পাঠানোয় আলাদা সীমাসহ:
| সীমা | মান |
|---|---|
সব /api/v1 রিকোয়েস্ট |
প্রতি ইউজারে মিনিটে ৬০টা |
POST /messages/send |
আরও আলাদা মিনিটে ৬০টা, প্রতি ইউজারে |
| সীমা পার হলে | HTTP 429, সাথে Retry-After, X-RateLimit-Limit আর X-RateLimit-Remaining |
অনেক মেসেজ পাঠাতে ক্যাম্পেইন ব্যবহার করুন। ক্যাম্পেইনের গতি SaleMag নিজেই সামলায়।
SaleMag API-র কি OpenAPI স্পেক বা SDK আছে?
OpenAPI স্পেক আছে, SDK নেই। /api/v1/openapi.json-এর OpenAPI 3.1 ডকুমেন্ট পাবলিক, তাই Postman, Insomnia বা কোড জেনারেটর টোকেন ছাড়াই পড়তে পারে। অ্যাপের ভেতরের API reference পেজে প্রতিটি এন্ডপয়েন্টের প্যারামিটার, উদাহরণ পেলোড আর আপনার নিজের base URL বসানো curl কমান্ড আছে।
এরর আসে JSON-এ: ব্যবসায়িক এররে error কি থাকে, আর ভ্যালিডেশন এররে 422-এর সাথে message আর errors অবজেক্ট।
SaleMag API কি ওয়েবহুক পাঠায়?
হ্যাঁ। কন্টাক্ট তৈরি হলে, মেসেজ এলে বা ক্যাম্পেইন শেষ হলে SaleMag আপনার সার্ভারে সাইন করা JSON ইভেন্ট POST করতে পারে। এন্ডপয়েন্ট যোগ করা যায় অ্যাপ থেকে, অথবা এই API-র /webhooks এন্ডপয়েন্ট দিয়ে। ইভেন্ট, সিগনেচার যাচাই আর রিট্রাইয়ের বিস্তারিত আছে ওয়েবহুক পেজে।
SaleMag API দিয়ে কী বানানো যায়?
SaleMag API দিয়ে কাস্টমার সিঙ্ক, অর্ডার আপডেট পাঠানো আর নিজের অ্যাপে এআই-এর উত্তর আনা যায়:
| কাজ | কীভাবে |
|---|---|
| ERP থেকে কাস্টমার সিঙ্ক | কাস্টম ফিল্ডসহ POST /contacts আর PATCH /contacts/{id} |
| অর্ডার আপডেট পাঠানো | WhatsApp Utility টেমপ্লেটসহ POST /messages/send |
| নিজের অ্যাপে এআই-এর উত্তর | POST /ai/agents/{id}/chat |
| এআই এজেন্টের তথ্য হালনাগাদ রাখা | POST /ai/knowledge-bases/{id}/documents |
| নিজের সিস্টেম থেকে ফ্লো চালু | POST /automations/{id}/trigger |
| BI টুলে হিসাব টানা | GET /analytics/messages আর GET /analytics/conversations |
SaleMag API কাদের জন্য?
SaleMag API সেই ডেভেলপার আর এজেন্সির জন্য, যারা SaleMag-কে অনলাইন স্টোর, ERP, CRM বা নিজের অ্যাপের সাথে যুক্ত করেন। কোড ছাড়া অটোমেশন চাইলে অটোমেশন ফ্লো বিল্ডারের HTTP রিকোয়েস্ট ধাপ আপনার URL কল করতে পারে।
প্রথম কল করতে প্রস্তুত? অ্যাকাউন্ট খুলুন আর API Tokens খুলুন, অথবা প্ল্যান মিলিয়ে দেখুন।
ধাপে ধাপে
- 1
টোকেন বানান
SaleMag-এ API Tokens খুলে টোকেনের নাম, স্কোপ আর মেয়াদ দিন, তারপর কপি করুন। এটা একবারই দেখায়।
- 2
টোকেন যাচাই করুন
বেয়ারার হেডারে টোকেন দিয়ে GET /api/v1/me কল করুন। টোকেনটা কার, সেই ইউজারের তথ্য ফেরত আসে।
- 3
কন্টাক্ট বানান
E.164 ফরম্যাটের ফোন নম্বর আর WhatsApp অপ্ট-ইনসহ POST /api/v1/contacts কল করুন।
- 4
মেসেজ পাঠান
কন্টাক্ট id, চ্যানেল আর টেমপ্লেটের নাম বা টেক্সটসহ POST /api/v1/messages/send কল করুন।
সাধারণ জিজ্ঞাসা
SaleMag API-তে অথেনটিকেশন কীভাবে হয়?
SaleMag-এর API Tokens পেজে পার্সোনাল অ্যাক্সেস টোকেন বানিয়ে Authorization: Bearer {token} হেডারে পাঠান। টোকেন হ্যাশ করে রাখা হয়, দেখায় একবারই, মেয়াদ দেওয়া যায়, আর কাজ করে শুধু বাছাই করা স্কোপে।
API দিয়ে কি WhatsApp মেসেজ পাঠানো যায়?
হ্যাঁ। messages:write স্কোপসহ POST /api/v1/messages/send দিয়ে কোনো কন্টাক্টকে WhatsApp টেমপ্লেট বা টেক্সট পাঠানো যায়। ২৪ ঘণ্টার উইন্ডোর বাইরে অনুমোদিত টেমপ্লেট লাগে।
SaleMag-এর কি OpenAPI বা Swagger স্পেক আছে?
হ্যাঁ। SaleMag-এর OpenAPI 3.1 ডকুমেন্ট /api/v1/openapi.json-এ পাবলিক, আর অ্যাপের ভেতরের API reference পেজে প্রতিটি এন্ডপয়েন্টের curl উদাহরণ আছে।
SaleMag API-র রেট লিমিট কত?
SaleMag API-তে প্রতি ইউজারে মিনিটে ৬০টা রিকোয়েস্ট চলে, আর মেসেজ পাঠানোয় আলাদা মিনিটে ৬০টার সীমা। 429 রেসপন্সে Retry-After আর X-RateLimit হেডার থাকে।
SaleMag API দিয়ে কি ইমেইল পাঠানো যায়?
না। মেসেজ এন্ডপয়েন্ট ইমেইল চ্যানেল নেয়, কিন্তু আপাতত 422 ফেরত দেয়। ইমেইল যায় ক্যাম্পেইন দিয়ে, যা API থেকেই বানানো আর চালু করা যায়।
SaleMag-এর কি SDK আছে?
না। SaleMag-এর অফিশিয়াল SDK নেই। API হলো HTTPS-এর ওপর সাধারণ JSON, আর OpenAPI ডকুমেন্ট থেকে ক্লায়েন্ট জেনারেট করা যায়।
SaleMag API-তে কি ওয়েবহুক আছে?
হ্যাঁ। কন্টাক্ট তৈরি হলে, মেসেজ এলে বা ক্যাম্পেইন শেষ হলে SaleMag সাইন করা ওয়েবহুক পাঠায়। ইভেন্ট আর সিগনেচারের বিস্তারিত দেখুন SaleMag ওয়েবহুক পেজে।
SaleMag API দিয়ে কি OTP কোড পাঠানো যায়?
না। SaleMag-এ OTP বানানো আর যাচাই করার কোনো এন্ডপয়েন্ট নেই। WhatsApp authentication টেমপ্লেট বানানো যায়, কিন্তু কোড বানানো আর যাচাই করতে হবে আপনার সিস্টেমকে।
লেখক পরিচিতি
হোয়াটসঅ্যাপ ও এফ-কমার্স অটোমেশন, ঢাকা
ঢাকার যে টিম সেলম্যাগ বানায়: বাংলাদেশের অনলাইন বিক্রেতাদের জন্য হোয়াটসঅ্যাপ, মেসেঞ্জার আর ইনস্টাগ্রামের এআই সেলস ইনবক্স।