Skoči na vsebino

Združljivost API-ja Messagio

SMSBAT podpira združljivostno plast z Messagio API. To vam omogoča, da svoje obstoječe integracije Viber, zasnovane za Messagio, preselite neposredno v SMSBAT, ne da bi vam bilo treba prepisati strukturo koristnega tovora ali spremeniti logiko integracije.

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/SendMessage
  • Oblika zahteve: application/x-www-form-urlencoded (podatki obrazca)

Preverjanje pristnosti in poverilnice

Zahteve so overjene s parametri, poslanimi neposredno znotraj podatkov obrazca telesa zahteve:

Parameter Vrsta Zahtevano Opis
uporabnik niz Da Vaša prijava v račun SMSBAT ali uporabniški identifikator.
znak niz Da API skrivnost ali podpis, registriran za ime pošiljatelja.
od niz Da Alfa ime registriranega pošiljatelja.
metoda_pošiljanja niz Da Vrsta kanala. Uporabite viber za običajna sporočila Viber Business ali viber_otp za predloge Viber OTP.
telefon niz Da Telefonska številka prejemnika v mednarodni obliki (npr. »380501234567«).

Vrste sporočil Viber

Izberite spodnji zavihek, da si ogledate specifične parametre in zahtevate obremenitve za različne strukture sporočil Viber:

Pošlje preprosto besedilno sporočilo.

Dodatni parametri:

Parameter Vrsta Zahtevano Opis
txt niz Da Besedilo sporočila.

Primer zahtevane obremenitve: 

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

Pošlje besedilno sporočilo z interaktivnim gumbom za poziv k dejanju.

Dodatni parametri:

Parameter Vrsta Zahtevano Opis
txt niz Da Besedilo sporočila.
besedilo_gumba niz Da Besedilo, prikazano na gumbu.
povezava_gumba niz Da Ciljni URL ob kliku gumba.

Primer zahtevane obremenitve: 

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

Pošlje javno slikovno datoteko.

Dodatni parametri:

Parameter Vrsta Zahtevano Opis
povezava_slike niz Da Javni HTTPS URL slike.
txt niz Ne Izbirno besedilo napisa za prikaz pod sliko.

Primer zahtevane obremenitve: 

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

Pošlje obogateno kartico, ki vsebuje besedilo, sliko in gumb.

Dodatni parametri:

Parameter Vrsta Zahtevano Opis
txt niz Da Besedilo napisa.
povezava_slike niz Da Javni HTTPS URL slike.
besedilo_gumba niz Da Besedilo, prikazano na gumbu.
povezava_gumba niz Da Ciljni URL ob kliku gumba.

Primer zahtevane obremenitve: 

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

Pošlje video datoteko z izbirnim besedilnim napisom in gumbi za dejanja.

Dodatni parametri:

Parameter Vrsta Zahtevano Opis
video.url niz Da Javni HTTPS URL video datoteke.
video.sličica niz Da Javni HTTPS URL slike za predogled videa.
video.size_mb celo število Da Približna velikost video datoteke v megabajtih.
video.duration_sec celo število Da Trajanje videa v sekundah.
txt niz Ne Neobvezno opisno besedilo.
besedilo_gumba niz Ne Neobvezno besedilo gumba (lahko deluje kot napis ali povezava).
povezava_gumba niz Ne Izbirni URL povezave gumba.

Primer zahtevane obremenitve: 

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

Pošlje Viber enkratna gesla (OTP) z uporabo vnaprej odobrene predloge.

Opomba

Ko pošiljate sporočila OTP, morate ending_method nastaviti na viber_otp.

Dodatni parametri:

| Parameter | Vrsta | Zahtevano | Opis |
| :--- | :--- | :--- | :--- |
| `template.id` | niz | **Da** | Vnaprej odobren ID predloge Viber OTP. |
| `template.lang` | niz | **Da** | Koda jezika predloge (npr. `en`, `uk`). |
| `template.params.pin` | niz | **Da** | Vrednost pina OTP, ki se vstavi v predlogo. |
| `template.params.ime_poslovne_platforme` | niz | **Da** | Mesto za ime podjetja v predlogi. |
| `template.params.code_validity_time` | niz | **Da** | Obdobje veljavnosti PIN v minutah. |

