Kompatibilita GMS API

SMSBAT podporuje vrstvu kompatibility s GMS API. To vám umožní migrovat vaše stávající integrace navržené pro GMS přímo na SMSBAT, aniž byste museli upravovat schémata směrování zpráv, struktury užitečného zatížení nebo posluchače zpětného volání.

Nastavení připojení

Chcete-li směrovat požadavky prostřednictvím SMSBAT, aktualizujte základní adresu URL a ověřovací pověření ve vaší integraci:

Základní adresa URL: https://restapi.smsbat.com
Koncový bod: POST /api/GMSMessage/send_message
Formát požadavku: application/json
Ověření: Základní ověřování HTTP (používá vaše přihlašovací údaje SMSBAT API)

Parametry požadavku

GMS compatibility API přijímá objekt JSON s následujícími parametry nejvyšší úrovně:

Parametr	Typ	Povinné	Popis
`telefonní_číslo`	řetězec	Ano	Telefonní číslo příjemce v mezinárodním formátu (např. „380501234567“).
"tag"	řetězec	Ano	Registrované jméno odesílatele / alfa název.
"kanály"	pole	Ano	Seznam kanálů k vyzkoušení v pořadí podle priority. Podporované hodnoty: `viber`, `sms`, `push`. Např. `["viber", "sms"]`.
`volby_kanálu`	objekt	Ano	Mapa obsahující možnosti pro každý aktivní kanál (viz níže).
`extra_id`	řetězec	Ne	Vaše interní ID zprávy na straně zákazníka.
`callback_url`	řetězec	Ne	Adresa URL koncového bodu ve vašem systému pro příjem zpětných volání stavu doručení.
`kód_oddělení`	řetězec	Ne	Volitelný identifikátor kódu divize (výchozí hodnota je „hlavní“).

Nastavení možností kanálu

Objekt channel_options obsahuje konfigurace specifické pro kanál.

Viber MessageViber se záložní zprávou SMSSMS zprávaPrůzkum ViberViber CarouselPush Message

Používá se, když je viber uveden v poli channels.

Parametr	Typ	Povinné	Popis
"text"	řetězec	Ano	Text zprávy.
`ttl`	celé číslo	Ano	Time-To-Live v sekundách.
`img`	řetězec	Ne	Veřejná HTTPS adresa URL obrázku, který se má zobrazit.
'nápis'	řetězec	Ne	Textový popisek tlačítka.
"akce"	řetězec	Ne	Cílová adresa URL po kliknutí na tlačítko.
`možnosti_průzkumu`	pole	Ne	Pole řetězců (2 až 5 položek), které se zobrazí jako možnosti průzkumu.
`carousel_items`	pole	Ne	Pole objektů snímků k zobrazení jako karusel Viber (viz struktura na kartě).

Příklad požadavku 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"
    }
  }
}

Povolí zasílání zpráv Viber s automatickou zálohou SMS, pokud selže doručení Viber v rámci TTL.

Příklad záložního požadavku:

