Help Center Združljivost GMS API

Združljivost GMS API

SMSBAT podpira združljivostno plast z GMS API. To vam omogoča, da svoje obstoječe integracije, zasnovane za GMS, preselite neposredno v SMSBAT, ne da bi morali spreminjati sheme usmerjanja sporočil, strukture koristnega tovora ali poslušalce povratnih klicev.

Nastavitve povezave

Če želite zahteve usmeriti prek SMSBAT, posodobite osnovni URL in poverilnice za preverjanje pristnosti v svoji integraciji:

Osnovni URL: https://restapi.smsbat.com
Končna točka: POST /api/GMSMessage/send_message
Oblika zahteve: application/json
Preverjanje pristnosti: Osnovno preverjanje pristnosti HTTP (uporablja vaše poverilnice API SMSBAT)

Parametri zahteve

API združljivosti GMS sprejema objekt JSON z naslednjimi parametri najvišje ravni:

Parameter	Vrsta	Zahtevano	Opis
`telefonska_številka`	niz	Da	Telefonska številka prejemnika v mednarodni obliki (npr. »380501234567«).
`oznaka`	niz	Da	Registrirano ime pošiljatelja/alfa ime.
`kanali`	niz	Da	Seznam kanalov, ki jih želite preizkusiti, po prednostnem vrstnem redu. Podprte vrednosti: `viber`, `sms`, `push`. Npr. `["viber", "sms"]`.
`možnosti_kanala`	predmet	Da	Zemljevid z možnostmi za vsak aktivni kanal (glejte spodaj).
`dodatni_id`	niz	Ne	Vaš interni ID sporočila na strani stranke.
`url_za_povratni klic`	niz	Ne	URL končne točke v vašem sistemu za prejemanje povratnih klicev o stanju dostave.
`koda_oddelka`	niz	Ne	Izbirni identifikator kode delitve (privzeto je `main`).

Nastavitve možnosti kanala

Objekt channel_options vsebuje konfiguracije, specifične za kanal.

Uporablja se, ko je viber naveden v matriki channels.

Parameter	Vrsta	Zahtevano	Opis
`besedilo`	niz	Da	Besedilo telesa sporočila.
`ttl`	celo število	Da	Čas do življenja v sekundah.
`img`	niz	Ne	Javni HTTPS URL slike za prikaz.
`napis`	niz	Ne	Besedilna oznaka gumba.
`akcija`	niz	Ne	Ciljni URL ob kliku gumba.
`možnosti_ankete`	niz	Ne	Niz nizov (2 do 5 elementov) za prikaz kot možnosti ankete.
`predmeti_vrtiljaka`	niz	Ne	Niz predmetov diapozitivov za prikaz kot vrtiljak Viber (glejte strukturo v zavihku).

Primer zahteve za 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"
    }
  }
}

Omogoča sporočanje Viber s samodejnim nadomestnim SMS-om, če dostava Viber ne uspe znotraj TTL.

Primer nadomestne zahteve:

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

Uporablja se, ko je sms naveden v matriki channels.

Parameter	Vrsta	Zahtevano	Opis
`besedilo`	niz	Da	Besedilo telesa sporočila.
`alfa_ime`	niz	Da	Alfa ime pošiljatelja.
`ttl`	celo število	Da	Čas do življenja v sekundah.
`ctr`	logično	Ne	Omogoči sledenje klikov CTR na povezavah v besedilu (`true`/`false`).

Primer SMS zahteve:

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

Uporablja se za ustvarjanje Viber anket in anket.

Warning

Konfiguracija ankete Viber mora imeti med 2 in 5 možnostmi znotraj survey_options.

Primer zahteve za anketo:

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

Uporablja se za pošiljanje drsnih kartic s slikami. Vsak diapozitiv podpira sliko, naslov in gumbe.

Primer zahteve za vrtiljak:

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

Uporablja se, ko je push naveden v matriki channels.

Parameter	Vrsta	Zahtevano	Opis
`naslov`	niz	Da	Besedilo naslova potisnega obvestila.
`besedilo`	niz	Da	Besedilo telesa sporočila.
`ttl`	celo število	Da	Čas do življenja v sekundah.
`img`	niz	Ne	Javni HTTPS URL slike za prikaz.
`napis`	niz	Ne	Besedilna oznaka gumba.
`akcija`	niz	Ne	Ciljni URL ob kliku gumba.
`ctr`	logično	Ne	Omogoči sledenje klikom.

Primer potisne zahteve:

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

Oblika odgovora

Končna točka vrne odgovore v formatu JSON s statusno kodo »HTTP 200 OK«.

Uspešen odgovor

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

Odgovori na napake

Če preverjanje ali obdelava ne uspe, bo vrnjen odgovor o napaki z neničelno ErrorCode in podrobnim ErrorText.

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

Oblika povratnega klica

Če je bil v zahtevi naveden callback_url, SMSBAT pošlje posodobitve statusa dostave kot koristni tovor JSON POST vaši končni točki.

Primer zahteve za povratni klic

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 polj povratnega klica

