לדלג לתוכן

תאימות GMS API

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

הגדרות חיבור

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

  • כתובת אתר בסיס: https://restapi.smsbat.com
  • נקודת קצה: POST /api/GMSMessage/send_message
  • פורמט בקשה: application/json
  • אימות: אימות HTTP בסיסי (משתמש באישורי ה-SMSBAT API שלך)

בקש פרמטרים

ממשק API של תאימות GMS מקבל אובייקט JSON עם הפרמטרים הבאים ברמה העליונה:

פרמטר הקלד חובה תיאור
מספר_טלפון מחרוזת כן מספר הטלפון של הנמען בפורמט בינלאומי (לדוגמה, 380501234567).
תג מחרוזת כן שם השולח רשום / שם אלפא.
ערוצים מערך כן רשימת ערוצים לנסות, בסדר עדיפות. ערכים נתמכים: viber, sms, push. למשל, ["viber", "sms"].
אפשרויות_ערוץ חפץ כן מפה המכילה אפשרויות עבור כל ערוץ פעיל (ראה להלן).
extra_id מחרוזת לא מזהה ההודעה הפנימית שלך בצד הלקוח.
callback_url מחרוזת לא כתובת URL של נקודת קצה במערכת שלך לקבלת התקשרות חוזרת של סטטוס מסירה.
קוד_חלוקה מחרוזת לא מזהה קוד חלוקה אופציונלי (ברירת המחדל הוא 'ראשי').

הגדרות אפשרויות ערוץ

האובייקט channel_options מכיל תצורות ספציפיות לערוץ.

משמש כאשר 'viber' מופיע במערך 'ערוצים'.

פרמטר הקלד חובה תיאור
טקסט מחרוזת כן טקסט גוף ההודעה.
ttl מספר שלם כן Time-To-Live בשניות.
img מחרוזת לא כתובת URL ציבורית של HTTPS של התמונה להצגה.
כיתוב מחרוזת לא תווית טקסט לחצן.
פעולה מחרוזת לא כתובת אתר יעד בעת לחיצה על הכפתור.
אפשרויות_סקר מערך לא מערך של מחרוזות (2 עד 5 פריטים) להצגה כאפשרויות סקר.
פריטי_קרוסלה מערך לא מערך אובייקטי שקופיות להצגה כקרוסלת Viber (ראה מבנה בכרטיסייה).

דוגמה לבקשת Viber: 

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Hello from SMSBAT!",
      "ttl": 60,
      "img": "https://www.example.com/image.png",
      "caption": "Open",
      "action": "https://www.example.com"
    }
  }
}

מאפשר העברת הודעות Viber עם ביטול SMS אוטומטי אם משלוח Viber נכשל בתוך ה-TTL.

דוגמה לבקשת החזרה: 

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber", "sms"],
  "channel_options": {
    "viber": {
      "text": "Your order is ready!",
      "ttl": 60,
      "caption": "Details",
      "action": "https://www.example.com/order"
    },
    "sms": {
      "text": "Your order is ready: https://www.example.com/order",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}

משמש כאשר 'sms' מופיע במערך 'ערוצים'.

פרמטר הקלד חובה תיאור
טקסט מחרוזת כן טקסט גוף ההודעה.
שם_אלפא מחרוזת כן שם אלפא השולח.
ttl מספר שלם כן Time-To-Live בשניות.
ctr בוליאני לא אפשר מעקב אחר קליקים על קישורים בטקסט (נכון/שקר).

דוגמה לבקשת SMS: 

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["sms"],
  "channel_options": {
    "sms": {
      "text": "Your verification code is 1234",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}

משמש ליצירת סקרים וסקרים של Viber.

אזהרה

תצורת סקר Viber חייבת לכלול בין 2 ל-5 אפשרויות בתוך survey_options.

דוגמה לבקשת סקר: 

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Please rate our service:",
      "ttl": 60,
      "survey_options": [
        "Excellent",
        "Good",
        "Bad"
      ]
    }
  }
}

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

דוגמה לבקשת קרוסלה: 

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Choose an offer",
      "ttl": 60,
      "carousel_items": [
        {
          "title": "Offer 1",
          "image_url": "https://www.example.com/offer-1.png",
          "primary_label": "Open",
          "primary_url": "https://www.example.com/offer-1",
          "secondary_label": "More",
          "secondary_url": "https://www.example.com/offers"
        },
        {
          "title": "Offer 2",
          "image_url": "https://www.example.com/offer-2.png",
          "primary_label": "Open",
          "primary_url": "https://www.example.com/offer-2"
        }
      ]
    }
  }
}

משמש כאשר 'push' מופיע במערך 'ערוצים'.

פרמטר הקלד חובה תיאור
כותרת מחרוזת כן טקסט הכותרת של הודעת הדחיפה.
טקסט מחרוזת כן טקסט גוף ההודעה.
ttl מספר שלם כן Time-To-Live בשניות.
img מחרוזת לא כתובת URL ציבורית של HTTPS של התמונה להצגה.
כיתוב מחרוזת לא תווית טקסט לחצן.
פעולה מחרוזת לא כתובת אתר יעד בעת לחיצה על הכפתור.
ctr בוליאני לא אפשר מעקב אחר קליקים.

דוגמה ל-Push Request: 

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["push"],
  "channel_options": {
    "push": {
      "title": "Order update",
      "text": "Your order is ready for pickup!",
      "ttl": 60,
      "img": "https://www.example.com/push.png",
      "caption": "Open",
      "action": "https://www.example.com/order",
      "ctr": false
    }
  }
}

