Pāriet uz saturu

Messagio API saderība

SMSBAT atbalsta saderības slāni ar Messagio API. Tas ļauj migrēt esošās Viber integrācijas, kas izstrādātas pakalpojumam Messagio, tieši uz SMSBAT, nepārrakstot lietderīgās slodzes struktūru vai nemainot integrācijas loģiku.

Savienojuma iestatījumi

Lai pieprasījumus novirzītu caur SMSBAT, integrācijā atjauniniet bāzes URL un autentifikācijas akreditācijas datus:

  • Pamata URL: https://restapi.smsbat.com
  • Beigu punkts: POST /api/SendMessage
  • Pieprasījuma formāts: application/x-www-form-urlencoded (veidlapas dati)

Autentifikācija un akreditācijas dati

Pieprasījumi tiek autentificēti, izmantojot parametrus, kas nosūtīti tieši pieprasījuma pamatteksta veidlapas datos:

Parametrs Tips Nepieciešams Apraksts
"lietotājs" stīga Jā Jūsu SMSBAT konta pieteikšanās vai lietotāja identifikators.
zīme stīga Jā API noslēpums vai paraksts, kas reģistrēts sūtītāja vārdam.
no stīga Jā Reģistrētais sūtītāja alfa vārds.
sūtīšanas_metode stīga Jā Kanāla veids. Izmantojiet “viber” parastajiem Viber Business ziņojumiem vai “viber_otp” Viber OTP veidnēm.
tālrunis stīga Jā Saņēmēja tālruņa numurs starptautiskā formātā (piemēram, 380501234567).

Viber ziņojumu veidi

Izvēlieties tālāk esošo cilni, lai skatītu konkrētus parametrus un pieprasītu lietderīgās slodzes dažādām Viber ziņojumu struktūrām:

Nosūta vienkāršu īsziņu.

Papildu parametri:

Parametrs Tips Nepieciešams Apraksts
txt stīga Jā Ziņas teksts.

Pieprasīt kravnesību, piemēram: 

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

Nosūta īsziņu ar interaktīvu aicinājuma uz darbību pogu.

Papildu parametri:

Parametrs Tips Nepieciešams Apraksts
txt stīga Jā Ziņas teksts.
pogas_teksts stīga Jā Teksts tiek parādīts uz pogas.
pogas_saite stīga Jā Galamērķa URL, kad tiek noklikšķināts uz pogas.

Pieprasīt kravnesību, piemēram: 

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

Nosūta publisku attēla failu.

Papildu parametri:

Parametrs Tips Nepieciešams Apraksts
image_link stīga Jā Attēla publiskais HTTPS URL.
txt stīga Nē Neobligāts parakstu teksts, kas jāparāda zem attēla.

Pieprasīt kravnesību, piemēram: 

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

Nosūta bagātinātu kartīti, kurā ir teksts, attēls un poga.

Papildu parametri:

Parametrs Tips Nepieciešams Apraksts
txt stīga Jā Parakstu teksts.
image_link stīga Jā Attēla publiskais HTTPS URL.
pogas_teksts stīga Jā Teksts tiek parādīts uz pogas.
pogas_saite stīga Jā Galamērķa URL, kad tiek noklikšķināts uz pogas.

Pieprasīt kravnesību, piemēram: 

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

Nosūta video failu ar izvēles teksta parakstu un darbību pogām.

Papildu parametri:

Parametrs Tips Nepieciešams Apraksts
video.url stīga Jā Video faila publiskais HTTPS URL.
video.thumbnail stīga Jā Video priekšskatījuma attēla publiskais HTTPS URL.
video.size_mb vesels skaitlis Jā Aptuvenais video faila lielums megabaitos.
video.duration_sec vesels skaitlis Jā Video ilgums sekundēs.
txt stīga Nē Apraksta teksts pēc izvēles.
pogas_teksts stīga Nē Izvēles pogas teksts (var darboties kā paraksts vai saite).
pogas_saite stīga Nē Izvēles pogas saites URL.

Pieprasīt kravnesību, piemēram: 

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

Nosūta Viber vienreizējās paroles (OTP), izmantojot iepriekš apstiprinātu veidni.

Piezīme

Sūtot OTP ziņojumus, sending_method jāiestata uz viber_otp.

Papildu parametri:

| Parametrs | Tips | Nepieciešams | Apraksts |
| :--- | :--- | :--- | :--- |
| `veidne.id` | stīga | **Jā** | Iepriekš apstiprināts Viber OTP veidnes ID. |
| `template.lang` | stīga | **Jā** | Veidnes valodas kods (piem., "en", "uk"). |
| `template.params.pin` | stīga | **Jā** | OTP pin vērtība, kas jāievada veidnē. |
| `template.params.business_platform_name` | stīga | **Jā** | Uzņēmuma nosaukuma vietturis veidnē. |
| `template.params.code_validity_time` | stīga | **Jā** | PIN derīguma termiņš minūtēs. |

