Kompatibilita Messagio API

SMSBAT podporuje vrstvu kompatibility s Messagio API. To vám umožní migrovat vaše stávající integrace Viber navržené pro Messagio přímo do SMSBAT, aniž byste museli přepisovat strukturu užitečného zatížení nebo měnit logiku integrace.

Nastavení připojení

Chcete-li směrovat požadavky prostřednictvím SMSBAT, aktualizujte základní adresu URL a ověřovací pověření ve vaší integraci:

Základní adresa URL: https://restapi.smsbat.com
Koncový bod: POST /api/SendMessage
Formát požadavku: application/x-www-form-urlencoded (data formuláře)

Autentizace a přihlašovací údaje

Žádosti se ověřují pomocí parametrů odeslaných přímo v datech formuláře těla žádosti:

Parametr	Typ	Povinné	Popis
"uživatel"	řetězec	Ano	Vaše přihlašovací jméno k účtu SMSBAT nebo identifikátor uživatele.
"znamení"	řetězec	Ano	Tajný klíč API nebo podpis registrovaný pro jméno odesílatele.
"od"	řetězec	Ano	Alfa jméno registrovaného odesílatele.
`způsob_odesílání`	řetězec	Ano	Typ kanálu. Použijte `viber` pro běžné zprávy Viber Business nebo `viber_otp` pro šablony Viber OTP.
"telefon"	řetězec	Ano	Telefonní číslo příjemce v mezinárodním formátu (např. „380501234567“).

Typy zpráv Viber

Chcete-li zobrazit konkrétní parametry a požadované užitečné zatížení pro různé struktury zpráv Viber, vyberte kartu níže:

Textová zprávaText + tlačítkoObrázková zprávaText + obrázek + tlačítkoVideo zprávaŠablona OTP

Odešle jednoduchou textovou zprávu.

Další parametry:

Parametr	Typ	Povinné	Popis
`txt`	řetězec	Ano	Text zprávy.

Příklad žádosti o užitečné zatížení:

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

Odešle textovou zprávu s interaktivním tlačítkem s výzvou k akci.

Další parametry:

Parametr	Typ	Povinné	Popis
`txt`	řetězec	Ano	Text zprávy.
`text_tlačítka`	řetězec	Ano	Text zobrazený na tlačítku.
`button_link`	řetězec	Ano	Cílová adresa URL po kliknutí na tlačítko.

Příklad žádosti o užitečné zatížení:

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

Odešle veřejný soubor obrázku.

Další parametry:

Parametr	Typ	Povinné	Popis
`odkaz_na obrázek`	řetězec	Ano	Veřejná HTTPS adresa URL obrázku.
`txt`	řetězec	Ne	Volitelný text titulku, který se zobrazí pod obrázkem.

Příklad žádosti o užitečné zatížení:

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

Odešle formátovanou kartu obsahující text, obrázek a tlačítko.

Další parametry:

Parametr	Typ	Povinné	Popis
`txt`	řetězec	Ano	Text titulku.
`odkaz_na obrázek`	řetězec	Ano	Veřejná HTTPS adresa URL obrázku.
`text_tlačítka`	řetězec	Ano	Text zobrazený na tlačítku.
`button_link`	řetězec	Ano	Cílová adresa URL po kliknutí na tlačítko.

Příklad žádosti o užitečné zatížení:

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

Odešle soubor videa s volitelným textovým titulkem a tlačítky akcí.

Další parametry:

Parametr	Typ	Povinné	Popis
`video.url`	řetězec	Ano	Veřejná HTTPS adresa URL souboru videa.
`video.thumbnail`	řetězec	Ano	Veřejná adresa URL HTTPS obrázku náhledu videa.
`video.size_mb`	celé číslo	Ano	Přibližná velikost souboru videa v megabajtech.
`video.duration_sec`	celé číslo	Ano	Délka videa v sekundách.
`txt`	řetězec	Ne	Volitelný popisný text.
`text_tlačítka`	řetězec	Ne	Volitelný text tlačítka (může fungovat jako titulek nebo odkaz).
`button_link`	řetězec	Ne	Volitelná adresa URL odkazu na tlačítko.

Příklad žádosti o užitečné zatížení:

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

Odesílá Viber One-Time Passwords (OTP) pomocí předem schválené šablony.

Poznámka

Při odesílání zpráv OTP musíte nastavit sending_method na viber_otp.

Další parametry:

