תאימות API של Messagio

SMSBAT תומך בשכבת תאימות עם Messagio API. זה מאפשר לך להעביר את שילובי ה-Viber הקיימים שלך שתוכננו עבור Messagio ישירות ל-SMSBAT מבלי שתצטרך לשכתב את מבנה המטען שלך או לשנות את היגיון האינטגרציה.

הגדרות חיבור

כדי לנתב בקשות דרך SMSBAT, עדכן את כתובת האתר הבסיסית ואת אישורי האימות בשילוב שלך:

כתובת אתר בסיס: https://restapi.smsbat.com
נקודת קצה: POST /api/SendMessage
פורמט בקשה: application/x-www-form-urlencoded (נתוני טופס)

אימות ואישורים

בקשות מאומתות באמצעות פרמטרים הנשלחים ישירות בתוך נתוני גוף הבקשה:

פרמטר	הקלד	חובה	תיאור
`משתמש`	מחרוזת	כן	התחברות לחשבון SMSBAT או מזהה משתמש.
`סימן`	מחרוזת	כן	סוד API או חתימה רשומים עבור שם השולח.
`מ`	מחרוזת	כן	שם אלפא של השולח הרשום.
`שיטת_שליחה`	מחרוזת	כן	סוג ערוץ. השתמש ב-'viber' עבור הודעות Viber Business רגילות או ב-'viber_otp' עבור תבניות Viber OTP.
`טלפון`	מחרוזת	כן	מספר הטלפון של הנמען בפורמט בינלאומי (לדוגמה, `380501234567`).

סוגי הודעות Viber

בחר כרטיסייה למטה כדי להציג את הפרמטרים הספציפיים ולבקש מטענים עבור מבני הודעות שונים של Viber:

הודעת טקסטטקסט + לחצןהודעת תמונהטקסט + תמונה + לחצןהודעת וידאותבנית OTP

שולח הודעת טקסט פשוטה.

פרמטרים נוספים:

פרמטר	הקלד	חובה	תיאור
`txt`	מחרוזת	כן	טקסט הודעה.

דוגמה לבקשת מטען:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Hello+from+SMSBAT%21

שולח הודעת טקסט עם כפתור קריאה לפעולה אינטראקטיבי.

פרמטרים נוספים:

פרמטר	הקלד	חובה	תיאור
`txt`	מחרוזת	כן	טקסט הודעה.
`טקסט_לחצן`	מחרוזת	כן	טקסט המוצג על הכפתור.
`button_link`	מחרוזת	כן	כתובת אתר יעד בעת לחיצה על הכפתור.

דוגמה לבקשת מטען:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Check+our+latest+offers%21&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

שולח קובץ תמונה ציבורי.

פרמטרים נוספים:

פרמטר	הקלד	חובה	תיאור
`קישור_תמונה`	מחרוזת	כן	כתובת אתר HTTPS ציבורית של התמונה.
`txt`	מחרוזת	לא	טקסט כיתוב אופציונלי להצגה מתחת לתמונה.

דוגמה לבקשת מטען:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png

שולח כרטיס עשיר המכיל טקסט, תמונה וכפתור.

פרמטרים נוספים:

פרמטר	הקלד	חובה	תיאור
`txt`	מחרוזת	כן	טקסט כיתוב.
`קישור_תמונה`	מחרוזת	כן	כתובת אתר HTTPS ציבורית של התמונה.
`טקסט_לחצן`	מחרוזת	כן	טקסט המוצג על הכפתור.
`button_link`	מחרוזת	כן	כתובת אתר יעד בעת לחיצה על הכפתור.

דוגמה לבקשת מטען:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Hot+deals+inside%21&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

שולח קובץ וידאו עם כיתוב טקסט אופציונלי ולחצני פעולה.

פרמטרים נוספים:

