Help Center תאימות GMS API

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

Warning

תצורת סקר 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 נדחתה.

Search Results

תאימות GMS API

הגדרות חיבור

בקש פרמטרים

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

פורמט תגובה

תגובה מוצלחת

תגובות שגיאה

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

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

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

מיפויי סטטוס

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

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

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

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

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

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

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

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