SMS ও সমর্থিত MMS পাঠান

পাঠানোর আগে

আপনার অ্যাকাউন্টের জন্য কনফিগার করা প্রেরক নম্বর ব্যবহার করে SMS বা সমর্থিত MMS পাঠান। এটি বাস্তব পরিবেশে কার্যকর হওয়া একটি অপারেশন, যা প্রাপকদের সঙ্গে যোগাযোগ করতে এবং চার্জ সৃষ্টি করতে পারে। শুধু অনুমোদিত প্রাপকদের কাছে অনুমোদিত ধরনের বার্তা পাঠান; নিচের উদাহরণের নম্বর ও রেফারেন্স কাল্পনিক।

আপনার অ্যাকাউন্টে বহির্মুখী বার্তা পাঠানোর অনুমোদন এবং প্রযোজ্য প্রেরক, দেশ ও বার্তার ধরনসংক্রান্ত অনুমতি থাকতে হবে। সরাসরি ব্যক্তিগত/ভোক্তা ব্যবহারকারীর পরিচয়প্রমাণ দিয়ে এই API ব্যবহার করা যায় না। অনুমোদিত নিবেদিত API পরিচয়প্রমাণের যোগ্যতা নির্ধারণের আলাদা প্রক্রিয়া রয়েছে; মোবাইল P2P প্রেরকদের অতিরিক্ত P2P এবং যুক্তরাষ্ট্র/কানাডার অনুমতির প্রয়োজন হতে পারে। API পরিচয়প্রমাণ থাকলেই যেকোনো ধরনের বার্তা পাঠানোর অনুমতি আছে ধরে না নিয়ে, MultiTEL-এর সঙ্গে আপনার অ্যাকাউন্টের সঠিক সেটআপ নিশ্চিত করুন।

পাঠানোর অনুরোধ

সক্রিয় API অ্যাকাউন্টের অনুমোদিত উৎস IP ঠিকানা থেকে HTTPS-এর মাধ্যমে পরিচয় যাচাই করুন। পরিচয়প্রমাণ সার্ভারের গোপন তথ্য সংরক্ষণাগারে রাখুন। ফর্ম-এনকোড করা ফিল্ডের সঙ্গে POST ব্যবহার করুন, অথবা কোনো ফর্ম বা কোয়েরি ফিল্ড দেওয়া না হলে JSON অবজেক্ট ব্যবহার করুন। URL-এ পরিচয়প্রমাণ বা বার্তার লেখা রাখবেন না।

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'from=12025550123' \
  --data-urlencode 'to=12025550124' \
  --data-urlencode 'text=Your requested update is ready.' \
  --data-urlencode 'reference=order-update-example' \
  https://api.multitel.net/v3/sendsms

JSON অ্যারের ক্ষেত্রে to-তে প্রকৃত অ্যারে ব্যবহার করুন; ফর্ম ফিল্ডের মধ্যে JSON অ্যারের স্ট্রিং রাখবেন না। প্রাথমিক ইন্টিগ্রেশন পরীক্ষায় একজন প্রাপককে বার্তা পাঠান। দলগত বার্তা ও MMS-এর সমর্থন রুটভেদে আলাদা, তাই ব্যবহারের আগে কোন সমন্বয় সমর্থিত তা নিশ্চিত করুন।

সম্পূর্ণ ফলাফল পড়ুন

শুধু উদাহরণ হিসেবে কয়েকটি নির্বাচিত ফিল্ড দেখানো হয়েছে; প্রদর্শিত খরচ কোনো মূল্যপ্রস্তাব নয়।

{
  "status": {
    "code": "200",
    "msg": ""
  },
  "response": {
    "sms_log_id_ori": 42,
    "to": "12025550124",
    "from": "12025550123",
    "status": "Success",
    "message": "Message queued",
    "causecode": 0,
    "uniqueid": "fixture-message",
    "cost": "$0.0120",
    "carrier_fee_usd": "0.0020000000",
    "chars": 31,
    "parts": 1,
    "encoding": "GSM-7",
    "permsg": "$0.0120",
    "pid": "fixture-reference"
  }
}