פרמטר	הקלד	חובה	תיאור
`video.url`	מחרוזת	כן	כתובת URL ציבורית של HTTPS של קובץ הווידאו.
`video.thumbnail`	מחרוזת	כן	כתובת URL ציבורית של HTTPS של תמונת התצוגה המקדימה של הסרטון.
`video.size_mb`	מספר שלם	כן	גודל קובץ וידאו משוער במגה-בייט.
`video.duration_sec`	מספר שלם	כן	משך הסרטון בשניות.
`txt`	מחרוזת	לא	טקסט תיאור אופציונלי.
`טקסט_לחצן`	מחרוזת	לא	טקסט לחצן אופציונלי (יכול לשמש כיתוב או קישור).
`button_link`	מחרוזת	לא	כתובת אתר קישור לחצן אופציונלי.

דוגמה לבקשת מטען:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Watch+this+tutorial%21&video.url=https%3A%2F%2Fwww.example.com%2Fvideo.mp4&video.thumbnail=https%3A%2F%2Fwww.example.com%2Fvideo-thumbnail.png&video.size_mb=1&video.duration_sec=3&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

שולח סיסמאות חד פעמיות של Viber (OTP) באמצעות תבנית מאושרת מראש.

הערה

בעת שליחת הודעות OTP, עליך להגדיר את 'שיטת_שליחה' ל'viber_otp'.

פרמטרים נוספים:

| פרמטר | הקלד | חובה | תיאור |
| :--- | :--- | :--- | :--- |
| `template.id` | מחרוזת | **כן** | מזהה תבנית OTP מאושר מראש של Viber. |
| `template.lang` | מחרוזת | **כן** | קוד שפת תבנית (למשל, `en`, `uk`). |
| `template.params.pin` | מחרוזת | **כן** | ערך סיכת ה-OTP להחדרה לתבנית. |
| `template.params.business_platform_name` | מחרוזת | **כן** | מציין המיקום של שם העסק בתבנית. |
| `template.params.code_validity_time` | מחרוזת | **כן** | תקופת תוקף ה-PIN בדקות. |

**דוגמה לבקשת מטען:**
```http
POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber_otp&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&template.id=otp_template_123&template.lang=en&template.params.pin=123456&template.params.business_platform_name=SMSBAT&template.params.code_validity_time=7
```

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

שולח כרטיס הודעה אינטראקטיבי המכיל מספר שקופיות (כרטיסים) שהמשתמש יכול להחליק דרכם.

פרמטרים נוספים:

פרמטר	הקלד	חובה	תיאור
`txt`	מחרוזת	כן	טקסט הכותרת של הקרוסלה.
`carousel[N].title`	מחרוזת	כן	כותרת הכרטיס 'N' (החל מ-0).
`carousel[N].image_url`	מחרוזת	כן	כתובת האתר של תמונת HTTPS ציבורית של כרטיס 'N'.
`carousel[N].primary_label`	מחרוזת	כן	כיתוב כפתור ראשי של כרטיס 'N'.
`carousel[N].primary_url`	מחרוזת	כן	כתובת האתר של קישור לחצן ראשי של כרטיס 'N'.
`carousel[N].secondary_label`	מחרוזת	לא	כיתוב לחצן משני של כרטיס 'N'.
`carousel[N].secondary_url`	מחרוזת	לא	כתובת האתר של קישור לחצן משני של כרטיס 'N'.

דוגמה לבקשת מטען:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Top+picks+for+you&carousel%5B0%5D.title=First+Offer&carousel%5B0%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-1.png&carousel%5B0%5D.primary_label=Open&carousel%5B0%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-1&carousel%5B0%5D.secondary_label=Details&carousel%5B0%5D.secondary_url=https%3A%2F%2Fwww.example.com%2Fitem-1%2Fdetails&carousel%5B1%5D.title=Second+Offer&carousel%5B1%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-2.png&carousel%5B1%5D.primary_label=Open&carousel%5B1%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-2

