Pereiti prie turinio

„Messagio“ API suderinamumas

SMSBAT palaiko suderinamumo sluoksnį su Messagio API. Tai leidžia perkelti esamas „Viber“ integracijas, skirtas „Messagio“, tiesiai į SMSBAT, nereikalaujant perrašyti naudingosios apkrovos struktūros ar nekeičiant integravimo logikos.

Ryšio nustatymai

Norėdami nukreipti užklausas per SMSBAT, integruodami atnaujinkite bazinį URL ir autentifikavimo kredencialus:

– Pagrindinis URL: „https://restapi.smsbat.com“. - Galinis taškas: „POST /api/SendMessage“. – Užklausos formatas: „application/x-www-form-urlencoded“ (formos duomenys)

Autentifikavimas ir kredencialai

Užklausos autentifikuojamos naudojant parametrus, siunčiamus tiesiai į užklausos turinio formos duomenis:

Parametras Tipas Reikalingas Aprašymas
"vartotojas" styga Taip Jūsų SMSBAT paskyros prisijungimas arba vartotojo identifikatorius.
signalas styga Taip API paslaptis arba parašas, užregistruotas siuntėjo vardui.
"nuo" styga Taip Registruotas siuntėjo alfa vardas.
siuntimo_metodas styga Taip Kanalo tipas. Naudokite „viber“ įprastiems „Viber Business“ pranešimams arba „viber_otp“ Viber OTP šablonams.
telefonas styga Taip Gavėjo telefono numeris tarptautiniu formatu (pvz., „380501234567“).

Viber pranešimų tipai

Pasirinkite toliau esantį skirtuką, kad peržiūrėtumėte konkrečius parametrus ir prašytumėte įvairių Viber pranešimų struktūrų naudingųjų apkrovų:

Siunčia paprastą tekstinį pranešimą.

Papildomi parametrai:

Parametras Tipas Reikalingas Aprašymas
txt styga Taip Pranešimo tekstas.

Užklausos naudingos apkrovos pavyzdys: 

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

Siunčia tekstinį pranešimą su interaktyviu raginimo veikti mygtuku.

Papildomi parametrai:

Parametras Tipas Reikalingas Aprašymas
txt styga Taip Pranešimo tekstas.
"mygtuko_tekstas" styga Taip Tekstas rodomas ant mygtuko.
mygtuko_linkas styga Taip Paskirties URL spustelėjus mygtuką.

Užklausos naudingos apkrovos pavyzdys: 

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

Siunčia viešą vaizdo failą.

Papildomi parametrai:

Parametras Tipas Reikalingas Aprašymas
„vaizdo_nuoroda“ styga Taip Vaizdo viešas HTTPS URL.
txt styga Ne Pasirenkamas antraštės tekstas, rodomas po vaizdu.

Užklausos naudingos apkrovos pavyzdys: 

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

Siunčia turtingą kortelę su tekstu, vaizdu ir mygtuku.

Papildomi parametrai:

Parametras Tipas Reikalingas Aprašymas
txt styga Taip Antraštės tekstas.
„vaizdo_nuoroda“ styga Taip Vaizdo viešas HTTPS URL.
"mygtuko_tekstas" styga Taip Tekstas rodomas ant mygtuko.
mygtuko_linkas styga Taip Paskirties URL spustelėjus mygtuką.

Užklausos naudingos apkrovos pavyzdys: 

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

Siunčia vaizdo įrašo failą su pasirenkama teksto antrašte ir veiksmų mygtukais.

Papildomi parametrai:

Parametras Tipas Reikalingas Aprašymas
video.url styga Taip Vaizdo įrašo failo viešas HTTPS URL.
video.thumbnail styga Taip Vaizdo įrašo peržiūros vaizdo viešas HTTPS URL.
video.size_mb sveikasis skaičius Taip Apytikslis vaizdo failo dydis megabaitais.
video.duration_sec sveikasis skaičius Taip Vaizdo įrašo trukmė sekundėmis.
txt styga Ne Neprivalomas aprašo tekstas.
"mygtuko_tekstas" styga Ne Neprivalomas mygtuko tekstas (gali veikti kaip antraštė arba nuoroda).
mygtuko_linkas styga Ne Neprivalomas mygtuko nuorodos URL.

Užklausos naudingos apkrovos pavyzdys: 

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

Siunčia Viber vienkartinius slaptažodžius (OTP) naudodamas iš anksto patvirtintą šabloną.

Pastaba

Siunčiant vienkartinius pranešimus, sending_method turite nustatyti į viber_otp.

Papildomi parametrai:

| Parametras | Tipas | Reikalingas | Aprašymas |
| :--- | :--- | :--- | :--- |
| `šablonas.id` | styga | **Taip** | Iš anksto patvirtintas Viber OTP šablono ID. |
| `template.lang` | styga | **Taip** | Šablono kalbos kodas (pvz., „en“, „uk“). |
| `template.params.pin` | styga | **Taip** | Vienkartinio slaptažodžio PIN reikšmė, kurią reikia įvesti į šabloną. |
| `template.params.business_platform_name` | styga | **Taip** | Įmonės pavadinimo rezervuota vieta šablone. |
| `template.params.code_validity_time` | styga | **Taip** | PIN galiojimo laikas minutėmis. |

