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.

Sporočilo ViberViber z nadomestnim SMS-omSporočilo SMSViber anketaViber CarouselPotisno sporočilo

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.

Opozorilo

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:

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

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.

Nepodprt kanal/možnostNeveljavno število možnosti anketeNeregistrirano alfa imeNotranja napaka pri obdelavi

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