**Pieprasīt kravnesību, piemēram:**
```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
```

Nosūta interaktīvu ziņojumu kartīti, kurā ir vairāki slaidi (kartītes), kurus lietotājs var pārvilkt.

Papildu parametri:

Parametrs Tips Nepieciešams Apraksts
txt stīga Jā Karuseļa virsraksta teksts.
karuselis[N].nosaukums stīga Jā Kartes nosaukums "N" (sākot ar 0).
karuselis[N].image_url stīga Jā Kartes “N” publiskais HTTPS attēla URL.
karuselis[N].primary_label stīga Jā Kartes galvenās pogas uzraksts "N".
karuselis[N].primary_url stīga Jā Kartes “N” galvenās pogas saites URL.
karuselis[N].secondary_label stīga Nē Kartes sekundārās pogas uzraksts "N".
karuselis[N].secondary_url stīga Nē Kartes “N” sekundārās pogas saites URL.

Pieprasīt kravnesību, piemēram: 

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

Nosūta ziņojumu ar interaktīvu aptauju vai aptaujas jautājumu.

Papildu parametri:

Parametrs Tips Nepieciešams Apraksts
txt stīga Jā Aptaujas jautājuma teksts.
aptaujas_iespējas[N] stīga Jā Aptaujas opcijas teksts vienumam "N" (indekss sākas ar 0). Nepieciešamas vismaz 2 iespējas.
opcijas_veids vesels skaitlis Jā Atlasītāja veids: “1” (radiopogas) vai “2” (parastās pogas).

Pieprasīt kravnesību, piemēram: 

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

Atbildes formāts

Messagio API saderības galapunkts atgriež atbildes XML formātā ar statusa kodu "HTTP 200 OK".

Pieņemta (veiksmīga) atbilde

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

Kļūdu atbildes

Ja pieprasījuma parametru validācija neizdodas vai autentifikācija neizdodas, atbilde atgriezīs kodu, kas nav nulle.

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

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

Atzvani

Atzvanīšanas vietrāži URL ir jāievieš un jāmitina jūsu platformā. SMSBAT nosūta HTTP atzvanus, lai atjauninātu jūsu sistēmu saistībā ar piegādes notikumiem, aptauju atbildēm un lietotāju atbildēm.

1. Piegādes statusa atzvanīšana

Nosūtīts, kad ziņojuma statuss tiek mainīts (piegādāts, lasīts, neizdevās).

  • Satura veids: application/x-www-form-urlencoded
  • Metode: POSTĪT

Pieprasīt derīgās slodzes formātus:

Piegādāts: 

msg_id=MESSAGE_GUID&status=delivered
Redzēts/lasīts: 
msg_id=MESSAGE_GUID&status=delivered&type=seen
* Nepiegādāts/neizdevās: 
msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

Lauku apraksts:

  • msg_id: SMSBAT unikālais ziņojuma ID (GUID), kas atgriezts atbildē SendMessage.
  • "statuss": piegādes rezultāts ("piegādāts", "nepiegādāts" vai "statuss nav zināms").
  • Tips: iestatiet uz "redzēts", kad adresāts ir apskatījis ziņojumu.
  • "statuss_extended": konkrēts tehnisks iemesls, kāpēc statuss netiek piegādāts (piemēram, "VIBER_EXPIRED", "VIBER_BLOCKED_BY_USER", "VIBER_USER_NOT_FOUND", "VIBER_NO_DEVICE").

2. Aptaujas atbildes atzvanīšana

Aktivizējas, kad lietotājs Viber aptaujas ziņojumā atlasa atbildes opciju.

  • Satura veids: application/x-www-form-urlencoded
  • Metode: POSTĪT

Pieprasīt kravas formātu: 

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. Ienākošā lietotāja ziņojuma atzvanīšana

Aktivizējas, kad lietotājs nosūta īsziņu vai multivides atbildi atpakaļ uz jūsu Viber Business pakalpojumu.

  • Satura veids: aplikācija/json
  • Metode: POSTĪT

Pieprasīt kravas formātu: 

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

Lauku apraksts:

  • msg_id: unikālais ziņojuma ID, kas ģenerēts ienākošajai atbildei. - teksts: lietotāja nosūtītais teksta saturs (var būt nulle, ja viņš nosūtīja tikai multividi).
  • "Multivide": tiešs URL, lai lejupielādētu visus multivides pielikumus, ko nosūtījis lietotājs (var būt "null", ja tikai teksts).
  • Tālrunis: sūtītāja tālruņa numurs starptautiskā formātā.
  • sender_bm_id: Viber Business sūtītāja ID.