Messagio API -yhteensopivuus

SMSBAT tukee yhteensopivuuskerrosta Messagio API:n kanssa. Tämän avulla voit siirtää olemassa olevat Messagiolle suunnitellut Viber-integraatiot suoraan SMSBAT:iin ilman, että sinun tarvitsee kirjoittaa uudelleen hyötykuormarakennetta tai muuttaa integrointilogiikkaa.

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/SendMessage
Pyyntömuoto: application/x-www-form-urlencoded (lomaketiedot)

Todennus ja tunnistetiedot

Pyynnöt todennetaan parametreilla, jotka lähetetään suoraan pyynnön runkolomakkeen tiedoissa:

Parametri	Tyyppi	Pakollinen	Kuvaus
"käyttäjä"	merkkijono	Kyllä	SMSBAT-tilisi kirjautumistunnus tai käyttäjätunnus.
"merkki"	merkkijono	Kyllä	API-salaisuus tai allekirjoitus, joka on rekisteröity lähettäjän nimelle.
"alkaen"	merkkijono	Kyllä	Rekisteröidyn lähettäjän alfa-nimi.
"lähetystapa"	merkkijono	Kyllä	Kanavan tyyppi. Käytä "viber" tavallisille Viber Business -viesteille tai "viber_otp" Viber OTP -malleille.
`puhelin`	merkkijono	Kyllä	Vastaanottajan puhelinnumero kansainvälisessä muodossa (esim. "380501234567").

Viber-viestityypit

Valitse alta välilehti nähdäksesi tietyt parametrit ja pyytääksesi hyötykuormia eri Viber-viestirakenteille:

TekstiviestiTeksti + painikeKuvaviestiTeksti + kuva + painikeVideoviestiOTP-malli

Lähettää yksinkertaisen tekstiviestin.

Lisäparametrit:

Parametri	Tyyppi	Pakollinen	Kuvaus
`txt`	merkkijono	Kyllä	Viestin teksti.

Pyydä hyötykuorma esimerkki:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Hello+from+SMSBAT%21

Lähettää tekstiviestin, jossa on interaktiivinen toimintakehotuspainike.

Lisäparametrit:

Parametri	Tyyppi	Pakollinen	Kuvaus
`txt`	merkkijono	Kyllä	Viestin teksti.
`button_text`	merkkijono	Kyllä	Painikkeessa näkyvä teksti.
`painike_linkki`	merkkijono	Kyllä	Kohde-URL, kun painiketta napsautetaan.

Pyydä hyötykuorma esimerkki:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Check+our+latest+offers%21&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Lähettää julkisen kuvatiedoston.

Lisäparametrit:

Parametri	Tyyppi	Pakollinen	Kuvaus
"image_link"	merkkijono	Kyllä	Kuvan julkinen HTTPS-URL-osoite.
`txt`	merkkijono	Ei	Valinnainen kuvateksti, joka näytetään kuvan alla.

Pyydä hyötykuorma esimerkki:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png

Lähettää rich-kortin, joka sisältää tekstiä, kuvan ja painikkeen.

Lisäparametrit:

Parametri	Tyyppi	Pakollinen	Kuvaus
`txt`	merkkijono	Kyllä	Kuvateksti.
"image_link"	merkkijono	Kyllä	Kuvan julkinen HTTPS-URL-osoite.
`button_text`	merkkijono	Kyllä	Painikkeessa näkyvä teksti.
`painike_linkki`	merkkijono	Kyllä	Kohde-URL, kun painiketta napsautetaan.

Pyydä hyötykuorma esimerkki:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Hot+deals+inside%21&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Lähettää videotiedoston valinnaisen tekstin ja toimintopainikkeiden kanssa.

Lisäparametrit:

Parametri	Tyyppi	Pakollinen	Kuvaus
`video.url`	merkkijono	Kyllä	Videotiedoston julkinen HTTPS-URL-osoite.
`video.thumbnail`	merkkijono	Kyllä	Videon esikatselukuvan julkinen HTTPS-URL-osoite.
`video.size_mb`	kokonaisluku	Kyllä	Likimääräinen videotiedoston koko megatavuina.
`video.duration_sec`	kokonaisluku	Kyllä	Videon kesto sekunneissa.
`txt`	merkkijono	Ei	Valinnainen kuvausteksti.
`button_text`	merkkijono	Ei	Valinnainen painikkeen teksti (voi toimia kuvatekstinä tai linkkinä).
`painike_linkki`	merkkijono	Ei	Valinnainen painikkeen linkin URL-osoite.

Pyydä hyötykuorma esimerkki:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Watch+this+tutorial%21&video.url=https%3A%2F%2Fwww.example.com%2Fvideo.mp4&video.thumbnail=https%3A%2F%2Fwww.example.com%2Fvideo-thumbnail.png&video.size_mb=1&video.duration_sec=3&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Lähettää Viber One-Time -salasanat (OTP) käyttämällä ennalta hyväksyttyä mallia.

Huomautus

Kun lähetät OTP-viestejä, sinun on asetettava "sending_method" -asetukseksi "viber_otp".

Lisäparametrit:

| Parametri | Tyyppi | Pakollinen | Kuvaus |
| :--- | :--- | :--- | :--- |
| `template.id` | merkkijono | **Kyllä** | Esihyväksytty Viber OTP -mallin tunnus. |
| `template.lang` | merkkijono | **Kyllä** | Mallin kielikoodi (esim. "en", "uk"). |
| `template.params.pin` | merkkijono | **Kyllä** | Malliin lisättävä OTP-nasta-arvo. |
| `template.params.business_platform_name` | merkkijono | **Kyllä** | Yrityksen nimen paikkamerkki mallissa. |
| `template.params.code_validity_time` | merkkijono | **Kyllä** | PIN-koodin voimassaoloaika minuuteissa. |

**Pyydä hyötykuorma esimerkki:**
```http
POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber_otp&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&template.id=otp_template_123&template.lang=en&template.params.pin=123456&template.params.business_platform_name=SMSBAT&template.params.code_validity_time=7
```

KaruselliviestiTutkimusviesti

Lähettää interaktiivisen viestikortin, joka sisältää useita dioja (kortteja), joiden läpi käyttäjä voi pyyhkäistä.

Lisäparametrit:

Parametri	Tyyppi	Pakollinen	Kuvaus
`txt`	merkkijono	Kyllä	Karusellin otsikkoteksti.
`karuselli[N].nimi`	merkkijono	Kyllä	Kortin nimi "N" (alkaen 0:sta).
`karuselli[N].image_url`	merkkijono	Kyllä	Kortin N julkinen HTTPS-kuvan URL-osoite.
`karuselli[N].ensisijainen_tunniste`	merkkijono	Kyllä	Kortin pääpainikkeen otsikko "N".
`karuselli[N].ensisijainen_url`	merkkijono	Kyllä	Pääpainikkeen linkin URL-osoite kortin N.
`karuselli[N].toissijainen_tunniste`	merkkijono	Ei	Kortin toissijaisen painikkeen otsikko "N".
`karuselli[N].secondary_url`	merkkijono	Ei	Kortin "N" toissijaisen painikkeen linkin URL-osoite.

Pyydä hyötykuorma esimerkki:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Top+picks+for+you&carousel%5B0%5D.title=First+Offer&carousel%5B0%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-1.png&carousel%5B0%5D.primary_label=Open&carousel%5B0%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-1&carousel%5B0%5D.secondary_label=Details&carousel%5B0%5D.secondary_url=https%3A%2F%2Fwww.example.com%2Fitem-1%2Fdetails&carousel%5B1%5D.title=Second+Offer&carousel%5B1%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-2.png&carousel%5B1%5D.primary_label=Open&carousel%5B1%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-2

Lähettää viestin, joka sisältää interaktiivisen kyselyn tai kyselyn.

Lisäparametrit:

Parametri	Tyyppi	Pakollinen	Kuvaus
`txt`	merkkijono	Kyllä	Kyselykysymyksen teksti.
`kyselyn_vaihtoehdot[N]`	merkkijono	Kyllä	Kyselyvaihtoehdon teksti kohteelle "N" (indeksi alkaen 0). Vähintään 2 vaihtoehtoa vaaditaan.
`option_tyyppi`	kokonaisluku	Kyllä	Valitsintyyppi: "1" (radiopainikkeet) tai "2" (tavalliset painikkeet).

