GMS API -yhteensopivuus

SMSBAT tukee yhteensopivuuskerrosta GMS API:n kanssa. Tämän avulla voit siirtää olemassa olevat GMS:lle suunnitellut integraatiot suoraan SMSBAT:iin ilman, että sinun tarvitsee muokata viestien reititysskeemoja, hyötykuormarakenteita tai takaisinsoittokuuntelijoita.

Yhteysasetukset

Voit reitittää pyynnöt SMSBAT:n kautta päivittämällä perus-URL-osoitteen ja todennustiedot integraatiossasi:

Perus-URL-osoite: https://restapi.smsbat.com
Päätepiste: POST /api/GMSMessage/send_message
Pyyntömuoto: "sovellus/json".
Todennus: HTTP-perustodennus (käyttää SMSBAT API -tunnuksiasi)

Pyydä parametreja

GMS-yhteensopivuussovellusliittymä hyväksyy JSON-objektin seuraavilla ylätason parametreilla:

Parametri	Tyyppi	Pakollinen	Kuvaus
`puhelinnumero`	merkkijono	Kyllä	Vastaanottajan puhelinnumero kansainvälisessä muodossa (esim. "380501234567").
"tunniste"	merkkijono	Kyllä	Rekisteröity lähettäjän nimi / alfa-nimi.
"kanavat"	joukko	Kyllä	Luettelo kokeiltavista kanavista prioriteettijärjestyksessä. Tuetut arvot: "viber", "sms", "push". Esim. `["viber", "sms"]`.
`kanavan_asetukset`	esine	Kyllä	Kartta, joka sisältää valinnat kullekin aktiiviselle kanavalle (katso alla).
"extra_id"	merkkijono	Ei	Sisäinen asiakaspuolen viestitunnuksesi.
`takaisinsoitto-url`	merkkijono	Ei	Päätepisteen URL-osoite järjestelmässäsi toimitustilan takaisinsoittojen vastaanottamista varten.
`jakokoodi`	merkkijono	Ei	Valinnainen jakokoodin tunniste (oletus on "main").

Kanavaasetusten asetukset

channel_options-objekti sisältää kanavakohtaisia määrityksiä.

Viber-viestiViber tekstiviestien varallaSMS-viestiViber SurveyViber-karuselliPush Message

Käytetään, kun "viber" on luettelossa "kanavat"-taulukossa.

Parametri	Tyyppi	Pakollinen	Kuvaus
"teksti"	merkkijono	Kyllä	Viestin teksti.
`ttl`	kokonaisluku	Kyllä	Elämisaika sekunneissa.
"img"	merkkijono	Ei	Näytettävän kuvan julkinen HTTPS-URL-osoite.
"teksti"	merkkijono	Ei	Painikkeen tekstitunniste.
"toiminta"	merkkijono	Ei	Kohde-URL, kun painiketta napsautetaan.
`kyselyn_vaihtoehdot`	joukko	Ei	Joukko merkkijonoja (2–5 kohdetta) näytettäväksi kyselyvaihtoehtoina.
"carousel_items"	joukko	Ei	Joukko diaobjekteja näytettäväksi Viber-karusellina (katso rakenne välilehdellä).

Viber-pyyntöesimerkki:

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

Ottaa käyttöön Viber-viestit automaattisella tekstiviestillä, jos Viber-toimitus epäonnistuu TTL:n sisällä.

Varapyyntöesimerkki:

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

Käytetään, kun "sms" on luettelossa "kanavat"-taulukossa.

Parametri	Tyyppi	Pakollinen	Kuvaus
"teksti"	merkkijono	Kyllä	Viestin teksti.
"alfa_nimi"	merkkijono	Kyllä	Lähettäjän alfa-nimi.
`ttl`	kokonaisluku	Kyllä	Elämisaika sekunneissa.
`ctr`	boolen	Ei	Ota napsautussuhteen klikkausseuranta käyttöön tekstilinkkeissä ("true"/"false").

Esimerkki tekstiviestipyynnöstä:

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

Käytetään Viber-kyselyjen ja kyselyjen luomiseen.

Varoitus

Viber-kyselyn määrityksissä on oltava 2–5 vaihtoehtoa kyselyn_vaihtoehdot-kohdassa.

Esimerkki kyselystä:

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

Käytetään pyyhkäisevien diakuvakorttien lähettämiseen. Jokainen dia tukee kuvaa, otsikkoa ja painikkeita.

Karusellipyyntöesimerkki:

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

Käytetään, kun "push" on listattu "channels"-taulukossa.

Parametri	Tyyppi	Pakollinen	Kuvaus
`title`	merkkijono	Kyllä	Push-ilmoituksen otsikkoteksti.
"teksti"	merkkijono	Kyllä	Viestin teksti.
`ttl`	kokonaisluku	Kyllä	Elämisaika sekunneissa.
"img"	merkkijono	Ei	Näytettävän kuvan julkinen HTTPS-URL-osoite.
"teksti"	merkkijono	Ei	Painikkeen tekstitunniste.
"toiminta"	merkkijono	Ei	Kohde-URL, kun painiketta napsautetaan.
`ctr`	boolen	Ei	Ota napsautusten seuranta käyttöön.

Esimerkki push-pyynnöstä:

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

Vastausmuoto

Päätepiste palauttaa vastaukset JSON-muodossa HTTP 200 OK -tilakoodilla.

Onnistunut vastaus

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

Virhevastaukset

