Kompatibilita GMS API

SMSBAT podporuje vrstvu kompatibility s GMS API. To vám umožňuje migrovať vaše existujúce integrácie navrhnuté pre GMS priamo na SMSBAT bez toho, aby ste museli upravovať schémy smerovania správ, štruktúry užitočného zaťaženia alebo poslucháčov spätných volaní.

Nastavenia pripojenia

Ak chcete smerovať požiadavky cez SMSBAT, aktualizujte základnú webovú adresu a overovacie poverenia vo svojej integrácii:

Základná adresa URL: https://restapi.smsbat.com
Koncový bod: POST /api/GMSMessage/send_message
Formát žiadosti: application/json
Autentifikácia: Základná autentifikácia HTTP (používa vaše poverenia SMSBAT API)

Parametre požiadavky

Rozhranie API kompatibility GMS akceptuje objekt JSON s nasledujúcimi parametrami najvyššej úrovne:

Parameter	Typ	povinné	Popis
`telefónne_číslo`	reťazec	Áno	Telefónne číslo príjemcu v medzinárodnom formáte (napr. „380501234567“).
"značka"	reťazec	Áno	Registrované meno odosielateľa / alfa meno.
"kanály"	pole	Áno	Zoznam kanálov na vyskúšanie v poradí podľa priority. Podporované hodnoty: `viber`, `sms`, `push`. Napr. „["viber", "sms"]".
`channel_options`	objekt	Áno	Mapa obsahujúca možnosti pre každý aktívny kanál (pozri nižšie).
`extra_id`	reťazec	Nie	Vaše interné ID správy na strane zákazníka.
`callback_url`	reťazec	Nie	Webová adresa koncového bodu vo vašom systéme na prijímanie spätných volaní stavu doručenia.
`kód_divízie`	reťazec	Nie	Voliteľný identifikátor kódu divízie (predvolený je „hlavný“).

Nastavenia možností kanála

Objekt channel_options obsahuje konfigurácie špecifické pre kanál.

Správa ViberViber s podporou SMSSMS správaPrieskum ViberViber CarouselSpráva push

Používa sa, keď je v poli kanálov uvedený výraz viber.

Parameter	Typ	povinné	Popis
"text"	reťazec	Áno	Text správy.
`ttl`	celé číslo	Áno	Time-To-Live v sekundách.
"img"	reťazec	Nie	Verejná HTTPS adresa URL obrázka, ktorý sa má zobraziť.
"nápis"	reťazec	Nie	Textový štítok tlačidla.
"akcia"	reťazec	Nie	Cieľová adresa URL po kliknutí na tlačidlo.
`možnosti_prieskumu`	pole	Nie	Pole reťazcov (2 až 5 položiek), ktoré sa majú zobraziť ako možnosti prieskumu.
`carousel_items`	pole	Nie	Pole objektov snímky, ktoré sa majú zobraziť ako karusel Viber (pozri štruktúru na karte).

Príklad žiadosti 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"
    }
  }
}

Umožňuje odosielanie správ Viber s automatickou núdzovou správou SMS, ak doručenie Viber zlyhá v rámci TTL.

Príklad záložnej žiadosti:

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

Používa sa, keď je sms uvedený v poli channels.

Parameter	Typ	povinné	Popis
"text"	reťazec	Áno	Text správy.
`alpha_name`	reťazec	Áno	Alfa meno odosielateľa.
`ttl`	celé číslo	Áno	Time-To-Live v sekundách.
"ctr"	boolean	Nie	Povoliť sledovanie CTR kliknutí na odkazy v texte (`true`/`false`).

Príklad SMS žiadosti:

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

Používa sa na vytváranie prieskumov a prieskumov Viber.

Varovanie

Konfigurácia prieskumu Viber musí mať 2 až 5 možností v survey_options.

Príklad žiadosti o prieskum:

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

Používa sa na odosielanie posúvateľných obrázkových kariet. Každá snímka podporuje obrázok, názov a tlačidlá.

Príklad žiadosti o posuvný pás:

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

Používa sa, keď je push uvedený v poli channels.

Parameter	Typ	povinné	Popis
"názov"	reťazec	Áno	Text nadpisu oznámenia push.
"text"	reťazec	Áno	Text správy.
`ttl`	celé číslo	Áno	Time-To-Live v sekundách.
"img"	reťazec	Nie	Verejná HTTPS adresa URL obrázka, ktorý sa má zobraziť.
"nápis"	reťazec	Nie	Textový štítok tlačidla.
"akcia"	reťazec	Nie	Cieľová adresa URL po kliknutí na tlačidlo.
"ctr"	boolean	Nie	Povoliť sledovanie kliknutí.

Príklad žiadosti push:

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

Formát odpovede

Koncový bod vracia odpovede vo formáte JSON so stavovým kódom „HTTP 200 OK“.

Úspešná odpoveď

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

Odpovede na chyby

Ak overenie alebo spracovanie zlyhá, vráti sa chybová odpoveď s nenulovým kódom chyby a podrobným textom chyby.

