שיוך מספר לקמפיין הודעות

שיוך מספר שליחה לקמפיין

השתמשו בפעולה זו לאחר שמותג ההודעות וקמפיין הייצור שלכם רשומים והקמפיין פעיל. היא משייכת מספר אחד התומך ב-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. אל תנסו שוב באופן עיוור לאחר פקיעת זמן או תוצאה חלקית. למטפל זה אין מפתח אידמפוטנטיות ברמת הבקשה, חזרה טרנזקציונית למצב הקודם או בדיקת השלמה של רישום הקמפיין. שיוך מקומי חוזר וזהה יכול להחזיר הצלחה גם כאשר מסד הנתונים מדווח שלא שונו שורות.

היקף והשפעות

פעולה זו משנה את ניתוב מספר השליחה ואת שיוך הקמפיין/המותג השמור שלו. במטפל שנסקר היא אינה כוללת חיוב ישיר של החשבון, יצירת קמפיין, רכישה או שליחת הודעה. זו אינה הצעת מחיר ואינה הבטחה לשירות חינם: חיובי המספר, הקמפיין וההודעות הקיימים ממשיכים לפי תנאי חשבונכם.

בפורטל, מעבר לקמפיין אחר מסיר תחילה את השיוך הקודם ואז מוסיף את החדש. אלו בקשות נפרדות. אם הבקשה השנייה נכשלת, ייתכן שהשיוך הקודם כבר הוסר. אל תניחו ששתי הבקשות מתבטלות יחד.