میسجنگ مہم کو ایک نمبر تفویض کریں

مہم کو بھیجنے والا نمبر تفویض کریں

یہ آپریشن اس وقت استعمال کریں جب آپ کا میسجنگ برانڈ اور پروڈکشن مہم رجسٹرڈ ہو چکے ہوں اور مہم فعال ہو۔ یہ آپ کے اکاؤنٹ کے ایک SMS فعال نمبر کو مہم سے منسلک کرتا ہے۔ یہ نہ برانڈ بناتا ہے، نہ مہم بناتا یا منظور کرتا ہے، نہ نمبر خریدتا ہے، اور نہ ہی کوئی پیغام بھیجتا ہے۔

موجودہ پورٹل کسی نمبر کو مہم تفویض کرتے وقت یہی روٹ استعمال کرتا ہے۔ پبلک API مہم کا شناخت کنندہ قبول کرتا ہے؛ یہ الگ برانڈ شناخت کنندہ قبول کرنے کے بجائے اکاؤنٹ کی ملکیت والی مہم سے برانڈ اخذ کرتا ہے۔

درخواست

اپنے فعال API اکاؤنٹ اور اس کے اجازت یافتہ سورس IP ایڈریس کا استعمال کرتے ہوئے HTTPS پر فارم انکوڈڈ POST بھیجیں۔ اپنے اکاؤنٹ کے اصل نمبر اور مہم کے شناخت کنندے استعمال کریں۔ اس مثال میں دیا گیا نمبر فرضی ہے۔

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'action=add' \
  --data-urlencode "campaign=$CAMPAIGN_ID" \
  --data-urlencode 'number=12025550123' \
  'https://api.multitel.net/v3/campaign'

مہم کی تفویض کاری کے پیرامیٹرز
پیرامیٹر	درکار	مطلب
action	ہاں	نمبر کی موجودہ مہم وابستگی تفویض کرنے کے لیے add اور ہٹانے کے لیے delete استعمال کریں۔ حروف کی کیس اور اردگرد کی خالی جگہیں نارملائز کی جاتی ہیں۔
campaign	add کے لیے	تصدیق شدہ اکاؤنٹ کی ملکیت والی ACTIVE مہم کی campaignId۔ اس کا برانڈ بھی اسی اکاؤنٹ سے تعلق رکھتا ہونا چاہیے۔ واضح طور پر sandbox کے طور پر نشان زد مہم کو لائیو بھیجنے والے نمبروں کو تفویض نہیں کیا جا سکتا۔ delete کے لیے یہ پیرامیٹر چھوڑ دیں؛ ہٹانے کے لیے نمبر کی موجودہ وابستگی استعمال ہوتی ہے۔
number	ہاں	آپ کی ملکیت کا، فعال، غیر منسوخ، SMS فعال بھیجنے والا نمبر۔ شمالی امریکی نمبر کے لیے ملکی کوڈ 1 اور اس کے بعد اس کے دس ہندسے استعمال کریں، بغیر جمع کے نشان کے۔ ہینڈلر غیر ہندسی حروف ہٹا دیتا ہے اور جمع کے نشان والے اور دس ہندسوں والے مساوی نمبر بھی تلاش کرتا ہے۔ یہ نارملائزیشن فون نمبر کی عمومی درستی کی جانچ نہیں ہے۔

یہ آپریشن ایک نمبر تبدیل کرتا ہے۔ اس میں کوئی پیجینیشن، بیچ پیرامیٹر یا ڈرائی رن آپشن نہیں ہے۔ کسی موجودہ مہم سے محض نمبر منسلک کرنے کے لیے مہم بنانے والا اینڈ پوائنٹ استعمال نہ کریں۔

موجودہ وابستگی ہٹائیں

اپنی ملکیت کے نمبر کے ساتھ action=delete استعمال کریں۔ یہ اس کی بھیجنے والی مہم کی وابستگی ہٹا دیتا ہے اور اس نمبر کے محفوظ شدہ برانڈ/مہم فیلڈز صاف کر دیتا ہے۔ یہ نہ مہم یا برانڈ حذف کرتا ہے، نہ فون نمبر چھوڑتا ہے، نہ نمبر کی سروس منسوخ کرتا ہے، اور نہ ہی مہم کی بار بار ہونے والی بلنگ روکتا ہے۔

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'action=delete' \
  --data-urlencode 'number=12025550123' \
  'https://api.multitel.net/v3/campaign'

جواب اور تصدیق

یہ فرضی مثال API کے عام جوابی لفافے اور منتخب نتیجہ فیلڈز کی وضاحت کرتی ہے۔ واپس کیا گیا نمبر آپ کے اکاؤنٹ میں محفوظ شدہ فارمیٹ برقرار رکھتا ہے۔ کامیاب ہٹانے کے بعد brandId اور campaignId خالی سٹرنگز ہوتے ہیں۔