HTTP স্ট্যাটাস, JSON-এর status.code এবং প্রতিক্রিয়ার status/message একসঙ্গে পরীক্ষা করুন। ফলাফলের কোড স্ট্রিং হতে পারে। সহায়তা নেওয়ার সময় সংশ্লিষ্ট তথ্য মেলানোর জন্য sms_log_id_ori এবং ফেরত পাওয়া বার্তা/রেফারেন্সের মানগুলো সংরক্ষণ করুন। পুরোনো ব্যবস্থার uniqueid ও pid-এর মান রুটভেদে আলাদা হয়; এগুলোর ফরম্যাট অনুমান করবেন না বা এগুলো ক্লায়েন্টের আইডেমপোটেন্সি টোকেন বলে ধরে নেবেন না।

Success বা Message queued সাধারণত নির্বাচিত রুট অনুরোধ গ্রহণ করেছে বোঝায়, কোনো ব্যক্তির হ্যান্ডসেটে বার্তা পৌঁছেছে বোঝায় না। sent-এর মতো প্রাথমিক কলব্যাক স্ট্যাটাস একাই চূড়ান্ত ডেলিভারি নিশ্চিত করে না।

বার্তার খণ্ড ও চার্জ

পাঠানোর আগে সম্পূর্ণ চূড়ান্ত লেখার ওপর SMS-এর দৈর্ঘ্য বিশ্লেষণ ব্যবহার করুন। SMS-এর মূল্য গন্তব্য ও অ্যাকাউন্টের পরিষেবার ওপর নির্ভর করে; প্রতি খণ্ডে প্রযোজ্য ক্যারিয়ার ফি যোগ হয়। পাঠানোর প্রক্রিয়া প্রাপকদের জন্য নির্ধারিত মূল্য ও প্রযোজ্য ফি একত্র করে, তারপর গণনা করা SMS খণ্ডসংখ্যা দিয়ে গুণ করে। এই হিসাবের জন্য একটি MMS অনুরোধকে একটি বার্তা হিসেবে ধরা হয়।

পুরোনো প্রতিক্রিয়া কাঠামোতে cost ও permsg নির্দিষ্ট বিন্যাসে অর্থের পরিমাণ প্রকাশকারী স্ট্রিং। carrier_fee_usd ক্যারিয়ার ফির অংশটি USD-এ জানায় এবং এটি পাঠানোর গণনা করা মোট খরচের মধ্যে ইতিমধ্যেই অন্তর্ভুক্ত; এটি দ্বিতীয়বার যোগ করবেন না। আপনার অ্যাকাউন্টের প্রকৃত মূল্য ও রুটের প্রাপ্যতা অবশ্যই যাচাই করতে হবে। এই অনুরোধ শুধু মূল্য জানার অপারেশন নয়।

পর্যালোচিত কোড ক্যারিয়ারের মাধ্যমে সফলভাবে পাঠানোর ধাপের পরে অর্থ কেটে নেয়, তবে ক্যারিয়ারের গ্রহণ, স্থানীয়ভাবে তথ্য সংরক্ষণ ও বিলিং একই লেনদেনের অংশ নয়। উজানের পরিষেবা অনুরোধ গ্রহণ করার পরেও ত্রুটি বা টাইমআউট ঘটতে পারে। ক্লায়েন্টের জন্য কোনো আইডেমপোটেন্সি কী দেওয়া হয় না: একই রেফারেন্স আবার ব্যবহার করলে পুনরায় বার্তা পাঠানো ও চার্জ কাটা হতে পারে।

স্থানীয় ডেলিভারি ও মিশ্র ফলাফল

বাইরের ক্যারিয়ারের মাধ্যমে না পাঠিয়েও স্থানীয়ভাবে হোস্ট করা নম্বরগুলোতে পাঠানো বার্তা MultiTEL-এর অন্তর্মুখী বার্তাপ্রবাহে accepted হতে পারে। সব প্রাপক স্থানীয় এমন অনুরোধের প্রতিক্রিয়ায় accepted, message_id, provider ও delivery_status থাকতে পারে। স্থানীয়ভাবে গ্রহণ করা হয়েছে মানেই প্রাপকের কনফিগার করা ফরওয়ার্ডিং গন্তব্য কাজ করেছে এমন নিশ্চয়তা নেই।