פורמט תגובה

נקודת הקצה מחזירה תגובות ב-פורמט JSON עם קוד סטטוס HTTP 200 OK.

תגובה מוצלחת

{
  "MessageId": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "ErrorCode": null,
  "ErrorText": null
}

תגובות שגיאה

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

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "This type of Message is not supported by the system"
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "There can be from 2 to 5 survey options."
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 400,
  "ErrorText": "Cannot send to international number: alpha name 'ALPHA' is not registered."
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 500,
  "ErrorText": "Internal server error."
}

פורמט מסירה להתקשרות חוזרת

אם 'callback_url' צוין בבקשה, SMSBAT שולח עדכוני סטטוס מסירה כמטען JSON POST לנקודת הקצה שלך.

דוגמה לבקשת התקשרות חוזרת

POST /your-callback-endpoint HTTP/1.1
Host: yoursystem.com
Content-Type: application/json

{
  "number": "380501234567",
  "time": 1719237600000,
  "status": 2,
  "substatus": 23,
  "hyber_status": 23033,
  "message_id": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "extra_id": "ORDER-12345",
  "sent_via": "viber",
  "matching_template_id": 0
}

שדות התקשרות חוזרים תיאור

שדה הקלד תיאור
מספר מחרוזת מספר טלפון של הנמען.
זמן מספר חותמת זמן של אירוע באלפיות שניות של יוניקס.
סטטוס מספר מזהה סטטוס פשוט (ראה טבלת קודי מצב).
תת-סטטוס מספר מזהה סטטוס מפורט (ראה טבלת קודי משנה).
היבר_סטטוס מספר קוד סטטוס פנימי מפורט של SMSBAT (ראה טבלת מצב היבר).
מזהה_הודעה מחרוזת מזהה הודעת SMSBAT (GUID) שנוצר בעת השליחה.
extra_id מחרוזת מזהה בצד הלקוח מסופק בבקשה המקורית.
שלח_via מחרוזת ערוץ שעיבד את ההודעה: viber, sms או rcs.
מזהה_תבנית_תואם מספר סטטוס התאמת תבנית Viber (כאשר רלוונטי).

מיפויי סטטוס

1. סטטוס פשוט (סטטוס)

קוד המשמעות
1 ההודעה התקבלה או נמסרת.
2 ההודעה נמסרה.
3 שגיאת עיבוד או מסירה.

2. סטטוס מפורט (תת-סטטוס)

קוד המשמעות
12 התקבל לעיבוד.
23 נמסר.
24 ראה/קרא.
35 לא נמסר בתוך TTL (פג תוקף).
36 טעות מסירה.

3. סוג ערוץ (שלח_via)

ערוץ תיאור
viber סטטוס מיוצר על ידי ערוץ Viber.
sms סטטוס מופק על ידי ערוץ SMS.
rcs סטטוס מיוצר על ידי ערוץ RCS.

4. סטטוס SMSBAT מפורט (hyber_status)

קוד ערוץ סטטוס תת-סטטוס המשמעות
23033 viber 2 23 הודעת Viber נמסרה.
24013 viber 2 24 הודעת Viber נקראת על ידי הנמען (נראה).
36013 viber 3 36 שגיאה פנימית של Viber.
36023 viber 3 36 מזהה שירות Viber לא חוקי או לא זמין.
36033 viber 3 36 נתוני מטען Viber לא חוקיים.
36037 viber 3 36 כתובת האתר של תמונת Viber ארוכה מדי.
36038 viber 3 36 כתובת אתר לא חוקית של תמונת Viber.
36039 viber 3 36 טקסט Viber ארוך מדי.
36044 viber 3 36 טקסט Viber ריק.
36053 viber 3 36 סוג הודעת Viber לא נתמך.
36063 viber 3 36 פרמטרים לא חוקיים של Viber.
36073 viber 3 36 פסק זמן של ספק Viber.
36083 viber 3 36 שולח Viber נחסם על ידי הנמען.
36093 viber 3 36 הנמען אינו רשום כמשתמש Viber.
36103 viber 3 36 לא נמצא מכשיר אנדרואיד/iOS עם תמיכה ב-Viber.
36113 viber 3 36 כתובת IP לא מורשית לשליחת Viber.
36123 viber 3 36 זוהתה הודעת Viber כפולה.
36143 viber 3 36 שגיאת חיוב של Viber.
36153 viber 3 36 הודעה חסומה על ידי הרשימה השחורה של הפלטפורמה.
36163 viber 3 36 שגיאת עיבוד פנימית של פלטפורמת Viber.
36173 viber 3 36 תווית Viber שגויה או חסרה.
36183 viber 3 36 ערך Viber TTL לא חוקי.
12011 sms / rcs 1 12 התקבלו SMS/RCS.
36011 sms / rcs 1 12 SMS/RCS בדרך.
23011 sms / rcs 2 23 נמסר SMS/RCS.
35015 sms / rcs 3 35 פג תוקף ה-SMS/RCS (לא נמסר בתוך TTL).
36021 sms / rcs 3 36 הודעת SMS/RCS נמחקה.
36031 sms / rcs 3 36 לא ניתן לשלוח SMS/RCS.
36041 sms / rcs 3 36 סטטוס משלוח SMS/RCS לא ידוע.
36051 sms / rcs 3 36 הודעת SMS/RCS נדחתה.