Help Center תאימות API של Messagio

תאימות 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:

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

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

פרמטרהקלדחובהתיאור
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

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

| פרמטר | הקלד | חובה | תיאור |
| :--- | :--- | :--- | :--- |
| `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

פורמט תגובה

נקודת הקצה של תאימות ה-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>

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

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

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

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

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

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

נמסר: http msg_id=MESSAGE_GUID&status=delivered נראה/נקרא: http 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.