local_delivery_results ও partial থাকলে পরীক্ষা করুন। ফরওয়ার্ডিংয়ের ফলাফল অসফল হলেও কোনো প্রাপকের ক্ষেত্রে accepted true দেখাতে পারে। একটি মিশ্র অনুরোধে ক্যারিয়ারের প্রাপকদের ক্ষেত্রে accepted দেখাতে পারে, অথচ স্থানীয় অংশ ব্যর্থ হতে পারে। স্বয়ংক্রিয়ভাবে পুরো ব্যাচ আবার পাঠাবেন না: আগে প্রতিটি প্রাপকের ফলাফল মিলিয়ে নিশ্চিত করুন।

সব প্রাপক স্থানীয় এবং অনুরোধ গৃহীত হলে এই প্রক্রিয়ায় বহির্মুখী খরচ শূন্য দেখানো হয়, তবে প্রাপকদের স্বাভাবিক অন্তর্মুখী বার্তার চার্জ তখনও লাগতে পারে। বহির্মুখী খরচ শূন্য মানেই কোনো অ্যাকাউন্টে চার্জ লাগবে না, এমন নিশ্চয়তা ধরে নেবেন না।

কলব্যাক ও সংশ্লিষ্ট তথ্য মেলানো

notifyurl দেওয়া হলে প্রাথমিক কলব্যাকে একটি status আবরণ এবং প্রতিক্রিয়ার ফিল্ডগুলো থাকে, যার মধ্যে রয়েছে message_id, reference, from, to, status, status_text, error_code, timestamp ও accepted। স্থানীয় ফলাফলও থাকতে পারে। API পরিচয়প্রমাণ বা বার্তার অপ্রয়োজনীয় বিষয়বস্তু লগে না লিখে সংশ্লিষ্ট তথ্য মেলানোর উপাত্ত সংরক্ষণ করুন।

এই হ্যান্ডলার ওই প্রাথমিক কলব্যাকে স্বাক্ষরসংক্রান্ত কোনো ফিল্ড যোগ করে না। যাচাই না করা কলব্যাককে অন্য কোনো কাজের একমাত্র অনুমোদন হিসেবে ব্যবহার করবেন না। আপনার অ্যাকাউন্টের জন্য সমর্থিত ইন্টিগ্রেশন/ওয়েবহুক সেটআপের নির্দেশনা দেখুন এবং পোর্টালের রেকর্ড বা সহায়তা বিভাগের সঙ্গে মিলিয়ে অনিশ্চিত ফলাফল নিশ্চিত করুন। কলব্যাক একবারই আসবে বা চূড়ান্ত ডেলিভারির ক্রমে আসবে বলে ধরে নেবেন না।

ব্যর্থতা ও নিরাপদ পুনরুদ্ধার

যাচাইকরণ ব্যর্থ হলে API কোড 403 ব্যবহার করা হতে পারে। অ্যাকাউন্টের অনুমোদন, P2P ও দেশের নীতির কারণে প্রত্যাখ্যানেও HTTP 403 সেট করা হতে পারে এবং মেশিনে পাঠযোগ্য response.code অন্তর্ভুক্ত থাকতে পারে। অনুরোধের হারসীমার ক্ষেত্রে পুনরায় চেষ্টার তথ্যসহ 429 ব্যবহার করা হতে পারে। নীতি অনুপলব্ধ হলে অথবা পাঠানো/স্থানীয়ভাবে তথ্য সংরক্ষণ ব্যর্থ হলে 503 বা 500 ব্যবহার করা হতে পারে; পুরোনো ব্যবস্থায় অপর্যাপ্ত ব্যালান্সের ক্ষেত্রেও 500 ফেরত আসতে পারে।

429-এর ক্ষেত্রে Retry-After এবং response.retry_after-এর কোনো মান থাকলে তা মেনে চলুন। অ্যাকাউন্ট, প্রেরক, দেশ বা প্রাপকসংক্রান্ত প্রত্যাখ্যান হলে আবার চেষ্টা করার আগে কারণটি সংশোধন করুন। টাইমআউট হলে বা পাঠানোর ফলাফল অস্পষ্ট হলে অনুরোধের সময়, রেফারেন্স ও ফেরত পাওয়া শনাক্তকারী সংরক্ষণ করুন, পোর্টাল পরীক্ষা করুন এবং পুনরায় পাঠানোর আগে সহায়তা বিভাগের সঙ্গে যোগাযোগ করুন। শুধু লগ এন্ট্রি না থাকাই কোনো ক্যারিয়ার অনুরোধটি গ্রহণ করেনি তার প্রমাণ নয়।