Kompatibilita Messagio API

SMSBAT podporuje vrstvu kompatibility s Messagio API. To vám umožní migrovať vaše existujúce integrácie Viber navrhnuté pre Messagio priamo do SMSBAT bez toho, aby ste museli prepisovať štruktúru užitočného zaťaženia alebo meniť logiku integrácie.

Nastavenia pripojenia

Ak chcete smerovať požiadavky cez SMSBAT, aktualizujte základnú webovú adresu a overovacie poverenia vo svojej integrácii:

Základná adresa URL: https://restapi.smsbat.com
Koncový bod: POST /api/SendMessage
Formát žiadosti: application/x-www-form-urlencoded (údaje formulára)

Autentifikácia a poverenia

Žiadosti sa overujú pomocou parametrov odoslaných priamo v rámci údajov formulára tela žiadosti:

Parameter	Typ	povinné	Popis
"používateľ"	reťazec	Áno	Prihlasovacie meno vášho účtu SMSBAT alebo identifikátor používateľa.
"znamenie"	reťazec	Áno	Tajomstvo API alebo podpis registrovaný pre meno odosielateľa.
"od"	reťazec	Áno	Alfa meno registrovaného odosielateľa.
`metóda_odosielania`	reťazec	Áno	Typ kanála. Použite `viber` pre bežné správy Viber Business alebo `viber_otp` pre šablóny Viber OTP.
"telefón"	reťazec	Áno	Telefónne číslo príjemcu v medzinárodnom formáte (napr. „380501234567“).

Typy správ Viber

Ak chcete zobraziť špecifické parametre a vyžiadať si užitočné zaťaženie pre rôzne štruktúry správ Viber, vyberte kartu nižšie:

Textová správaText + tlačidloObrázková správaText + obrázok + tlačidloVideo správaŠablóna OTP

Odošle jednoduchú textovú správu.

Dodatočné parametre:

Parameter	Typ	povinné	Popis
`txt`	reťazec	Áno	Text správy.

Príklad žiadosti o užitočné zaťaženie:

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

Odošle textovú správu s interaktívnym tlačidlom výzvy na akciu.

Dodatočné parametre:

Parameter	Typ	povinné	Popis
`txt`	reťazec	Áno	Text správy.
`text_tlačidla`	reťazec	Áno	Text zobrazený na tlačidle.
`odkaz_na_tlačidlo`	reťazec	Áno	Cieľová adresa URL po kliknutí na tlačidlo.

Príklad žiadosti o užitočné zaťaženie:

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

Odošle verejný obrazový súbor.

Dodatočné parametre:

Parameter	Typ	povinné	Popis
`image_link`	reťazec	Áno	Verejná HTTPS adresa URL obrázka.
`txt`	reťazec	Nie	Voliteľný text titulku, ktorý sa zobrazí pod obrázkom.

Príklad žiadosti o užitočné zaťaženie:

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

Odošle multimediálnu kartu obsahujúcu text, obrázok a tlačidlo.

Dodatočné parametre:

Parameter	Typ	povinné	Popis
`txt`	reťazec	Áno	Text titulku.
`image_link`	reťazec	Áno	Verejná HTTPS adresa URL obrázka.
`text_tlačidla`	reťazec	Áno	Text zobrazený na tlačidle.
`odkaz_na_tlačidlo`	reťazec	Áno	Cieľová adresa URL po kliknutí na tlačidlo.

Príklad žiadosti o užitočné zaťaženie:

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

Odošle video súbor s voliteľným textovým titulkom a tlačidlami akcií.

Dodatočné parametre:

Parameter	Typ	povinné	Popis
`video.url`	reťazec	Áno	Verejná HTTPS adresa URL súboru videa.
`video.thumbnail`	reťazec	Áno	Verejná webová adresa HTTPS obrázka ukážky videa.
`video.size_mb`	celé číslo	Áno	Približná veľkosť súboru videa v megabajtoch.
`video.duration_sec`	celé číslo	Áno	Trvanie videa v sekundách.
`txt`	reťazec	Nie	Voliteľný text popisu.
`text_tlačidla`	reťazec	Nie	Voliteľný text tlačidla (môže fungovať ako titulok alebo odkaz).
`odkaz_na_tlačidlo`	reťazec	Nie	Voliteľná adresa URL odkazu na tlačidlo.

Príklad žiadosti o užitočné zaťaženie:

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

Posiela Viber jednorazové heslá (OTP) pomocou vopred schválenej šablóny.

Poznámka

Pri odosielaní správ OTP musíte nastaviť sending_method na viber_otp.

Dodatočné parametre:

| Parameter | Typ | povinné | Popis |
| :--- | :--- | :--- | :--- |
| `template.id` | reťazec | **Áno** | Vopred schválené ID šablóny Viber OTP. |
| `template.lang` | reťazec | **Áno** | Kód jazyka šablóny (napr. „sk“, „uk“). |
| `template.params.pin` | reťazec | **Áno** | Hodnota pinu OTP, ktorá sa má vložiť do šablóny. |
| `template.params.business_platform_name` | reťazec | **Áno** | Zástupný symbol obchodného názvu v šablóne. |
| `template.params.code_validity_time` | reťazec | **Áno** | Doba platnosti PIN v minútach. |

**Príklad žiadosti o užitočné zaťaženie:**
```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
```

Správa z kolotočaSpráva o prieskume

Odošle interaktívnu kartu so správou obsahujúcu viaceré snímky (karty), cez ktoré môže používateľ prechádzať prstom.

Dodatočné parametre:

Parameter	Typ	povinné	Popis
`txt`	reťazec	Áno	Text nadpisu kolotoča.
`kolotoč[N].title`	reťazec	Áno	Názov karty „N“ (začína od 0).
`carousel[N].image_url`	reťazec	Áno	Verejná webová adresa obrázka HTTPS karty „N“.
`kolotoč[N].primary_label`	reťazec	Áno	Titulok hlavného tlačidla karty „N“.
`kolotoč[N].primary_url`	reťazec	Áno	Adresa URL odkazu na hlavné tlačidlo karty „N“.
`kolotoč[N].sekundárny_štítok`	reťazec	Nie	Titulok sekundárneho tlačidla karty „N“.
`kolotoč[N].secondary_url`	reťazec	Nie	Adresa URL odkazu na sekundárne tlačidlo karty „N“.

Príklad žiadosti o užitočné zaťaženie:

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

Odošle správu obsahujúcu interaktívny prieskum alebo anketovú otázku.

Dodatočné parametre:

Parameter	Typ	povinné	Popis
`txt`	reťazec	Áno	Text prieskumnej otázky.
`možnosti_prieskumu[N]`	reťazec	Áno	Text možnosti prieskumu pre položku „N“ (index začínajúci od 0). Vyžadujú sa aspoň 2 možnosti.
"typ_možnosti"	celé číslo	Áno	Typ voliča: „1“ (RadioButtons) alebo „2“ (bežné tlačidlá).

Príklad žiadosti o užitočné zaťaženie:

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

Formát odpovede

Koncový bod kompatibility rozhrania Messagio API vracia odpovede vo formáte XML so stavovým kódom „HTTP 200 OK“.

Prijatá (úspešná) odpoveď

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

Odpovede na chyby

Ak overenie parametrov požiadavky zlyhá alebo autentifikácia zlyhá, odpoveď vráti nenulový kód.

Chýbajúci podpisNeoprávnené

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

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

Spätné volania

Webové adresy spätného volania musia byť implementované a hostené na vašej platforme. SMSBAT posiela spätné volanie HTTP na aktualizáciu vášho systému týkajúceho sa udalostí doručenia, odpovedí na prieskum a odpovedí používateľov.

1. Spätné volanie o stave doručenia

Odoslané pri zmene stavu správy (doručená, prečítaná, neúspešná).

Content-Type: application/x-www-form-urlencoded
Spôsob: „POST“.

Formáty obsahu žiadosti:

Doručené:

msg_id=MESSAGE_GUID&status=delivered

Zobrazené/prečítané:

msg_id=MESSAGE_GUID&status=delivered&type=seen

* Nedoručené / zlyhalo:

msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

Popis polí:

msg_id: Jedinečné ID správy SMSBAT (GUID) vrátené v odpovedi SendMessage.
„stav“: výsledok doručenia („doručený“, „nedoručený“ alebo „neznámy stav“).
type: Nastavte na videl, keď si správu prezrel príjemca.
status_extended: Špecifický technický dôvod stavu nedoručenia (napr. VIBER_EXPIRED, VIBER_BLOCKED_BY_USER, VIBER_USER_NOT_FOUND, VIBER_NO_DEVICE).

2. Spätné volanie prieskumu

Spustí sa, keď používateľ vyberie možnosť odpovede v správe prieskumu Viber.

Content-Type: application/x-www-form-urlencoded
Spôsob: „POST“.

Formát žiadosti o užitočné zaťaženie:

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. Spätné volanie prichádzajúcej správy používateľa

Spustí sa, keď používateľ odošle textovú alebo mediálnu odpoveď späť do vašej služby Viber Business.

Typ obsahu: application/json
Spôsob: „POST“.

Formát žiadosti o užitočné zaťaženie:

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

Popis polí:

msg_id: Jedinečné ID správy vygenerované pre prichádzajúcu odpoveď.
text: Textový obsah odoslaný používateľom (môže byť null, ak odosielal iba médiá).
media: Priama adresa URL na stiahnutie akýchkoľvek mediálnych príloh odoslaných používateľom (môže byť null, ak ide len o text).
phone: Telefónne číslo odosielateľa v medzinárodnom formáte.
sender_bm_id: ID odosielateľa Viber Business.