Pyydä hyötykuorma esimerkki:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Please+rate+our+service&survey_options%5B0%5D=Excellent&survey_options%5B1%5D=Good&survey_options%5B2%5D=Average&option_type=1

Vastausmuoto

Messagio API -yhteensopivuuspäätepiste palauttaa vastaukset XML-muodossa HTTP 200 OK -tilakoodilla.

Hyväksytty (onnistunut) vastaus

<response>
  <code>0</code>
  <tech_message>OK</tech_message>
  <msg_id phone="380501234567">MESSAGE_GUID</msg_id>
</response>

Virhevastaukset

Jos pyynnön parametrien validointi epäonnistuu tai todennus epäonnistuu, vastaus palauttaa nollasta poikkeavan koodin.

Puuttuva allekirjoitusLuvaton

<response>
  <code>-1</code>
  <tech_message>PARAM ERROR (sign)</tech_message>
</response>

<response>
  <code>-2</code>
  <tech_message>ERROR(unauthorized)</tech_message>
</response>

Takaisinsoittoja

Takaisinsoitto-URL-osoitteet on otettava käyttöön ja niitä on ylläpidettävä alustassasi. SMSBAT lähettää HTTP-takaisinsoittoja päivittääkseen järjestelmäsi toimitustapahtumien, kyselyvastausten ja käyttäjien vastausten osalta.

1. Toimituksen tilan takaisinsoitto

Lähetetään, kun viestin siirtymätila (toimitettu, luettu, epäonnistunut).

Sisältötyyppi: Application/x-www-form-urlencoded
Menetelmä: LÄHETÄ

Pyydä hyötykuormamuotoja:

Toimitetaan:

msg_id=MESSAGE_GUID&status=delivered

** Nähty/luettu:
msg_id=MESSAGE_GUID&status=delivered&type=seen
* Toimittamatta/epäonnistunut:**

msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

Kentien kuvaus:

msg_id: SendMessage-vastauksessa palautettu yksilöllinen SMSBAT-viestitunnus (GUID).
"tila": Toimituksen tulos ("toimitettu", "toimittamaton" tai "tila tuntematon").
"type": Aseta arvoon "nähty", kun vastaanottaja on katsonut viestin.
status_extended: Tietty tekninen syy toimittamattoman tilan tilaan (esim. VIBER_EXPIRED, VIBER_BLOCKED_BY_USER, VIBER_USER_NOT_FOUND, VIBER_NO_DEVICE).

2. Kyselyn vastaus takaisinsoitto

Laukaisee, kun käyttäjä valitsee vastausvaihtoehdon Viber Survey -viestissä.

Sisältötyyppi: Application/x-www-form-urlencoded
Menetelmä: LÄHETÄ

Pyydä hyötykuorman muotoa:

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. Saapuvan käyttäjän viestin takaisinsoitto

Laukaisee, kun käyttäjä lähettää teksti- tai mediavastauksen takaisin Viber Business -palveluusi.

Content-Type: "sovellus/json".
Menetelmä: LÄHETÄ

Pyydä hyötykuorman muotoa:

{
  "msg_id": "INBOUND_MESSAGE_GUID",
  "text": "Hello, I have a question",
  "media": "https://example.com/user-attachment.png",
  "phone": "380501234567",
  "sender_bm_id": "12345"
}

Kentien kuvaus:

msg_id: saapuvalle vastaukselle luotu yksilöllinen viestin tunnus.
"teksti": käyttäjän lähettämä tekstisisältö (voi olla "nolla", jos hän lähetti vain mediaa).
"media": Suora URL-osoite, josta voit ladata käyttäjän lähettämät medialiitteet (voi olla "nolla", jos vain tekstiä).
"Puhelin": Lähettäjän puhelinnumero kansainvälisessä muodossa.
"sender_bm_id": Viber Business -lähettäjätunnus.