{
  "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žívá se, když je sms uveden v poli channels.

Parametr	Typ	Povinné	Popis
"text"	řetězec	Ano	Text zprávy.
`alpha_name`	řetězec	Ano	Alfa jméno odesílatele.
`ttl`	celé číslo	Ano	Time-To-Live v sekundách.
`ctr`	booleovský	Ne	Povolit měření CTR kliknutí na odkazy v textu (`true`/`false`).

Příklad SMS požadavku:

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

Používá se k vytváření anket a průzkumů Viber.

Varování

Konfigurace průzkumu Viber musí mít 2 až 5 možností uvnitř survey_options.

Příklad žádosti o průzkum:

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

Používá se k odesílání karet s obrázky s obrázky. Každý snímek podporuje obrázek, název a tlačítka.

Příklad požadavku na 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žívá se, když je push uveden v poli channels.

Parametr	Typ	Povinné	Popis
"titul"	řetězec	Ano	Text titulku oznámení push.
"text"	řetězec	Ano	Text zprávy.
`ttl`	celé číslo	Ano	Time-To-Live v sekundách.
`img`	řetězec	Ne	Veřejná HTTPS adresa URL obrázku, který se má zobrazit.
'nápis'	řetězec	Ne	Textový popisek tlačítka.
"akce"	řetězec	Ne	Cílová adresa URL po kliknutí na tlačítko.
`ctr`	booleovský	Ne	Povolit sledování prokliků.

Příklad požadavku 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 odpovědi

Koncový bod vrací odpovědi ve formátu JSON se stavovým kódem „HTTP 200 OK“.

Úspěšná odpověď

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

Chybové reakce

Pokud se ověření nebo zpracování nezdaří, bude vrácena chybová odpověď s nenulovým ErrorCode a podrobným ErrorText.

Nepodporovaný kanál/možnostNeplatný počet možností průzkumuNeregistrovaný název alfaInterní chyba zpracování

{
  "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čení zpětného volání

Pokud byl v požadavku zadán callback_url, SMSBAT odešle aktualizace stavu doručení jako JSON POST datovou část do vašeho koncového bodu.

Příklad požadavku na zpětné volání

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í zpětného volání

Pole	Typ	Popis
"číslo"	řetězec	Telefonní číslo příjemce.
"čas"	číslo	Časové razítko události v unixových milisekundách.
"stav"	číslo	Zjednodušený stavový identifikátor (viz tabulka stavových kódů).
`podstatu`	číslo	Podrobný identifikátor stavu (viz tabulka kódů dílčích stavů).
`hyber_status`	číslo	Podrobný interní stavový kód SMSBAT (viz tabulka Hyber Status).
`ID_zprávy`	řetězec	ID zprávy SMSBAT (GUID) vygenerované při odeslání.
`extra_id`	řetězec	ID na straně zákazníka uvedené v původní žádosti.
`sent_via`	řetězec	Kanál, který zprávu zpracoval: `viber`, `sms` nebo `rcs`.
`odpovídající_id_šablony`	číslo	Stav shody šablony Viber (pokud existuje).

Mapování stavu

1. Zjednodušený stav (`stav`)

Kód	Význam
"1"	Zpráva přijata nebo doručena.
"2"	Zpráva doručena.
"3"	Chyba zpracování nebo doručení.

2. Podrobný stav („substatus“)

Kód	Význam
"12"	Přijato ke zpracování.
"23"	Doručeno.
"24"	Viděno/čteno.
"35"	Nedoručeno v rámci TTL (vypršelo).
"36"	Chyba doručení.

3. Typ kanálu (`sent_via`)

Kanál	Popis
"viber"	Stav vytvořený kanálem Viber.
`sms`	Stav vytvořený kanálem SMS.
`rcs`	Stav vytvořený kanálem RCS.

4. Podrobný stav SMSBAT (`hyber_status`)

Kód	Kanál	Stav	Substatus	Význam
23033	"viber"	"2"	"23"	Zpráva Viber doručena.
24013	"viber"	"2"	"24"	Zpráva Viber přečtená příjemcem (viděna).
36013	"viber"	"3"	"36"	Vnitřní chyba Viberu.
36023	"viber"	"3"	"36"	Neplatné nebo nedostupné ID služby Viber.
36033	"viber"	"3"	"36"	Neplatná data užitečného zatížení Viber.
36037	"viber"	"3"	"36"	Adresa URL obrázku Viber je příliš dlouhá.
36038	"viber"	"3"	"36"	Neplatná adresa URL obrázku Viber.
36039	"viber"	"3"	"36"	Text Viber je příliš dlouhý.
36044	"viber"	"3"	"36"	Prázdný text Viber.
36053	"viber"	"3"	"36"	Nepodporovaný typ zprávy Viber.
36063	"viber"	"3"	"36"	Neplatné parametry Viber.
36073	"viber"	"3"	"36"	Časový limit poskytovatele Viber.
36083	"viber"	"3"	"36"	Odesílatel Viber je zablokován příjemcem.
36093	"viber"	"3"	"36"	Příjemce není registrován jako uživatel Viber.
36103	"viber"	"3"	"36"	Nebylo nalezeno žádné zařízení Android/iOS s podporou Viber.
36113	"viber"	"3"	"36"	Neoprávněná IP adresa pro odesílání Viber.
36123	"viber"	"3"	"36"	Byla zjištěna duplicitní zpráva Viber.
36143	"viber"	"3"	"36"	Chyba účtování Viber.
36153	"viber"	"3"	"36"	Zpráva je blokována černou listinou platformy.
36163	"viber"	"3"	"36"	Interní chyba zpracování platformy Viber.
36173	"viber"	"3"	"36"	Špatný nebo chybějící štítek Viber.
36183	"viber"	"3"	"36"	Neplatná hodnota Viber TTL.
12011	`sms` / `rcs`	"1"	"12"	SMS/RCS přijímány.
36011	`sms` / `rcs`	"1"	"12"	SMS/RCS na cestě.
23011	`sms` / `rcs`	"2"	"23"	SMS/RCS doručeny.
35015	`sms` / `rcs`	"3"	"35"	Platnost SMS/RCS vypršela (nedoručeno v rámci TTL).
36021	`sms` / `rcs`	"3"	"36"	SMS/RCS zpráva smazána.
36031	`sms` / `rcs`	"3"	"36"	SMS/RCS nelze doručit.
36041	`sms` / `rcs`	"3"	"36"	Neznámý stav doručení SMS/RCS.
36051	`sms` / `rcs`	"3"	"36"	Zpráva SMS/RCS odmítnuta.