{
  "status": {"code": 200, "msg": "Campaign assignment updated."},
  "response": {
    "number": "+12025550123",
    "brandId": "BRAND_FROM_ACCOUNT",
    "campaignId": "CAMPAIGN_FROM_ACCOUNT",
    "providerStatus": 200
  }
}

providerStatus میسجنگ پارٹنر کا HTTP اسٹیٹس ہے۔ ہینڈلر 2xx ٹرانسپورٹ جواب قبول کرتا ہے اور پھر مقامی نمبر ریکارڈ اپ ڈیٹ کرتا ہے؛ یہ الگ کاروباری سطح کے قبولیت نتیجے کے لیے پارٹنر کے جوابی باڈی کی تشریح نہیں کرتا۔ لہٰذا کامیابی کا جواب اس بات کا ثبوت نہیں ہے کہ میسجنگ رجسٹریشن مکمل ہو گئی ہے یا ترسیل کامیاب ہوگی۔ پروڈکشن ٹریفک بھیجنے سے پہلے پورٹل میں نمبر کی مہم کی حیثیت کا جائزہ لیں۔

محض مقامی وابستگی کو ترسیل کی منظوری نہ سمجھیں۔ مہم اور برانڈ کی منظوری، نمبر کی فراہمی، اکاؤنٹ کی اجازتیں، مواد کے قواعد اور عام میسجنگ حدود بدستور لاگو رہتی ہیں۔

خرابیاں اور جزوی نتائج

401: ہینڈلر کے لیے کوئی تصدیق شدہ اکاؤنٹ دستیاب نہیں ہے۔
400: action یا number غائب/غلط ہے، یا add درخواست میں مہم کا شناخت کنندہ موجود نہیں ہے۔
404: نمبر آپ کی ملکیت کا، فعال، غیر منسوخ SMS نمبر نہیں ہے۔
409: مہم اکاؤنٹ کے لیے دستیاب نہیں ہے، ACTIVE نہیں ہے، واضح طور پر sandbox ہے، یا اس کا برانڈ اکاؤنٹ کے لیے دستیاب نہیں ہے۔
503: میسجنگ انٹیگریشن دستیاب نہیں ہے۔ اکاؤنٹ کی اسناد تبدیل کرنے یا کنفیگریشن کی قدریں گھڑنے کے بجائے سپورٹ سے رابطہ کریں۔
502: میسجنگ درخواست ناکام ہو گئی، اس کا وقت ختم ہو گیا یا اس نے غیر 2xx HTTP اسٹیٹس واپس کیا۔ providerStatus واپس کیا جا سکتا ہے۔ ٹائم آؤٹ اس بات کا ثبوت نہیں ہے کہ پارٹنر نے کوئی تبدیلی نہیں کی۔
500 مع partial=true: میسجنگ پارٹنر نے کامیاب HTTP اسٹیٹس واپس کیا، لیکن مقامی وابستگی کی تصدیق نہیں ہو سکی۔ دوبارہ کوشش کرنے سے پہلے پورٹل میں نمبر کی اصل حالت چیک کریں اور کسی بھی عدم مطابقت کو دور کریں یا سپورٹ سے رابطہ کریں۔

HTTP نتیجے کے ساتھ ساتھ API اسٹیٹس کوڈ اور جوابی باڈی بھی چیک کریں۔ ٹائم آؤٹ یا جزوی نتیجے پر آنکھ بند کر کے دوبارہ کوشش نہ کریں۔ اس ہینڈلر میں درخواست کی سطح کی آئیڈمپوٹنسی کلید، ٹرانزیکشنل رول بیک یا مہم رجسٹریشن کی تکمیل کی جانچ نہیں ہے۔ دہرائی گئی ایک جیسی مقامی تفویض اس وقت بھی کامیابی واپس کر سکتی ہے جب ڈیٹا بیس کوئی تبدیل شدہ قطار رپورٹ نہ کرے۔

دائرہ کار اور اثرات

یہ آپریشن بھیجنے والے نمبر کی روٹنگ اور اس کی محفوظ شدہ مہم/برانڈ وابستگی تبدیل کرتا ہے۔ جائزہ شدہ ہینڈلر میں اس میں اکاؤنٹ سے براہِ راست کٹوتی، مہم کی تخلیق، خریداری یا پیغام کی ترسیل شامل نہیں ہے۔ یہ نہ قیمت کا تخمینہ ہے اور نہ مفت سروس کا وعدہ: موجودہ نمبر، مہم اور میسجنگ کے چارجز آپ کے اکاؤنٹ کی شرائط کے تحت جاری رہتے ہیں۔

پورٹل میں کسی مختلف مہم پر منتقل ہونے کے لیے پہلے پچھلی وابستگی ہٹائی جاتی ہے اور پھر نئی شامل کی جاتی ہے۔ یہ الگ الگ درخواستیں ہیں۔ اگر دوسری درخواست ناکام ہو جائے تو پچھلی وابستگی پہلے ہی ہٹائی جا چکی ہو سکتی ہے۔ یہ نہ سمجھیں کہ دونوں درخواستیں ایک ساتھ رول بیک ہو جاتی ہیں۔