GMS API kompatibilnost

SMSBAT podržava sloj kompatibilnosti s GMS API. To vam omogućuje migriranje vaših postojećih integracija dizajniranih za GMS izravno na SMSBAT bez potrebe za izmjenom shema usmjeravanja poruka, struktura nosivosti ili slušatelja povratnih poziva.

Postavke veze

Za usmjeravanje zahtjeva putem SMSBAT-a ažurirajte osnovni URL i vjerodajnice za provjeru autentičnosti u svojoj integraciji:

Osnovni URL: https://restapi.smsbat.com
Krajnja točka: POST /api/GMSMessage/send_message
Format zahtjeva: application/json
Provjera autentičnosti: HTTP osnovna provjera autentičnosti (koristi vaše SMSBAT API vjerodajnice)

Parametri zahtjeva

GMS kompatibilni API prihvaća JSON objekt sa sljedećim parametrima najviše razine:

Parametar	Upišite	Obavezno	Opis
`telefonski_broj`	niz	Da	Telefonski broj primatelja u međunarodnom formatu (npr. `380501234567`).
`oznaka`	niz	Da	Ime registriranog pošiljatelja / alfa ime.
`kanali`	niz	Da	Popis kanala za isprobavanje, po prioritetu. Podržane vrijednosti: `viber`, `sms`, `push`. Npr., `["viber", "sms"]`.
`opcije_kanala`	objekt	Da	Karta koja sadrži opcije za svaki aktivni kanal (vidi dolje).
`dodatni_id`	niz	Ne	Vaš interni ID poruke na strani korisnika.
`url_povratnog_poziva`	niz	Ne	URL krajnje točke na vašem sustavu za primanje povratnih poziva o statusu isporuke.
`šifra_odjeljka`	niz	Ne	Neobavezni identifikator šifre podjele (zadano je `main`).

Postavke opcija kanala

Objekt channel_options sadrži konfiguracije specifične za kanal.

Viber porukaViber s povratnim SMS-omSMS porukaViber AnketaViber vrtuljakPush poruka

Koristi se kada je viber naveden u nizu channels.

Parametar	Upišite	Obavezno	Opis
`tekst`	niz	Da	Tekst tijela poruke.
`ttl`	cijeli broj	Da	Vrijeme do života u sekundama.
`img`	niz	Ne	Javni HTTPS URL slike za prikaz.
`naslov`	niz	Ne	Tekstna oznaka gumba.
`akcija`	niz	Ne	Odredišni URL kada se klikne na gumb.
`opcije_ankete`	niz	Ne	Niz nizova (2 do 5 stavki) za prikaz kao opcije ankete.
`predmeti_vrtuljka`	niz	Ne	Niz objekata slajdova za prikaz kao Viber vrtuljak (pogledajte strukturu na kartici).

Primjer Viber zahtjeva:

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

Omogućuje Viber razmjenu poruka s automatskim povratnim SMS-om ako Viber isporuka ne uspije unutar TTL-a.

Primjer zamjenskog zahtjeva:

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

Koristi se kada je sms naveden u nizu channels.

Parametar	Upišite	Obavezno	Opis
`tekst`	niz	Da	Tekst tijela poruke.
`alfa_ime`	niz	Da	Alfa ime pošiljatelja.
`ttl`	cijeli broj	Da	Vrijeme do života u sekundama.
`ctr`	Booleov	Ne	Omogućite CTR praćenje klikova na poveznicama u tekstu (`true`/`false`).

Primjer SMS zahtjeva:

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

Koristi se za izradu Viber anketa i anketa.

Upozorenje

Konfiguracija Viber ankete mora imati između 2 i 5 opcija unutar survey_options.

Primjer zahtjeva za anketu:

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

Koristi se za slanje klizajućih slikovnih kartica. Svaki slajd podržava sliku, naslov i gumbe.

Primjer zahtjeva za vrtuljak:

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

Koristi se kada je "push" naveden u nizu "channels".

Parametar	Upišite	Obavezno	Opis
`naslov`	niz	Da	Tekst naslova push obavijesti.
`tekst`	niz	Da	Tekst tijela poruke.
`ttl`	cijeli broj	Da	Vrijeme do života u sekundama.
`img`	niz	Ne	Javni HTTPS URL slike za prikaz.
`naslov`	niz	Ne	Tekstna oznaka gumba.
`akcija`	niz	Ne	Odredišni URL kada se klikne na gumb.
`ctr`	Booleov	Ne	Omogući praćenje klikova.

Primjer Push zahtjeva:

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

Format odgovora

Krajnja točka vraća odgovore u JSON formatu sa statusnim kodom HTTP 200 OK.

Uspješan odgovor

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

Odgovori na pogreške

Ako provjera valjanosti ili obrada ne uspije, vratit će se odgovor o pogrešci s ErrorCode koji nije null i detaljnim ErrorText.

