Preskoči na sadržaj

Messagio API kompatibilnost

SMSBAT podržava sloj kompatibilnosti s Messagio API. To vam omogućuje da migrirate svoje postojeće Viber integracije dizajnirane za Messagio izravno u SMSBAT bez potrebe da prepisujete strukturu nosivosti ili mijenjate logiku integracije.

Postavke veze

Za usmjeravanje zahtjeva putem SMSBAT-a ažurirajte osnovni URL i vjerodajnice za provjeru autentičnosti u svojoj integraciji:

  • Osnovni URL: https://restapi.smsbat.com
  • Krajnja točka: POST /api/SendMessage
  • Format zahtjeva: application/x-www-form-urlencoded (Podaci obrasca)

Autentifikacija i vjerodajnice

Zahtjevi se autentificiraju pomoću parametara koji se šalju izravno unutar podataka obrasca tijela zahtjeva:

Parametar Upišite Obavezno Opis
korisnik niz Da Vaša prijava na SMSBAT račun ili identifikator korisnika.
znak niz Da API tajna ili potpis registriran za ime pošiljatelja.
od niz Da Alfa naziv registriranog pošiljatelja.
metoda_slanja niz Da Vrsta kanala. Koristite viber za obične Viber poslovne poruke ili viber_otp za Viber OTP predloške.
telefon niz Da Telefonski broj primatelja u međunarodnom formatu (npr. 380501234567).

Viber vrste poruka

Odaberite karticu u nastavku kako biste vidjeli specifične parametre i zatražili podatke za različite strukture Viber poruka:

Šalje jednostavnu tekstualnu poruku.

Dodatni parametri:

Parametar Upišite Obavezno Opis
txt niz Da Tekst poruke.

Primjer opterećenja zahtjeva: 

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

Šalje tekstualnu poruku s interaktivnim gumbom za poziv na radnju.

Dodatni parametri:

Parametar Upišite Obavezno Opis
txt niz Da Tekst poruke.
tekst_gumba niz Da Tekst prikazan na gumbu.
gumb_veza niz Da Odredišni URL kada se klikne na gumb.

Primjer opterećenja zahtjeva: 

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

Šalje javnu slikovnu datoteku.

Dodatni parametri:

Parametar Upišite Obavezno Opis
slika_veza niz Da Javni HTTPS URL slike.
txt niz Ne Dodatni tekst naslova za prikaz ispod slike.

Primjer opterećenja zahtjeva: 

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

Šalje obogaćenu karticu koja sadrži tekst, sliku i gumb.

Dodatni parametri:

Parametar Upišite Obavezno Opis
txt niz Da Tekst natpisa.
slika_veza niz Da Javni HTTPS URL slike.
tekst_gumba niz Da Tekst prikazan na gumbu.
gumb_veza niz Da Odredišni URL kada se klikne na gumb.

Primjer opterećenja zahtjeva: 

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

Šalje videodatoteku s dodatnim tekstualnim naslovom i akcijskim gumbima.

Dodatni parametri:

Parametar Upišite Obavezno Opis
video.url niz Da Javni HTTPS URL video datoteke.
video.sličica niz Da Javni HTTPS URL slike za pregled videozapisa.
video.size_mb cijeli broj Da Približna veličina video datoteke u megabajtima.
video.duration_sec cijeli broj Da Trajanje videa u sekundama.
txt niz Ne Opcijski tekst opisa.
tekst_gumba niz Ne Izborni tekst gumba (može služiti kao naslov ili poveznica).
gumb_veza niz Ne Neobavezni URL veze gumba.

Primjer opterećenja zahtjeva: 

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

Šalje Viber jednokratne lozinke (OTP) pomoću unaprijed odobrenog predloška.

Bilješka

Kada šaljete OTP poruke, morate postaviti ending_method na viber_otp.

Dodatni parametri:

| Parametar | Upišite | Obavezno | Opis |
| :--- | :--- | :--- | :--- |
| `template.id` | niz | **Da** | Unaprijed odobren Viber OTP ID predloška. |
| `template.lang` | niz | **Da** | Kôd jezika predloška (npr. `en`, `uk`). |
| `template.params.pin` | niz | **Da** | Vrijednost OTP pina za umetanje u predložak. |
| `template.params.business_platform_name` | niz | **Da** | Rezervirano mjesto naziva tvrtke u predlošku. |
| `template.params.code_validity_time` | niz | **Da** | Rok valjanosti PIN-a u minutama. |

