לדלג לתוכן

שלח הודעה

שלח הודעות דרך SMSBAT API באמצעות נקודת הקצה /bat/messagelist.

נקודת קצה

POST /bat/messagelist

מבנה הבקשה

גוף הבקשה הוא מערך JSON של אובייקטי הודעה:

{
  "messages": [
    {
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Your message text",
      "customerMessageId": "your-internal-id",
      "ttl": 3600
    }
  ]
}

פרמטרים

פרמטרים נדרשים

פרמטר הקלד תיאור
מ מחרוזת מזהה שולח אלפאנומרי
אל מחרוזת מספר הטלפון של הנמען בפורמט E.164 (לדוגמה, +380XXXXXXXXX)
סוג מחרוזת סוג הודעה: sms, viber_promo, viber_trans, viber_carousel, viber_survey, viber_otp, rcs, flashcall
טקסט מחרוזת תוכן הודעה (נדרש עבור רוב הסוגים, אופציונלי עבור חלקם)

פרמטרים אופציונליים

פרמטר הקלד תיאור
customerMessageId מחרוזת המזהה הפנימי שלך למעקב
ttl מספר שלם זמן לחיות בשניות
messageData חפץ תצורה ספציפית לסוג (משתנה לפי סוג ההודעה)

אימות

בחר אחת משלוש שיטות אימות:

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -H "X-Authorization-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -u "@:your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'

תגובה

תגובת הצלחה

{
  "messagelistId": 123456,
  "messages": [
    {
      "messageId": "abc123def456",
      "status": "accepted",
      "parts": 1,
      "customerMessageId": "your-internal-id",
      "to": "+380XXXXXXXXX"
    }
  ]
}

שדות תגובה

שדה הקלד תיאור
messagelistId מספר שלם מזהה ייחודי לרשימת ההודעות
messageId מחרוזת מזהה ייחודי לכל הודעה
סטטוס מחרוזת סטטוס הודעה: מקובל, נדחה, נכשל
חלקים מספר שלם מספר חלקי ההודעה (עבור SMS)
customerMessageId מחרוזת המזהה הפנימי שלך (אם מסופק)
אל מחרוזת מספר טלפון של הנמען

סוגי הודעות

SMS

הודעות טקסט פשוטות:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "sms",
  "text": "Your SMS message text"
}

פרומו של Viber

הודעות קידום מכירות עם מדיה עשירה:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_promo",
  "text": "Check out our new product!",
  "messageData": {
    "image": "https://example.com/image.jpg",
    "button": {
      "text": "View Product",
      "url": "https://example.com/product"
    }
  }
}

Viber עסקה

הודעות על עסקה:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_trans",
  "text": "Your order #12345 has been confirmed"
}

Viber OTP

התראות סיסמא חד פעמיות:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_otp",
  "messageData": {
    "code": "123456",
    "validity": 300
  }
}

טיפול בשגיאות

קודי מצב HTTP

קוד תיאור
200 הבקשה הצליחה
400 בקשה שגויה - פרמטרים לא חוקיים
401 לא מורשה - האימות נכשל
429 יותר מדי בקשות - חריגה ממגבלת התעריף
500 שגיאת שרת פנימית

תגובת שגיאה

{
  "error": {
    "code": "INVALID_RECIPIENT",
    "message": "Invalid phone number format"
  }
}

שיטות עבודה מומלצות

פורמט מספר טלפון

השתמש תמיד בפורמט E.164 עבור מספרי טלפון:

  • ✅ נכון: +380XXXXXXXXX
  • ❌ שגוי: 380XXXXXXXXX, 0XXXXXXXXX

טקסט הודעה

  • שמור SMS מתחת ל-160 תווים כדי להימנע ממספר חלקים
  • השתמש בקידוד UTF-8 עבור תווים בינלאומיים
  • בדוק תווים מיוחדים לפני שליחה בכמות גדולה

TTL (זמן לחיות)

  • הגדר TTL מתאים להודעות רגישות לזמן
  • הודעות OTP: 300-600 שניות (5-10 דקות)
  • הודעות קידום מכירות: 3600-86400 שניות (1-24 שעות)

מזהה הודעת לקוח

  • השתמש במזהים ייחודיים עבור כל הודעה
  • עוזר במעקב ובניפוי באגים
  • שימושי לתיאום עם רישומי המערכת שלך

מגבלות תעריף

פנה למנהל החשבון שלך לקבלת מידע על:

  • הודעות בשנייה
  • הודעות ליום
  • חיבורים במקביל

השלבים הבאים