Nepodržani kanal/opcijaNevažeći broj opcija anketeNeregistrirano alfa imeInterna pogreška obrade

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

Format isporuke povratnog poziva

Ako je callback_url naveden u zahtjevu, SMSBAT šalje ažuriranja statusa isporuke kao JSON POST korisni teret vašoj krajnjoj točki.

Primjer zahtjeva za povratni poziv

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
}

Opis polja povratnog poziva

Polje	Upišite	Opis
`broj`	niz	Broj telefona primatelja.
`vrijeme`	broj	Vremenska oznaka događaja u Unix milisekundama.
`status`	broj	Pojednostavljeni identifikator statusa (pogledajte tablicu statusnih kodova).
`podstatus`	broj	Detaljan identifikator statusa (pogledajte tablicu kodova podstatusa).
`hiber_status`	broj	Detaljan SMSBAT interni statusni kod (pogledajte tablicu statusa Hyber).
`id_poruke`	niz	SMSBAT ID poruke (GUID) generiran pri slanju.
`dodatni_id`	niz	ID na strani korisnika naveden je u izvornom zahtjevu.
`poslano_preko`	niz	Kanal koji je obradio poruku: `viber`, `sms` ili `rcs`.
`podudarni_id_predloška`	broj	Status podudaranja Viber predloška (gdje je primjenjivo).

Preslikavanja statusa

1. Pojednostavljeni status (`status`)

Kod	Značenje
`1`	Poruka je prihvaćena ili se isporučuje.
`2`	Poruka isporučena.
`3`	Greška u obradi ili isporuci.

2. Detaljan status (`podstatus`)

Kod	Značenje
`12`	Prihvaćeno za obradu.
`23`	Isporučeno.
`24`	Viđeno/pročitano.
`35`	Nije isporučeno unutar TTL-a (isteklo).
`36`	Greška pri isporuci.

3. Vrsta kanala (`sent_via`)

Kanal	Opis
`viber`	Status proizveden od Viber kanala.
`sms`	Status proizveden SMS kanalom.
`rcs`	Status koji proizvodi RCS kanal.

4. Detaljan SMSBAT status (`hyber_status`)

Kod	Kanal	Status	Podstatus	Značenje
23033	`viber`	`2`	`23`	Viber poruka isporučena.
24013	`viber`	`2`	`24`	Viber poruka pročitana od strane primatelja (Seen).
36013	`viber`	`3`	`36`	Interna greška Vibera.
36023	`viber`	`3`	`36`	Nevažeći ili nedostupni ID usluge Viber.
36033	`viber`	`3`	`36`	Nevažeći Viber korisni podaci.
36037	`viber`	`3`	`36`	URL Viber slike je predug.
36038	`viber`	`3`	`36`	Nevažeći URL Viber slike.
36039	`viber`	`3`	`36`	Viber poruka je preduga.
36044	`viber`	`3`	`36`	Prazan Viber tekst.
36053	`viber`	`3`	`36`	Nepodržana vrsta Viber poruke.
36063	`viber`	`3`	`36`	Nevažeći parametri Vibera.
36073	`viber`	`3`	`36`	Istek vremena pružatelja Vibera.
36083	`viber`	`3`	`36`	Viber pošiljatelja blokirao je primatelj.
36093	`viber`	`3`	`36`	Primatelj nije registriran kao Viber korisnik.
36103	`viber`	`3`	`36`	Nije pronađen nijedan Android/iOS uređaj s podrškom za Viber.
36113	`viber`	`3`	`36`	Neautorizirana IP adresa za slanje putem Vibera.
36123	`viber`	`3`	`36`	Otkrivena dupla Viber poruka.
36143	`viber`	`3`	`36`	Greška pri naplati Vibera.
36153	`viber`	`3`	`36`	Poruka je blokirana crnom listom platforme.
36163	`viber`	`3`	`36`	Interna greška obrade platforme Viber.
36173	`viber`	`3`	`36`	Viber oznaka je pogrešna ili nedostaje.
36183	`viber`	`3`	`36`	Nevažeća Viber TTL vrijednost.
12011	`sms` / `rcs`	`1`	`12`	SMS/RCS prihvaćen.
36011	`sms` / `rcs`	`1`	`12`	SMS/RCS na putu.
23011	`sms` / `rcs`	`2`	`23`	SMS/RCS isporučen.
35015	`sms` / `rcs`	`3`	`35`	SMS/RCS je istekao (nije dostavljen unutar TTL-a).
36021	`sms` / `rcs`	`3`	`36`	SMS/RCS poruka izbrisana.
36031	`sms` / `rcs`	`3`	`36`	SMS/RCS nije moguće isporučiti.
36041	`sms` / `rcs`	`3`	`36`	Nepoznat status isporuke SMS-a/RCS-a.
36051	`sms` / `rcs`	`3`	`36`	SMS/RCS poruka odbijena.