**Primjer opterećenja zahtjeva:**
```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
```

Šalje interaktivnu karticu s porukom koja sadrži više slajdova (kartica) kroz koje korisnik može prelaziti.

Dodatni parametri:

Parametar Upišite Obavezno Opis
txt niz Da Naslovni tekst karusela.
vrtuljak[N].naslov niz Da Naslov kartice "N" (počevši od 0).
vrtuljak[N].url_slike niz Da Javni HTTPS URL slike kartice "N".
vrtuljak[N].primarna_oznaka niz Da Naslov glavnog gumba kartice "N".
vrtuljak[N].primarni_url niz Da URL poveznice glavnog gumba kartice "N".
vrtuljak[N].sekundarna_oznaka niz Ne Opis sekundarnog gumba kartice "N".
vrtuljak[N].sekundarni_url niz Ne URL veze sekundarnog gumba kartice "N".

Primjer opterećenja zahtjeva: 

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

Šalje poruku koja sadrži interaktivnu anketu ili anketno pitanje.

Dodatni parametri:

Parametar Upišite Obavezno Opis
txt niz Da Tekst anketnog pitanja.
opcije_ankete[N] niz Da Tekst opcije ankete za stavku N (indeks počinje od 0). Potrebne su najmanje 2 opcije.
vrsta_opcije cijeli broj Da Vrsta selektora: 1 (RadioButtons) ili 2 (obični gumbi).

Primjer opterećenja zahtjeva: 

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

Format odgovora

Krajnja točka kompatibilnosti Messagio API-ja vraća odgovore u XML formatu sa statusnim kodom HTTP 200 OK.

Odgovor prihvaćen (uspjeh).

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

Odgovori na pogreške

Ako provjera valjanosti parametara zahtjeva ne uspije ili provjera autentičnosti ne uspije, odgovor će vratiti kod različit od nule.

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

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

Povratni pozivi

URL-ovi za povratni poziv moraju biti implementirani i hostirani na vašoj platformi. SMSBAT šalje HTTP povratne pozive za ažuriranje vašeg sustava u vezi s događajima isporuke, odgovorima na ankete i odgovorima korisnika.

1. Povratni poziv statusa isporuke

Šalje se kada poruka promijeni status (isporučeno, pročitano, neuspjelo).

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

Formati zahtjeva za sadržaj:

  • Isporučeno: 
    msg_id=MESSAGE_GUID&status=delivered
  • Viđeno/pročitano: 
    msg_id=MESSAGE_GUID&status=delivered&type=seen
  • Neisporučeno / Neuspjelo: 
    msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

Opis polja:

  • msg_id: SMSBAT jedinstveni ID poruke (GUID) vraćen u odgovoru SendMessage.
  • status: Ishod isporuke (isporučeno, neisporučeno ili status nepoznat).
  • type: Postavite na seen kada je poruku pregledao primatelj.
  • status_extended: Poseban tehnički razlog statusa nedostavljenog (npr. VIBER_EXPIRED, VIBER_BLOCKED_BY_USER, VIBER_USER_NOT_FOUND, VIBER_NO_DEVICE).

2. Povratni poziv za odgovor na anketu

Pokreće se kada korisnik odabere opciju odgovora u poruci Viber ankete.

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

Format zahtjeva za sadržaj: 

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. Povratni poziv dolazne korisničke poruke

Pokreće se kada korisnik pošalje tekstualni ili medijski odgovor vašoj Viber Business usluzi.

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

Format zahtjeva za sadržaj: 

{
  "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 polja:

  • msg_id: Jedinstveni ID poruke generiran za dolazni odgovor.
  • tekst: tekstualni sadržaj koji šalje korisnik (može biti null ako je poslao samo medije).
  • media: izravni URL za preuzimanje svih medijskih privitaka koje je poslao korisnik (može biti null ako je samo tekst).
  • phone: Telefonski broj pošiljatelja u međunarodnom formatu.
  • sender_bm_id: Viber Business ID pošiljatelja.