GMS API kompatibilitás

Az SMSBAT támogatja a GMS API kompatibilitási rétegét. Ez lehetővé teszi, hogy a GMS-hez tervezett meglévő integrációit közvetlenül az SMSBAT-ba helyezze át anélkül, hogy módosítania kellene az üzenettovábbítási sémákat, a hasznos adatszerkezeteket vagy a visszahívási figyelőket.

Csatlakozási beállítások

A kérések SMSBAT-on keresztüli irányításához frissítse az alap URL-t és a hitelesítési adatokat az integrációban:

Alap URL: https://restapi.smsbat.com
Végpont: POST /api/GMSMessage/send_message
Kérés formátuma: Application/json
Hitelesítés: HTTP alapszintű hitelesítés (az Ön SMSBAT API hitelesítő adatait használja)

Paraméterek kérése

A GMS-kompatibilitási API a következő legfelső szintű paraméterekkel rendelkező JSON-objektumot fogadja el:

Paraméter	Típus	Kötelező	Leírás
`telefonszám`	húr	Igen	A címzett telefonszáma nemzetközi formátumban (pl. "380501234567").
"címke"	húr	Igen	Regisztrált feladó neve / alfa név.
"csatornák"	tömb	Igen	A kipróbálandó csatornák listája, prioritási sorrendben. Támogatott értékek: "viber", "sms", "push". Pl. `["viber", "sms"]`.
`csatorna_beállítások`	tárgy	Igen	Az egyes aktív csatornák opcióit tartalmazó térkép (lásd alább).
`extra_id`	húr	Nem	Az Ön belső ügyféloldali üzenetazonosítója.
`visszahívási_url`	húr	Nem	Végpont URL a rendszerén a kézbesítési állapot visszahívásainak fogadásához.
`felosztás_kódja`	húr	Nem	Opcionális felosztási kód azonosító (alapértelmezett a "fő").

Csatornabeállítások beállításai

A channel_options objektum csatornaspecifikus konfigurációkat tartalmaz.

Viber üzenetViber SMS tartalékkalSMS üzenetViber felmérésViber CarouselPush Message

Akkor használatos, ha a „viber” szerepel a „channels” tömbben.

Paraméter	Típus	Kötelező	Leírás
"szöveg"	húr	Igen	Üzenettörzs szövege.
"ttl"	egész	Igen	Élettartam másodpercekben.
"img"	húr	Nem	A megjelenítendő kép nyilvános HTTPS URL-je.
"felirat"	húr	Nem	Gomb szöveges címke.
"cselekvés"	húr	Nem	Cél URL a gombra kattintva.
`survey_options`	tömb	Nem	Karakterláncok tömbje (2–5 elem), amelyek felmérési opcióként jeleníthetők meg.
`carousel_items`	tömb	Nem	Viber-körhintaként megjelenítendő diaobjektumok tömbje (lásd a szerkezetet a lapon).

Viber-kérés példa:

{
  "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"
    }
  }
}

Lehetővé teszi a Viber-üzenetküldést automatikus SMS-visszaállítással, ha a Viber kézbesítés meghiúsul a TTL-n belül.

Példa tartalék kérelemre:

{
  "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
    }
  }
}

Akkor használatos, ha az "sms" szerepel a "channels" tömbben.

Paraméter	Típus	Kötelező	Leírás
"szöveg"	húr	Igen	Üzenettörzs szövege.
`alfa_név`	húr	Igen	Feladó alfa neve.
"ttl"	egész	Igen	Élettartam másodpercekben.
`ctr`	logikai	Nem	Engedélyezze a CTR-kattintások nyomon követését a szöveges linkeken ("igaz"/"hamis").

Példa SMS-kérésre:

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

Viber szavazások és felmérések készítésére szolgál.

Figyelmeztetés

A Viber felmérés konfigurációjában 2 és 5 között kell lennie a survey_options-ban.

Példa felmérés kérésre:

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

Csúsztatható diakártyák küldésére szolgál. Minden dia támogatja a képet, a címet és a gombokat.

Példa a körhinta kérésére:

href="#__codelineno-4-1">{ "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" } ] } } }

Akkor használatos, ha a "push" szerepel a "channels" tömbben.

Paraméter	Típus	Kötelező	Leírás
"cím"	húr	Igen	A push értesítés címszövege.
"szöveg"	húr	Igen	Üzenettörzs szövege.
"ttl"	egész	Igen	Élettartam másodpercekben.
"img"	húr	Nem	A megjelenítendő kép nyilvános HTTPS URL-je.
"felirat"	húr	Nem	Gomb szöveges címke.
"cselekvés"	húr	Nem	Cél URL a gombra kattintva.
`ctr`	logikai	Nem	Kattintáskövetés engedélyezése.

Példa 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
    }
  }
}

Válaszformátum

A végpont JSON formátumban ad vissza válaszokat "HTTP 200 OK" állapotkóddal.

Sikeres válasz

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

Hibaválaszok

Ha az érvényesítés vagy a feldolgozás sikertelen, egy hibaválasz nem nulla "ErrorCode" és részletes "ErrorText" jelenik meg.