שולח הודעה המכילה סקר אינטראקטיבי או שאלת סקר.

פרמטרים נוספים:

פרמטר	הקלד	חובה	תיאור
`txt`	מחרוזת	כן	טקסט שאלת הסקר.
`survey_options[N]`	מחרוזת	כן	טקסט אפשרות סקר עבור פריט 'N' (אינדקס שמתחיל ב-0). נדרשות לפחות 2 אפשרויות.
`סוג_אופציה`	מספר שלם	כן	סוג הבורר: `1` (לחצני רדיו) או `2` (לחצנים רגילים).

דוגמה לבקשת מטען:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Please+rate+our+service&survey_options%5B0%5D=Excellent&survey_options%5B1%5D=Good&survey_options%5B2%5D=Average&option_type=1

פורמט תגובה

נקודת הקצה של תאימות ה-API של Messagio מחזירה תגובות ב-פורמט XML עם קוד סטטוס HTTP 200 OK.

תגובה מקובלת (הצלחה).

<response>
  <code>0</code>
  <tech_message>OK</tech_message>
  <msg_id phone="380501234567">MESSAGE_GUID</msg_id>
</response>

תגובות שגיאה

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

חסרה חתימהלא מורשה

<response>
  <code>-1</code>
  <tech_message>PARAM ERROR (sign)</tech_message>
</response>

<response>
  <code>-2</code>
  <tech_message>ERROR(unauthorized)</tech_message>
</response>

התקשרויות חוזרות

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

1. מצב מסירה התקשרות חוזרת

נשלחה כאשר הודעה עוברת סטטוס (נמסרה, נקראה, נכשלה).

Content-Type: application/x-www-form-urlencoded
שיטה: 'פוסט'

בקש פורמטים של מטען:

נמסר:

msg_id=MESSAGE_GUID&status=delivered

נראה/נקרא:

msg_id=MESSAGE_GUID&status=delivered&type=seen

* לא נמסר / נכשל:

msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

תיאור שדות:

msg_id: מזהה הודעה ייחודי של SMSBAT (GUID) הוחזר בתגובת SendMessage.
סטטוס: תוצאת מסירה (מסירה, לא נמסרה או סטטוס לא ידוע).
סוג: הגדר לנראה כאשר ההודעה נצפה על ידי הנמען.
status_extended: סיבה טכנית ספציפית לסטטוס שלא נמסר (לדוגמה, VIBER_EXPIRED, VIBER_BLOCKED_BY_USER, VIBER_USER_NOT_FOUND, VIBER_NO_DEVICE).

2. תשובה לסקר התקשרות חוזרת

מופעל כאשר משתמש בוחר אפשרות תגובה בהודעת Viber Survey.

Content-Type: application/x-www-form-urlencoded
שיטה: 'פוסט'

פורמט בקשת מטען:

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. התקשרות חוזרת של הודעת משתמש נכנסת

מופעל כאשר משתמש שולח הודעת טקסט או מדיה בחזרה לשירות Viber Business שלך.

Content-Type: application/json
שיטה: 'פוסט'

פורמט בקשת מטען:

{
  "msg_id": "INBOUND_MESSAGE_GUID",
  "text": "Hello, I have a question",
  "media": "https://example.com/user-attachment.png",
  "phone": "380501234567",
  "sender_bm_id": "12345"
}

תיאור שדות:

msg_id: מזהה ההודעה הייחודי שנוצר עבור התשובה הנכנסת.
טקסט: תוכן טקסט שנשלח על ידי המשתמש (יכול להיות null אם הוא שלח מדיה בלבד).
מדיה: כתובת אתר ישירה להורדת קבצי מדיה מצורפים שנשלחו על ידי המשתמש (יכול להיות null אם טקסט בלבד).
טלפון: מספר הטלפון של השולח בפורמט בינלאומי.
sender_bm_id: מזהה השולח של Viber Business.