לדלג לתוכן

מדריך ממשק API של SMSBAT RESTful

מדריך שלם ל-SMSBAT RESTful API - כל מה שאתה צריך לדעת.

עדכון אחרון: 29 באוגוסט 2025

SMSBAT RESTful API מאפשר לך לשלוח סוגים שונים של הודעות: Viber-carousel, Viber-survey, Viber-promo (תמונות, וידאו), Viber צ'אטים עסקיים, הודעות OTP (Viber OTP, Flash Call), וגרסאות החזר שלהם.

הערה: זהו ה-API המאוחד של HTTP להעברת הודעות יוצאות. אם אתה צריך אינטגרציות עם בוטים נכנסים (Viber Bot / Telegram Bot), אנא עיין ב-Cascade API.

1. פרוטוקול

  • פרוטוקול: HTTPS
  • גוף הבקשה: אובייקט JSON המכיל מערך של 'הודעות'.
  • שיטות:
  • 'GET' כדי להביא נתונים (סטטוס הודעה, יתרה וכו')
  • 'POST' ליצירת אובייקטים (למשל, התחלת שידור/שליחה)
  • PATCH כדי לשנות אובייקטים

2. הרשאה

אנו מספקים מספר שיטות הרשאה לנוחיותך: - אימות HTTP בסיסי (כניסה וסיסמה מלוח המחוונים שלך). - כותרת HTTP מותאמת אישית 'X-Authorization-Key' המכילה אסימון API. - שדה סיסמת HTTP Basic Authentication המכיל את אסימון ה-API (העבירו '@' בתור הכניסה).

ניתן ליצור אסימון API בלוח המחוונים תחת פרופיל משתמש.

בקש דוגמאות

עם אישור בסיסי: 

curl -H "Content-Type: application/json" \
  -X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist \
  --user user:password

עם X-Authorization-Key: 

curl -H "X-Authorization-Key: <token>" \
  -H "Content-Type: application/json" \
  -X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist

3. שליחת הודעות

בפלטפורמת SMSBAT, כל שליחת הודעה (אפילו הודעה בודדת) נחשבת ל"שידור" (רשימת הודעות).

נקודת קצה - שיטה: POST - כתובת אתר: https://api.smsbat.com/bat/messagelist - Headers: Content-Type: application/json

מבנה מטען בסיסי: 

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380936670003",
      "text": "Check out our new products!",
      "type": "viber_carousel",
      "ttl": 300,
      "messageData": { ... }
    }
  ]
}

שדות נדרשים עבור כל אובייקט הודעה:

  • מאת: שם אלפא של השולח מאומת.
  • אל: מספר הטלפון של הנמען (פורמט E.164).
  • סוג: סוג הודעה enum.
  • טקסט: הטקסט הראשי של ההודעה (אופציונלי אם הסוג אינו דורש טקסט).

ערכי 'סוג' נתמכים: - sms - viber_service (או viber_trans) - viber_promo - viber_carousel - סקר_viber - viber_otp - viber_session - flashcall_callback - שיחת הבזק

שדות נפוצים אופציונליים:

  • customerMessageId: מזהה מחרוזת בתוך המערכת שלך (המשמשת למעקב אחר התקשרויות חוזרות). חייב להיות ייחודי לכל הודעה.
  • dtSend: ISO8601 תאריך/שעה של משלוח עתידי מתוכנן.
  • dtExpire: ISO8601 תאריך/שעה של המועד האחרון לאספקה.
  • ttl: זמן-לחיות בשניות. (אם לא מסופק dtExpire, ה-API מחשב את מיפוי ברירת המחדל מהסוג `).

ברירת מחדל של TTL (שניות):

  • sms - 86400 (24 שעות)
  • viber_trans / viber_service - 345600
  • viber_promo - 604800
  • viber_session - 604800

4. ניתוב מיתון (מדורג)

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

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380500505051",
      "text": "test message",
      "type": "viber_service",
      "ttl": 60,
      "fallbacks": [
        {
          "from": "ALPHANAME",
          "to": "380936670003",
          "text": "test sms fallback message2",
          "type": "sms"
        }
      ]
    }
  ]
}
נפילות מופעלות כאשר הספק דוחה את ההודעה הראשית או כאשר ה-TTL פג.

5. סקירה כללית של סוגי הודעות ונתוני הודעות

סוגי הודעות מורכבות דורשות תצורות נוספות המוזרקות למאפיין messageData.

5.1 Viber Promo (viber_promo)

תמונה בלבד 

"messageData":{
  "img":"https://domain.com/image.png"
}

טקסט + לחצן 

"messageData":{
  "buttonText":"Save Now",
  "buttonAction":"https://help.smsbat.com"
}

תמונה + טקסט + לחצן משלב את 'img', 'buttonText' ו-'buttonAction'.

** מטען וידאו: 

"messageData":{
  "video": "https://domain.com/test.mp4",
  "thumbnail": "https://domain.com/carusel.png",
  "fileSize": 12000000,
  "duration": 30
}
(ניתן גם לשלב מאפייני וידאו עם buttonText ו-buttonAction).

5.2 Viber Transactional / Service (viber_trans, viber_service)

אם יש לך תבנית מאושרת המכילה קובץ מצורף: 

"messageData": {
  "fileUrl": "https://domain.com/receipt.pdf",
  "fileName": "Receipt.pdf",
  "fileType": "pdf"
}

דורש מערך carousel.items בתוך messageData.

מגבלות: - אורך פריטים: בין 2 ל-5 פריטים - כותרת: 2 עד 38 תווים - imageUrl: גודל מומלץ JPEG/PNG 215x185

"messageData": {
  "carousel": {
    "items": [
      {
        "title": "50% Off Shoes!",
        "imageUrl": "https://domain.com/image1.png",
        "primaryButton": { "label": "Shop", "actionUrl": "..." },
        "secondaryButton": { "label": "Details", "actionUrl": "..." }
      }
    ]
  }
}

5.4 Viber Survey / רשימה (viber_survey)

יוצר סקר אינטראקטיבי בתצוגת הצ'אט. 

"messageData": {
  "survey": {
    "options": [
      "Excellent", "Good", "Normal", "Bad", "Terrible"
    ]
  }
}
המאפיין 'טקסט' של ההודעה פועל ככותרת הסקר (מקסימום 85 תווים). אתה יכול להעביר בין 2 ל-5 אפשרויות, כל אחת מקסימום 50 תווים.

5.5 Viber OTP (viber_otp)

משתמש בתבניות Viber מקומיות רשומות מראש ברחבי העולם. 

"messageData": {
  "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
  "templateLang": "uk",
  "templateParams": {
    "pin": "3211",
    "business_platform_name": "SMSBAT",
    "code_validity_time": 7
  }
}
פרמטרי תבנית (pin, business_platform_name) תלויים בהחלט לאותיות גדולות. ה-API תומך בגרסאות שונות של שפת קוד ISO (EN, ES, RU, TR, UK וכו').

5.6 שיחת פלאש ('flashcall')

יש להעביר את הספרות האחרונות של מספר החיוג (הקוד שנוצר) באמצעות פרמטר 'טקסט'. אם טקסט מושמט, הקוד עובר אקראית ועליכם לחלץ אותו מגוף ה-API הסינכרוני 200 OK Response (הודעות/טקסט).

{
  "from": "FLASHCALL",
  "to": "380500000000",
  "type": "flashcall",
  "text": "340"
}