| Parametr | Typ | Povinné | Popis |
| :--- | :--- | :--- | :--- |
| `šablona.id` | řetězec | **Ano** | Předschválené ID šablony Viber OTP. |
| `template.lang` | řetězec | **Ano** | Kód jazyka šablony (např. `en`, `uk`). |
| `template.params.pin` | řetězec | **Ano** | Hodnota pinu OTP, která se má vložit do šablony. |
| `template.params.business_platform_name` | řetězec | **Ano** | Zástupný symbol obchodního názvu v šabloně. |
| `template.params.code_validity_time` | řetězec | **Ano** | Doba platnosti PIN v minutách. |

**Příklad žádosti o užitečné zatížení:**
```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
```

kolotočová zprávaZpráva o průzkumu

Odešle interaktivní kartu se zprávou obsahující více snímků (karty), které může uživatel procházet.

Další parametry:

Parametr	Typ	Povinné	Popis
`txt`	řetězec	Ano	Text nadpisu karuselu.
`kolotoč[N].title`	řetězec	Ano	Název karty „N“ (začíná od 0).
`carousel[N].image_url`	řetězec	Ano	Veřejná adresa URL obrázku HTTPS karty „N“.
`kolotoč[N].primární_štítek`	řetězec	Ano	Titulek hlavního tlačítka karty „N“.
`carousel[N].primary_url`	řetězec	Ano	Adresa URL odkazu hlavního tlačítka karty „N“.
`kolotoč[N].sekundární_štítek`	řetězec	Ne	Popisek sekundárního tlačítka karty „N“.
`carousel[N].secondary_url`	řetězec	Ne	Adresa URL odkazu sekundárního tlačítka karty „N“.

Příklad žádosti o užitečné zatížení:

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

Odešle zprávu obsahující interaktivní anketu nebo otázku průzkumu.

Další parametry:

Parametr	Typ	Povinné	Popis
`txt`	řetězec	Ano	Text otázky průzkumu.
`možnosti_průzkumu[N]`	řetězec	Ano	Text možnosti průzkumu pro položku `N` (index začínající na 0). Jsou vyžadovány alespoň 2 možnosti.
`typ_možnosti`	celé číslo	Ano	Typ voliče: `1` (RadioButtons) nebo `2` (běžná tlačítka).

Příklad žádosti o užitečné zatížení:

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 odpovědi

Koncový bod kompatibility Messagio API vrací odpovědi ve formátu XML se stavovým kódem „HTTP 200 OK“.

Přijatá (úspěšná) odpověď

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

Chybové reakce

Pokud selže ověření parametrů požadavku nebo selže autentizace, odpověď vrátí nenulový kód.

Chybí podpisNeoprávněné

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

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

Zpětná volání

Adresy URL zpětného volání musí být implementovány a hostovány na vaší platformě. SMSBAT odesílá zpětná volání HTTP, aby aktualizoval váš systém ohledně událostí doručení, odpovědí na průzkum a odpovědí uživatelů.

1. Zpětné volání stavu doručení

Odesláno, když zpráva změní stav (doručená, přečtená, neúspěšná).

Content-Type: application/x-www-form-urlencoded
Metoda: „POST“.

Formáty požadované zátěže:

Doručeno:

msg_id=MESSAGE_GUID&status=delivered

Zobrazeno/přečteno:

msg_id=MESSAGE_GUID&status=delivered&type=seen

* Nedoručeno / Nezdařilo se:

msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

Popis polí:

msg_id: Jedinečné ID zprávy SMSBAT (GUID) vrácené v odpovědi SendMessage.
stav: Výsledek doručení (doručeno, nedoručeno nebo stav neznámý).
typ: Nastavte na vidět, když si zprávu prohlédl příjemce.
status_extended: Konkrétní technický důvod stavu nedoručení (např. VIBER_EXPIRED, VIBER_BLOCKED_BY_USER, VIBER_USER_NOT_FOUND, VIBER_NO_DEVICE).

2. Zpětné volání v průzkumu

Spustí se, když uživatel vybere možnost odpovědi ve zprávě průzkumu Viber.

Content-Type: application/x-www-form-urlencoded
Metoda: „POST“.

Formát žádosti o užitečné zatížení:

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. Zpětné volání příchozí zprávy uživatele

Spustí se, když uživatel odešle textovou nebo mediální odpověď zpět do vaší služby Viber Business.

Typ obsahu: application/json
Metoda: „POST“.

Formát žádosti o užitečné zatížení:

{
  "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 zprávy vygenerované pro příchozí odpověď.
text: Textový obsah odeslaný uživatelem (může být null, pokud odeslal pouze média).
media: Přímá adresa URL ke stažení jakýchkoli příloh médií odeslaných uživatelem (může být null, pokud je pouze text).
phone: Telefonní číslo odesílatele v mezinárodním formátu.
sender_bm_id: ID odesílatele Viber Business.