**Primer zahtevane obremenitve:**
```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
```

Pošlje interaktivno kartico s sporočilom, ki vsebuje več diapozitivov (kartic), po katerih lahko uporabnik povleče.

Dodatni parametri:

Parameter Vrsta Zahtevano Opis
txt niz Da Besedilo naslova vrtiljaka.
vrtiljak[N].naslov niz Da Naslov kartice »N« (začne se pri 0).
vrtiljak[N].url_slike niz Da URL javne slike HTTPS kartice »N«.
vrtiljak[N].primarna_oznaka niz Da Napis glavnega gumba kartice »N«.
vrtiljak[N].primarni_url niz Da URL povezave do glavnega gumba kartice »N«.
vrtiljak[N].sekundarna_oznaka niz Ne Napis sekundarnega gumba kartice »N«.
vrtiljak[N].sekundarni_url niz Ne URL povezave do sekundarnega gumba kartice »N«.

Primer zahtevane obremenitve: 

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

Pošlje sporočilo, ki vsebuje interaktivno anketo ali anketno vprašanje.

Dodatni parametri:

Parameter Vrsta Zahtevano Opis
txt niz Da Besedilo anketnega vprašanja.
možnosti_ankete[N] niz Da Besedilo možnosti ankete za postavko N (indeks se začne pri 0). Potrebni sta vsaj 2 možnosti.
vrsta_možnosti celo število Da Vrsta izbirnika: 1 (RadioButtons) ali 2 (navadni gumbi).

Primer zahtevane obremenitve: 

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

Oblika odgovora

Končna točka združljivosti API-ja Messagio vrne odgovore v formatu XML s statusno kodo »HTTP 200 OK«.

Sprejet (uspešen) odgovor

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

Odgovori na napake

Če preverjanje parametrov zahteve ne uspe ali avtentikacija ne uspe, bo odgovor vrnil kodo, ki ni ničelna.

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

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

Povratni klici

URL-ji za povratni klic morajo biti implementirani in gostovani na vaši platformi. SMSBAT pošilja povratne klice HTTP, da posodobi vaš sistem glede dogodkov dostave, odgovorov na ankete in odgovorov uporabnikov.

1. Povratni klic stanja dostave

Poslano, ko sporočilo spremeni status (dostavljeno, prebrano, neuspešno).

  • Content-Type: application/x-www-form-urlencoded
  • Metoda: POST

Zahtevajte formate koristne vsebine:

  • Dostavljeno: 
    msg_id=MESSAGE_GUID&status=delivered
  • Viđeno/prebrano: 
    msg_id=MESSAGE_GUID&status=delivered&type=seen
  • Nedostavljeno / Neuspelo: 
    msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

Opis polj:

  • msg_id: Enolični ID sporočila SMSBAT (GUID), vrnjen v odgovoru SendMessage.
  • stanje: izid dostave (dostavljeno, nedostavljeno ali neznano stanje).
  • type: nastavite na seen, ko si je sporočilo ogledal prejemnik.
  • status_extended: Poseben tehnični razlog za nedostavljeno stanje (npr. VIBER_EXPIRED, VIBER_BLOCKED_BY_USER, VIBER_USER_NOT_FOUND, VIBER_NO_DEVICE).

2. Povratni klic za odgovor na anketo

Sproži se, ko uporabnik izbere možnost odgovora v sporočilu Viber Survey.

  • Content-Type: application/x-www-form-urlencoded
  • Metoda: POST

Zahtevajte obliko koristnega tovora: 

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. Povratni klic dohodnega uporabniškega sporočila

Sproži se, ko uporabnik pošlje besedilo ali predstavnostni odgovor nazaj vaši storitvi Viber Business.

  • Content-Type: application/json
  • Metoda: POST

Zahtevajte obliko koristnega tovora: 

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

Opis polj:

  • msg_id: enolični ID sporočila, ustvarjen za dohodni odgovor.
  • text: Besedilna vsebina, ki jo pošlje uporabnik (lahko je null, če je poslal samo predstavnost).
  • media: neposredni URL za prenos vseh medijskih prilog, ki jih pošlje uporabnik (lahko je null, če je samo besedilo).
  • phone: Telefonska številka pošiljatelja v mednarodni obliki.
  • sender_bm_id: ID pošiljatelja Viber Business.