Nepodporovaný kanál/možnosťNeplatný počet možností prieskumuNeregistrovaný názov alfaInterná chyba spracovania

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

Formát doručenia spätného volania

Ak bol v požiadavke zadaný parameter „callback_url“, SMSBAT odošle aktualizácie stavu doručenia ako užitočné zaťaženie JSON POST do vášho koncového bodu.

Príklad žiadosti o spätné volanie

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
}

Popis polí spätného volania

Pole	Typ	Popis
"číslo"	reťazec	Telefónne číslo príjemcu.
"čas"	číslo	Časová pečiatka udalosti v milisekundách Unix.
"stav"	číslo	Zjednodušený identifikátor stavu (pozri tabuľku kódov stavu).
"podstav"	číslo	Podrobný identifikátor stavu (pozri tabuľku kódov podstavu).
`hyber_status`	číslo	Podrobný interný stavový kód SMSBAT (pozri tabuľku Hyber Status).
`ID_správy`	reťazec	ID správy SMSBAT (GUID) vygenerované pri odosielaní.
`extra_id`	reťazec	ID na strane zákazníka uvedené v pôvodnej žiadosti.
`sent_via`	reťazec	Kanál, ktorý správu spracoval: `viber`, `sms` alebo `rcs`.
`matching_template_id`	číslo	Stav zhody šablóny Viber (ak je to možné).

Mapovania stavu

1. Zjednodušený stav („stav“)

Kód	Význam
"1"	Správa bola prijatá alebo doručená.
"2"	Správa doručená.
"3"	Chyba spracovania alebo doručenia.

2. Podrobný stav („podstav“)

Kód	Význam
"12"	Prijaté na spracovanie.
"23"	Doručené.
"24"	Videné/prečítané.
"35"	Nedoručené v rámci TTL (platnosť vypršala).
"36"	Chyba doručenia.

3. Typ kanála (`sent_via`)

Kanál	Popis
"viber"	Stav vytvorený kanálom Viber.
`sms`	Stav vytvorený kanálom SMS.
"rcs"	Stav vytvorený kanálom RCS.

4. Podrobný stav SMSBAT (`hyber_status`)

Kód	Kanál	Stav	Substatus	Význam
23033	"viber"	"2"	"23"	Správa Viber doručená.
24013	"viber"	"2"	"24"	Správa Viber prečítaná príjemcom (videná).
36013	"viber"	"3"	"36"	Vnútorná chyba Viber.
36023	"viber"	"3"	"36"	Neplatné alebo nedostupné ID služby Viber.
36033	"viber"	"3"	"36"	Neplatné údaje o užitočnom zaťažení Viber.
36037	"viber"	"3"	"36"	Adresa URL obrázka Viber je príliš dlhá.
36038	"viber"	"3"	"36"	Neplatná adresa URL obrázka Viber.
36039	"viber"	"3"	"36"	Text Viber je príliš dlhý.
36044	"viber"	"3"	"36"	Prázdny text Viber.
36053	"viber"	"3"	"36"	Nepodporovaný typ správy Viber.
36063	"viber"	"3"	"36"	Neplatné parametre Viber.
36073	"viber"	"3"	"36"	Časový limit poskytovateľa Viber vypršal.
36083	"viber"	"3"	"36"	Odosielateľ Viber je zablokovaný príjemcom.
36093	"viber"	"3"	"36"	Príjemca nie je registrovaný ako používateľ Viber.
36103	"viber"	"3"	"36"	Nenašlo sa žiadne zariadenie so systémom Android/iOS s podporou Viber.
36113	"viber"	"3"	"36"	Neoprávnená IP adresa na odosielanie Viber.
36123	"viber"	"3"	"36"	Bola zistená duplicitná správa Viber.
36143	"viber"	"3"	"36"	Chyba fakturácie Viber.
36153	"viber"	"3"	"36"	Správa je zablokovaná na čiernej listine platformy.
36163	"viber"	"3"	"36"	Interná chyba spracovania platformy Viber.
36173	"viber"	"3"	"36"	Nesprávny alebo chýbajúci štítok Viber.
36183	"viber"	"3"	"36"	Neplatná hodnota Viber TTL.
12011	`sms` / `rcs`	"1"	"12"	SMS/RCS akceptované.
36011	`sms` / `rcs`	"1"	"12"	SMS/RCS na ceste.
23011	`sms` / `rcs`	"2"	"23"	SMS/RCS doručené.
35015	`sms` / `rcs`	"3"	"35"	Platnosť SMS/RCS vypršala (nedoručené v rámci TTL).
36021	`sms` / `rcs`	"3"	"36"	Správa SMS/RCS bola odstránená.
36031	`sms` / `rcs`	"3"	"36"	SMS/RCS nie je možné doručiť.
36041	`sms` / `rcs`	"3"	"36"	Neznámy stav doručenia SMS/RCS.
36051	`sms` / `rcs`	"3"	"36"	Správa SMS/RCS bola odmietnutá.