שליחת SMS ו־MMS נתמך

לפני השליחה

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

החשבון שלכם זקוק לאישור לשליחת הודעות יוצאות ולהרשאות המתאימות לשולח, למדינה ולתעבורת ההודעות. פרטי הזדהות ישירים של משתמשים אישיים או צרכניים אינם זכאים לשימוש ב־API זה. לפרטי הזדהות ייעודיים ומאושרים ל־API יש מסלול זכאות נפרד; שולחי P2P סלולריים עשויים להזדקק להרשאות P2P נוספות ולהרשאות לארצות הברית ולקנדה. ודאו עם MultiTEL שהחשבון מוגדר כראוי, ואל תראו בפרטי הזדהות ל־API הרשאה אוטומטית לשליחת כל סוג של תעבורה.

בקשת שליחה

הזדהו דרך HTTPS באמצעות חשבון API פעיל, מכתובת IP מקור שמורשית עבורו. שמרו את פרטי ההזדהות במאגר סודות בצד השרת. השתמשו ב־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, את status.code ב־JSON ואת status/message שבתשובה. קודי התוצאה עשויים להיות מחרוזות. שמרו את sms_log_id_ori ואת ערכי ההודעה והאסמכתה שהוחזרו, לצורך קישור הנתונים בעת פנייה לתמיכה. ערכי uniqueid ו־pid הוותיקים משתנים בין המסלולים; אל תסיקו מהו הפורמט שלהם ואל תניחו שהם אסימוני אידמפוטנטיות של הלקוח.

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

מקטעים וחיובים

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

cost ו־permsg הם מחרוזות בפורמט כספי בתשובה הוותיקה. carrier_fee_usd מציין את רכיב עמלת המפעיל ב־USD, והוא כבר נכלל בסכום השליחה הכולל שחושב; אל תוסיפו אותו פעם נוספת. יש לבדוק את התמחור בפועל ואת זמינות המסלולים עבור החשבון שלכם. הבקשה אינה פעולה לבירור מחיר בלבד.

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

מסירה מקומית ותוצאות מעורבות

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

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

כשלים והתאוששות בטוחה

כשלים בבדיקת תקינות עשויים להשתמש בקוד API 403. דחיות הנוגעות לאישור החשבון, ל־P2P ולמדיניות מדינה עשויות גם להגדיר HTTP 403 ולכלול response.code קריא למכונה. הגבלות קצב עשויות להשתמש ב־429 עם מידע על ניסיון חוזר. מדיניות שאינה זמינה או כשל בשליחה או בשמירה מקומית עשויים להשתמש ב־503 או ב־500; גם המסלול הוותיק לטיפול ביתרה לא מספקת עשוי להחזיר 500.

במקרה של 429, פעלו בהתאם ל־Retry-After ולכל ערך של response.retry_after. במקרה של דחייה הקשורה לחשבון, לשולח, למדינה או לנמען, תקנו את הגורם לפני ניסיון חוזר. במקרה של חריגה מזמן ההמתנה או תוצאת שליחה שאינה ברורה, שמרו את זמן הבקשה, את האסמכתה ואת המזהים שהוחזרו, בדקו את הפורטל ופנו לתמיכה לפני שליחה חוזרת. היעדר רשומה ביומן כשלעצמו אינו הוכחה לכך שאף מפעיל לא קיבל את הבקשה.