تعيين رقم لحملة مراسلة

تعيين رقم إرسال لحملة

استخدم هذه العملية بعد تسجيل علامة المراسلة التجارية وحملة الإنتاج الخاصتين بك وعندما تكون الحملة نشطة. تربط هذه العملية رقمًا واحدًا مفعّلًا لخدمة SMS في حسابك بالحملة. وهي لا تنشئ علامة تجارية، ولا تنشئ حملة أو تعتمدها، ولا تشتري رقمًا، ولا ترسل رسالة.

تستخدم البوابة الحالية هذا المسار عند تعيين حملة لرقم. تقبل واجهة API العامة معرّف الحملة؛ وتشتق العلامة التجارية من الحملة المملوكة للحساب بدلًا من قبول معرّف علامة تجارية منفصل.

الطلب

أرسل طلب POST مرمّزًا كنموذج عبر HTTPS باستخدام حساب API المفعّل الخاص بك وعنوان IP المصدر المسموح به له. استخدم معرّفات الرقم والحملة الفعلية من حسابك. الرقم الوارد في هذا المثال خيالي.

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=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: فشل طلب المراسلة أو انتهت مهلته أو أعاد حالة HTTP غير 2xx. قد يتم إرجاع providerStatus. انتهاء المهلة لا يثبت أن الشريك لم يُجرِ أي تغيير.
• 500 مع partial=true: أعاد شريك المراسلة حالة HTTP ناجحة، لكن تعذر تأكيد الارتباط المحلي. تحقق من حالة الرقم في البوابة وعالج أي اختلافات أو تواصل مع الدعم قبل إعادة المحاولة.

تحقق من رمز حالة API ونص الاستجابة بالإضافة إلى نتيجة HTTP. لا تعد المحاولة بشكل أعمى بعد انتهاء المهلة أو نتيجة جزئية. لا يملك هذا المعالج مفتاح منع التكرار على مستوى الطلب، ولا تراجعًا عن المعاملات، ولا فحصًا لاكتمال تسجيل الحملة. قد يعيد تعيين محلي مكرر ومطابق نجاحًا حتى عندما لا تبلّغ قاعدة البيانات عن أي صفوف متغيرة.

النطاق والآثار

تغيّر هذه العملية توجيه رقم الإرسال وارتباطه المحفوظ بالحملة/العلامة التجارية. وهي لا تتضمن في المعالج الذي تمت مراجعته أي خصم مباشر من الحساب أو إنشاء حملة أو شراء أو إرسال رسالة. هذا ليس عرض سعر ولا وعدًا بخدمة مجانية: فرسوم الرقم والحملة والمراسلة الحالية تستمر وفق شروط حسابك.

في البوابة، يؤدي التغيير إلى حملة مختلفة إلى إزالة الارتباط السابق أولًا ثم إضافة الارتباط الجديد. وهذان طلبان منفصلان. إذا فشل الطلب الثاني، فقد يكون الارتباط السابق قد أُزيل بالفعل. لا تفترض أن الطلبين يتراجعان معًا.