Nem támogatott csatorna/opcióÉrvénytelen felmérési opciók számaNem regisztrált alfa névBelső feldolgozási hiba

{
  "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."
}

Visszahívás kézbesítési formátum

Ha a „callback_url” meg van adva a kérésben, az SMSBAT a kézbesítési állapotfrissítéseket JSON POST-adatként küldi el a végpontnak.

Példa visszahívási kérelemre

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
}

Visszahívási mezők leírása

Mező	Típus	Leírás
"szám"	húr	Címzett telefonszáma.
"idő"	szám	Esemény időbélyegzője Unix ezredmásodpercben.
"állapot"	szám	Egyszerűsített állapotazonosító (lásd az állapotkód táblázatot).
"alállapot"	szám	Részletes állapotazonosító (lásd az Alállapot kódtáblázatát).
`hiber_állapot`	szám	Részletes SMSBAT belső állapotkód (lásd a Hiberállapot táblázatot).
`üzenet_azonosítója`	húr	SMSBAT üzenetazonosító (GUID) a küldéskor generálva.
`extra_id`	húr	Az eredeti kérésben megadott ügyféloldali azonosító.
`elküldve`	húr	Az üzenetet feldolgozó csatorna: "viber", "sms" vagy "rcs".
`matching_template_id`	szám	Viber-sablon egyezési állapota (ha van).

Állapotleképezések

1. Egyszerűsített állapot (`status`)

Kód	Jelentése
"1"	Üzenet elfogadva vagy kézbesítve.
"2"	Üzenet kézbesítve.
"3"	Feldolgozási vagy kézbesítési hiba.

2. Részletes állapot (`substatus`)

Kód	Jelentése
"12"	Feldolgozásra elfogadva.
"23"	Szállítva.
"24"	Látott/olvasott.
"35"	Nem TTL-n belül szállítják (lejárt).
"36"	Célbajuttatási hiba.

3. Csatorna típusa (`sent_via`)

Csatorna	Leírás
`viber`	A Viber csatorna által előállított állapot.
`sms`	SMS csatorna által előállított állapot.
"rcs"	Az RCS csatorna által előállított állapot.

4. Részletes SMSBAT állapot (`hyber_status`)

Kód	Csatorna	Állapot	Alállapot	Jelentése
23033	`viber`	"2"	"23"	Viber üzenet kézbesítve.
24013	`viber`	"2"	"24"	Viber üzenetet olvasott a címzett (Látva).
36013	`viber`	"3"	"36"	Viber belső hiba.
36023	`viber`	"3"	"36"	Érvénytelen vagy nem elérhető Viber szolgáltatásazonosító.
36033	`viber`	"3"	"36"	Érvénytelen Viber hasznos adat.
36037	`viber`	"3"	"36"	A Viber kép URL-je túl hosszú.
36038	`viber`	"3"	"36"	Érvénytelen Viber-kép URL-je.
36039	`viber`	"3"	"36"	A Viber szöveg túl hosszú.
36044	`viber`	"3"	"36"	Üres Viber szöveg.
36053	`viber`	"3"	"36"	Nem támogatott Viber üzenettípus.
36063	`viber`	"3"	"36"	Érvénytelen Viber paraméterek.
36073	`viber`	"3"	"36"	Viber szolgáltató időtúllépés.
36083	`viber`	"3"	"36"	A címzett letiltotta a Viber küldőt.
36093	`viber`	"3"	"36"	A címzett nem regisztrált Viber-felhasználóként.
36103	`viber`	"3"	"36"	Nem található Viber-támogatással rendelkező Android/iOS-eszköz.
36113	`viber`	"3"	"36"	Jogosulatlan IP-cím a Viber küldéshez.
36123	`viber`	"3"	"36"	Duplikált Viber-üzenet észlelve.
36143	`viber`	"3"	"36"	Viber számlázási hiba.
36153	`viber`	"3"	"36"	Az üzenetet blokkolta a platform tiltólistája.
36163	`viber`	"3"	"36"	Viber platform belső feldolgozási hiba.
36173	`viber`	"3"	"36"	Hibás vagy hiányzó Viber címke.
36183	`viber`	"3"	"36"	Érvénytelen Viber TTL érték.
12011	`sms` / `rcs`	"1"	"12"	SMS/RCS elfogadva.
36011	`sms` / `rcs`	"1"	"12"	SMS/RCS útközben.
23011	`sms` / `rcs`	"2"	"23"	SMS/RCS kézbesítve.
35015	`sms` / `rcs`	"3"	"35"	Az SMS/RCS lejárt (nem kézbesítve TTL-en belül).
36021	`sms` / `rcs`	"3"	"36"	SMS/RCS üzenet törölve.
36031	`sms` / `rcs`	"3"	"36"	SMS/RCS nem kézbesíthető.
36041	`sms` / `rcs`	"3"	"36"	Ismeretlen SMS/RCS kézbesítési állapot.
36051	`sms` / `rcs`	"3"	"36"	SMS/RCS üzenet elutasítva.