Jos vahvistus tai käsittely epäonnistuu, palautetaan virhevastaus, jossa on ei-nolla "ErrorCode" ja yksityiskohtainen "ErrorText".

Ei tuettu kanava/vaihtoehtoVirheellinen kyselyvaihtoehtojen määräRekisteröimätön alfanimiSisäinen käsittelyvirhe

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

Takaisinsoittojen toimitusmuoto

Jos callback_url määritettiin pyynnössä, SMSBAT lähettää toimituksen tilapäivitykset JSON POST -hyötykuormana päätepisteellesi.

Takaisinsoittopyynnön esimerkki

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
}

Takaisinsoittokenttien kuvaus

Kenttä	Tyyppi	Kuvaus
"numero"	merkkijono	Vastaanottajan puhelinnumero.
"aika"	numero	Tapahtuman aikaleima Unix millisekunteina.
"tila"	numero	Yksinkertaistettu tilatunniste (katso Tilakooditaulukko).
"alitila"	numero	Yksityiskohtainen tilatunniste (katso alitilakooditaulukko).
`hyber_status`	numero	Yksityiskohtainen SMSBAT:n sisäinen tilakoodi (katso Hyber-tilataulukko).
`message_id`	merkkijono	SMSBAT-viestitunnus (GUID) luotu lähetyksen yhteydessä.
"extra_id"	merkkijono	Alkuperäisessä pyynnössä oleva asiakaspuolen tunnus.
"lähetetty"	merkkijono	Kanava, joka käsitteli viestin: "viber", "sms" tai "rcs".
`matching_template_id`	numero	Viber-mallin vastaavuuden tila (tarvittaessa).

Tilakartoitukset

1. Yksinkertaistettu tila (`status`)

Koodi	Merkitys
"1"	Viesti hyväksytty tai toimitettu.
"2"	Viesti toimitettu.
"3"	Käsittely- tai toimitusvirhe.

2. Yksityiskohtainen tila (`substatus`)

Koodi	Merkitys
"12"	Hyväksytty käsiteltäväksi.
"23"	Toimitettu.
"24"	Nähty/luettu.
"35"	Ei toimitettu TTL:n sisällä (vanhentunut).
"36"	Toimitusvirhe.

3. Kanavan tyyppi (`sent_via`)

Kanava	Kuvaus
"viber"	Viber-kanavan tuottama tila.
`sms`	SMS-kanavan tuottama tila.
"rcs"	RCS-kanavan tuottama tila.

4. Yksityiskohtainen SMSBAT-tila (`hyber_status`)

Koodi	Kanava	Tila	Alatila	Merkitys
23033	"viber"	"2"	"23"	Viber-viesti toimitettu.
24013	"viber"	"2"	"24"	Vastaanottajan lukema Viber-viesti (nähty).
36013	"viber"	"3"	"36"	Viberin sisäinen virhe.
36023	"viber"	"3"	"36"	Virheellinen tai ei saatavilla Viber-palvelutunnus.
36033	"viber"	"3"	"36"	Virheelliset Viber-hyötykuormatiedot.
36037	"viber"	"3"	"36"	Viber-kuvan URL-osoite liian pitkä.
36038	"viber"	"3"	"36"	Virheellinen Viber-kuvan URL-osoite.
36039	"viber"	"3"	"36"	Viber-teksti liian pitkä.
36044	"viber"	"3"	"36"	Tyhjä Viber-teksti.
36053	"viber"	"3"	"36"	Viber-viestityyppiä ei tueta.
36063	"viber"	"3"	"36"	Virheelliset Viber-parametrit.
36073	"viber"	"3"	"36"	Viber-palveluntarjoajan aikakatkaisu.
36083	"viber"	"3"	"36"	Vastaanottaja on estänyt Viber-lähettäjän.
36093	"viber"	"3"	"36"	Vastaanottaja ei ole rekisteröitynyt Viber-käyttäjäksi.
36103	"viber"	"3"	"36"	Viber-tuella varustettua Android/iOS-laitetta ei löytynyt.
36113	"viber"	"3"	"36"	Luvaton IP-osoite Viber-lähetystä varten.
36123	"viber"	"3"	"36"	Viber-viestin kaksoiskappale havaittu.
36143	"viber"	"3"	"36"	Viber laskutusvirhe.
36153	"viber"	"3"	"36"	Viesti on estetty alustan mustalla listalla.
36163	"viber"	"3"	"36"	Viber-alustan sisäinen käsittelyvirhe.
36173	"viber"	"3"	"36"	Väärä tai puuttuva Viber-tarra.
36183	"viber"	"3"	"36"	Virheellinen Viber TTL -arvo.
12011	"sms" / "rcs"	"1"	"12"	SMS/RCS hyväksytty.
36011	"sms" / "rcs"	"1"	"12"	SMS/RCS matkalla.
23011	"sms" / "rcs"	"2"	"23"	SMS/RCS toimitettu.
35015	"sms" / "rcs"	"3"	"35"	SMS/RCS vanhentunut (ei toimitettu TTL:n sisällä).
36021	"sms" / "rcs"	"3"	"36"	SMS/RCS-viesti poistettu.
36031	"sms" / "rcs"	"3"	"36"	SMS/RCS ei toimiteta.
36041	"sms" / "rcs"	"3"	"36"	Tuntematon SMS/RCS-toimituksen tila.
36051	"sms" / "rcs"	"3"	"36"	SMS/RCS-viesti hylätty.