Kompatibilnost GMS API-ja

SMSBAT podržava sloj kompatibilnosti sa GMS API. Ovo vam omogućava da migrirate svoje postojeće integracije dizajnirane za GMS direktno na SMSBAT bez potrebe za izmjenom vaših šema rutiranja poruka, strukture korisnog opterećenja ili slušatelja povratnog poziva.

Postavke veze

Za usmjeravanje zahtjeva putem SMSBAT-a, ažurirajte osnovni URL i vjerodajnice za autentifikaciju u svojoj integraciji:

Osnovni URL: https://restapi.smsbat.com
Krajnja tačka: POST /api/GMSMessage/send_message
Format zahtjeva: application/json
Authentication: HTTP Basic Authentication (koristi vaše SMSBAT API vjerodajnice)

Parametri zahtjeva

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

Parametar	Vrsta	Obavezno	Opis
`telefonski broj`	string	Da	Telefonski broj primaoca u međunarodnom formatu (npr. `380501234567`).
`oznaka`	string	Da	Registrirano ime pošiljaoca / alfa ime.
`kanali`	niz	Da	Lista kanala koje treba isprobati, po prioritetu. Podržane vrijednosti: `viber`, `sms`, `push`. Npr., `["viber", "sms"]`.
`channel_options`	objekt	Da	Mapa koja sadrži opcije za svaki aktivni kanal (pogledajte ispod).
`extra_id`	string	Ne	Vaš interni ID poruke na strani korisnika.
`callback_url`	string	Ne	URL krajnje tačke na vašem sistemu za primanje povratnih poziva statusa isporuke.
`šifra_podjela`	string	Ne	Opcijski identifikator koda podjele (zadano na `glavni`).

Postavke kanala

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

Viber porukaViber sa SMS FallbackSMS porukaViber anketaViber vrtuljakPush poruka

Koristi se kada je viber naveden u nizu channels.

Parametar	Vrsta	Obavezno	Opis
`tekst`	string	Da	Tekst tijela poruke.
`ttl`	cijeli broj	Da	Vrijeme za život u sekundama.
`img`	string	Ne	Javni HTTPS URL slike za prikaz.
`naslov`	string	Ne	Oznaka teksta dugmeta.
`akcija`	string	Ne	Odredišni URL kada se klikne na dugme.
`opcije_ankete`	niz	Ne	Niz nizova (2 do 5 stavki) za prikaz kao opcije ankete.
`carousel_items`	niz	Ne	Niz objekata slajda 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ćava razmjenu Viber poruka s automatskim zamjenskim 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	Vrsta	Obavezno	Opis
`tekst`	string	Da	Tekst tijela poruke.
`alpha_name`	string	Da	Alfa ime pošiljaoca.
`ttl`	cijeli broj	Da	Vrijeme za život u sekundama.
`ctr`	boolean	Ne	Omogućite CTR praćenje klikova na linkovima u tekstu (`tačno`/`netačno`).

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 kreiranje Viber anketa i anketa.

Upozorenje

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

Primjer zahtjeva za anketiranje:

{
  "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 slajd kartica sa slikama koje se mogu prevlačiti. Svaki slajd podržava sliku, naslov i dugmad.

Primjer zahtjeva za vrtuljkom:

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	Vrsta	Obavezno	Opis
`naslov`	string	Da	Tekst naslova push obavijesti.
`tekst`	string	Da	Tekst tijela poruke.
`ttl`	cijeli broj	Da	Vrijeme za život u sekundama.
`img`	string	Ne	Javni HTTPS URL slike za prikaz.
`naslov`	string	Ne	Oznaka teksta dugmeta.
`akcija`	string	Ne	Odredišni URL kada se klikne na dugme.
`ctr`	boolean	Ne	Omogućite 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 tač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 greške

Ako provjera valjanosti ili obrada ne uspije, bit će vraćen odgovor na grešku s ErrorCode koji nije nulti i detaljnim ErrorText.

Nepodržani kanal/opcijaNevažeći broj opcija anketeNeregistrirano alfa imeInterna greška u obradi

{
  "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 tački.

Primjer zahtjeva za povratnim pozivom

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	Vrsta	Opis
`broj`	string	Broj telefona primaoca.
`vrijeme`	broj	Vremenska oznaka događaja u Unix milisekundama.
`status`	broj	Pojednostavljeni identifikator statusa (pogledajte tabelu statusnih kodova).
`podstatus`	broj	Detaljni identifikator statusa (pogledajte tabelu kodova podstatusa).
`hyber_status`	broj	Detaljan SMSBAT interni statusni kod (pogledajte tabelu Hyber statusa).
`message_id`	string	ID SMSBAT poruke (GUID) generiran prilikom slanja.
`extra_id`	string	ID na strani korisnika naveden u originalnom zahtjevu.
`sent_via`	string	Kanal koji je obradio poruku: `viber`, `sms` ili `rcs`.
`matching_template_id`	broj	Status podudaranja Viber šablona (gdje je primjenjivo).

Mapiranja statusa

1. Pojednostavljeni status (`status`)

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

2. Detaljan status (`podstatus`)

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

3. Vrsta kanala (`sent_via`)

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

4. Detaljan SMSBAT status (`hyber_status`)

Šifra	Kanal	Status	Podstatus	Značenje
23033	`viber`	`2`	`23`	Viber poruka dostavljena.
24013	`viber`	`2`	`24`	Viber poruku je pročitao primalac (Viđeno).
36013	`viber`	`3`	`36`	Viber interna greška.
36023	`viber`	`3`	`36`	Nevažeći ili nedostupni ID usluge Viber.
36033	`viber`	`3`	`36`	Nevažeći podaci o korisnom učitavanju Vibera.
36037	`viber`	`3`	`36`	URL slike Vibera je predugačak.
36038	`viber`	`3`	`36`	Nevažeći URL Viber slike.
36039	`viber`	`3`	`36`	Viber tekst je predugačak.
36044	`viber`	`3`	`36`	Prazan Viber tekst.
36053	`viber`	`3`	`36`	Nepodržana vrsta Viber poruke.
36063	`viber`	`3`	`36`	Nevažeći Viber parametri.
36073	`viber`	`3`	`36`	Vremensko ograničenje Viber provajdera.
36083	`viber`	`3`	`36`	Viber pošiljalac blokiran od strane primaoca.
36093	`viber`	`3`	`36`	Primalac nije registrovan kao Viber korisnik.
36103	`viber`	`3`	`36`	Nije pronađen nijedan Android/iOS uređaj sa podrškom za Viber.
36113	`viber`	`3`	`36`	Neovlaštena IP adresa za slanje putem Vibera.
36123	`viber`	`3`	`36`	Otkrivena je duplirana Viber poruka.
36143	`viber`	`3`	`36`	Viber greška u naplati.
36153	`viber`	`3`	`36`	Poruka blokirana crnom listom platforme.
36163	`viber`	`3`	`36`	Greška interne obrade Viber platforme.
36173	`viber`	`3`	`36`	Pogrešna ili nedostaje Viber oznaka.
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 isporučen unutar TTL-a).
36021	`sms` / `rcs`	`3`	`36`	SMS/RCS poruka je izbrisana.
36031	`sms` / `rcs`	`3`	`36`	SMS/RCS se ne može isporučiti.
36041	`sms` / `rcs`	`3`	`36`	Nepoznat status isporuke SMS/RCS.
36051	`sms` / `rcs`	`3`	`36`	SMS/RCS poruka je odbijena.