Polje	Vrsta	Opis
`številka`	niz	Telefonska številka prejemnika.
`čas`	številka	Časovni žig dogodka v milisekundah sistema Unix.
`stanje`	številka	Poenostavljen identifikator statusa (glejte tabelo statusnih kod).
`podstanje`	številka	Podroben identifikator statusa (glejte tabelo kod podstatusa).
`hiber_status`	številka	Podrobna interna statusna koda SMSBAT (glejte tabelo stanja Hyber).
`id_sporočila`	niz	ID sporočila SMSBAT (GUID), ustvarjen ob pošiljanju.
`dodatni_id`	niz	ID na strani stranke, naveden v prvotni zahtevi.
`poslano_prek`	niz	Kanal, ki je obdelal sporočilo: `viber`, `sms` ali `rcs`.
`id_ujemajoče se_predloge`	številka	Status ujemanja predloge Viber (kjer je primerno).

Preslikave stanja

1. Poenostavljeno stanje (`status`)

Koda	Pomen
`1`	Sporočilo sprejeto ali dostavljeno.
`2`	Sporočilo dostavljeno.
`3`	Napaka pri obdelavi ali dostavi.

2. Podrobno stanje (`podstanje`)

Koda	Pomen
`12`	Sprejeto v obdelavo.
`23`	Dostavljeno.
`24`	Videno/prebrano.
`35`	Ni dostavljeno v TTL (poteklo).
`36`	Napaka pri dostavi.

3. Vrsta kanala (`sent_via`)

Kanal	Opis
`viber`	Status, ki ga ustvari Viber kanal.
`sms`	Status, ki ga ustvari SMS kanal.
`rcs`	Stanje, ki ga je ustvaril kanal RCS.

4. Podrobno stanje SMSBAT (`hyber_status`)

Koda	Kanal	Stanje	Podstatus	Pomen
23033	`viber`	`2`	`23`	Sporočilo Viber dostavljeno.
24013	`viber`	`2`	`24`	Sporočilo Viber prebere prejemnik (Seen).
36013	`viber`	`3`	`36`	Viber notranja napaka.
36023	`viber`	`3`	`36`	Neveljaven ali nedosegljiv ID storitve Viber.
36033	`viber`	`3`	`36`	Neveljavni podatki o obremenitvi Viber.
36037	`viber`	`3`	`36`	URL slike Viber je predolg.
36038	`viber`	`3`	`36`	Neveljaven URL slike Viber.
36039	`viber`	`3`	`36`	Besedilo Viber je predolgo.
36044	`viber`	`3`	`36`	Prazno besedilo Viber.
36053	`viber`	`3`	`36`	Nepodprta vrsta sporočila Viber.
36063	`viber`	`3`	`36`	Neveljavni parametri Viber.
36073	`viber`	`3`	`36`	Časovna omejitev ponudnika Viber.
36083	`viber`	`3`	`36`	Viber pošiljatelja blokira prejemnik.
36093	`viber`	`3`	`36`	Prejemnik ni registriran kot uporabnik Viberja.
36103	`viber`	`3`	`36`	Najdena ni bila nobena naprava Android/iOS s podporo za Viber.
36113	`viber`	`3`	`36`	Nepooblaščen naslov IP za pošiljanje Viber.
36123	`viber`	`3`	`36`	Zaznano podvojeno sporočilo Viber.
36143	`viber`	`3`	`36`	Napaka pri obračunavanju Viberja.
36153	`viber`	`3`	`36`	Sporočilo blokira črni seznam platforme.
36163	`viber`	`3`	`36`	Notranja napaka pri obdelavi platforme Viber.
36173	`viber`	`3`	`36`	Napačna ali manjkajoča oznaka Viber.
36183	`viber`	`3`	`36`	Neveljavna vrednost Viber TTL.
12011	`sms` / `rcs`	`1`	`12`	SMS/RCS sprejet.
36011	`sms` / `rcs`	`1`	`12`	SMS/RCS na poti.
23011	`sms` / `rcs`	`2`	`23`	SMS/RCS dostavljen.
35015	`sms` / `rcs`	`3`	`35`	SMS/RCS je potekel (ni dostavljen v TTL).
36021	`sms` / `rcs`	`3`	`36`	Sporočilo SMS/RCS izbrisano.
36031	`sms` / `rcs`	`3`	`36`	SMS/RCS ni mogoče dostaviti.
36041	`sms` / `rcs`	`3`	`36`	Neznano stanje dostave SMS/RCS.
36051	`sms` / `rcs`	`3`	`36`	Sporočilo SMS/RCS zavrnjeno.

Search Results

Združljivost GMS API

Nastavitve povezave

Parametri zahteve

Nastavitve možnosti kanala

Oblika odgovora

Uspešen odgovor

Odgovori na napake

Oblika povratnega klica

Primer zahteve za povratni klic

Opis polj povratnega klica

Preslikave stanja

1. Poenostavljeno stanje (status)

2. Podrobno stanje (podstanje)

3. Vrsta kanala (sent_via)

4. Podrobno stanje SMSBAT (hyber_status)

1. Poenostavljeno stanje (`status`)

2. Podrobno stanje (`podstanje`)

3. Vrsta kanala (`sent_via`)

4. Podrobno stanje SMSBAT (`hyber_status`)