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 کی کسی بھی قدر کی پابندی کریں۔ اکاؤنٹ، ارسال کنندہ، ملک یا وصول کنندہ کے مسترد ہونے پر دوبارہ کوشش سے پہلے وجہ درست کریں۔ وقت کی حد ختم ہونے یا ارسال کا نتیجہ غیر واضح ہونے پر درخواست کا وقت، حوالہ اور واپس ملنے والی شناختیں محفوظ رکھیں، پورٹل کا جائزہ لیں اور دوبارہ بھیجنے سے پہلے معاونت سے رابطہ کریں۔ محض لاگ میں اندراج نہ ہونا اس بات کا ثبوت نہیں کہ کسی کیریئر نے درخواست قبول نہیں کی۔