**Užklausos naudingos apkrovos pavyzdys:**
```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
```

=== „Karuselės pranešimas“

Siunčia interaktyvią pranešimų kortelę, kurioje yra kelios skaidrės (kortelės), kurias vartotojas gali perbraukti.

**Papildomi parametrai:**

| Parametras | Tipas | Reikalingas | Aprašymas |
| :--- | :--- | :--- | :--- |
| `txt` | styga | **Taip** | Karuselės pavadinimo tekstas. |
| `karuselė[N].pavadinimas` | styga | **Taip** | Kortelės pavadinimas „N“ (pradedant nuo 0). |
| `karuselė[N].image_url` | styga | **Taip** | Kortelės „N“ viešas HTTPS vaizdo URL. |
| `karuselė[N].pagrindinė_etiketė` | styga | **Taip** | Pagrindinės kortelės mygtuko antraštė „N“. |
| `karuselė[N].pirminis_url` | styga | **Taip** | Kortelės „N“ pagrindinio mygtuko nuorodos URL. |
| `karuselė[N].antrinė_etiketė` | styga | Ne | Antrinio mygtuko antraštė ant kortelės „N“. |
| `karuselė[N].antrinis_url` | styga | Ne | Kortelės „N“ antrinio mygtuko nuorodos URL. |

**Užklausos naudingos apkrovos pavyzdys:**
```http
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
```

Siunčia pranešimą su interaktyviu apklausos ar apklausos klausimu.

Papildomi parametrai:

Parametras Tipas Reikalingas Aprašymas
txt styga Taip Apklausos klausimo tekstas.
apklausos_parinktys[N] styga Taip Elemento „N“ apklausos parinkties tekstas (indeksas prasideda nuo 0). Reikalingi bent 2 variantai.
„parinkties_tipas“ sveikasis skaičius Taip Pasirinkiklio tipas: „1“ (radijo mygtukai) arba „2“ (įprasti mygtukai).

Užklausos naudingos apkrovos pavyzdys: 

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

Atsakymo formatas

„Messagio“ API suderinamumo galutinis taškas pateikia atsakymus XML formatu su „HTTP 200 OK“ būsenos kodu.

Priimtas (sėkmingas) atsakymas

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

Klaidų atsakymai

Jei užklausos parametrų patvirtinimas nepavyksta arba autentifikavimas nepavyksta, atsakymas grąžins kodą, kuris nėra nulis.

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

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

Atgaliniai skambučiai

Atgalinio iškvietimo URL turi būti įdiegti ir priglobti jūsų platformoje. SMSBAT siunčia atgalinius HTTP skambučius, kad atnaujintų jūsų sistemą apie pristatymo įvykius, apklausų atsakymus ir vartotojų atsakymus.

1. Pristatymo būsenos atgalinis skambutis

Išsiunčiama, kai pranešimo būsena perkeliama (pristatyta, perskaityta, nepavyko).

– Turinio tipas: „application/x-www-form-urlencoded“ - Metodas: „PASKELBTI“.

Prašyti naudingos apkrovos formatų:

Pristatyta: 

msg_id=MESSAGE_GUID&status=delivered
Matytas/skaitytas: 
msg_id=MESSAGE_GUID&status=delivered&type=seen
Nepristatyta / nepavyko: 
msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

Laukų aprašymas:

  • msg_id: SMSBAT unikalus pranešimo ID (GUID), grąžintas atsakyme SendMessage.
  • „būsena“: pristatymo rezultatas („pristatytas“, „nepristatytas“ arba „būsena nežinoma“).
  • Tipas: nustatykite į „mačiau“, kai gavėjas peržiūrėjo pranešimą. – „status_extended“: konkreti techninė nepristatymo būsenos priežastis (pvz., „VIBER_EXPIRED“, „VIBER_BLOCKED_BY_USER“, „VIBER_USER_NOT_FOUND“, „VIBER_NO_DEVICE“).

2. Apklausos atsakymas atgalinis skambutis

Suveikia, kai vartotojas pasirenka atsakymo parinktį Viber Survey pranešime.

– Turinio tipas: „application/x-www-form-urlencoded“ - Metodas: „PASKELBTI“.

Užklausos naudingos apkrovos formatas: 

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. Įeinančio vartotojo žinutės atgalinis skambutis

Suaktyvinama, kai vartotojas siunčia tekstinį arba žiniasklaidos atsakymą atgal į jūsų „Viber Business“ paslaugą.

– Turinio tipas: „application/json“. - Metodas: „PASKELBTI“.

Užklausos naudingos apkrovos formatas: 

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

Laukų aprašymas:

  • msg_id: unikalus pranešimo ID, sugeneruotas gaunamam atsakymui. – „tekstas“: vartotojo atsiųstas teksto turinys (gali būti „nulis“, jei jis siuntė tik mediją).
  • „Media“: tiesioginis URL, skirtas atsisiųsti bet kokius vartotojo atsiųstus medijos priedus (gali būti „nulis“, jei tik tekstas).
  • „Telefonas“: siuntėjo telefono numeris tarptautiniu formatu.
  • „sender_bm_id“: „Viber Business“ siuntėjo ID.