Kalo te përmbajtja

Messagio Compatibility

Përputhshmëria # Messagio API

SMSBAT mbështet një shtresë përputhshmërie me Messagio API. Kjo ju lejon të migroni integrimet tuaja ekzistuese të Viber të krijuara për Messagio direkt në SMSBAT pa pasur nevojë të rishkruani strukturën tuaj të ngarkesës ose të ndryshoni logjikën e integrimit.

Cilësimet e lidhjes

Për të drejtuar kërkesat përmes SMSBAT, përditësoni URL-në bazë dhe kredencialet e vërtetimit në integrimin tuaj:

  • URL bazë: https://restapi.smsbat.com
  • Pika e fundit: POST /api/SendMessage
  • Formati i kërkesës: application/x-www-form-urlencoded (Të dhënat e formularit)

Autentifikimi dhe Kredencialet

Kërkesat vërtetohen duke përdorur parametrat e dërguar direkt brenda të dhënave të formularit të trupit të kërkesës:

Parametri Lloji Kërkohet Përshkrimi
përdorues varg **Po ** Hyrja në llogarinë tuaj SMSBAT ose identifikuesi i përdoruesit.
shenjë varg **Po ** Sekreti API ose nënshkrimi i regjistruar për emrin e dërguesit.
nga varg **Po ** Emri alfa i dërguesit të regjistruar.
metoda_dërguese varg **Po ** Lloji i kanalit. Përdorni 'viber' për mesazhet e zakonshme të Viber Business ose 'viber_otp' për shabllonet Viber OTP.
telefon varg **Po ** Numri i telefonit të marrësit në format ndërkombëtar (p.sh., 380501234567).

Llojet e mesazheve Viber

Zgjidhni një skedë më poshtë për të parë parametrat specifikë dhe për të kërkuar ngarkesa për struktura të ndryshme të mesazheve Viber:

Dërgon një mesazh të thjeshtë me tekst.

Parametrat shtesë:

Parametri Lloji Kërkohet Përshkrimi
txt varg **Po ** Teksti i mesazhit.

Kërkoni një shembull të ngarkesës: 

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

Dërgon një mesazh me tekst me një buton interaktiv thirrjeje për veprim.

Parametrat shtesë:

Parametri Lloji Kërkohet Përshkrimi
txt varg **Po ** Teksti i mesazhit.
text_button varg **Po ** Teksti shfaqet në buton.
"button_link" varg **Po ** URL-ja e destinacionit kur klikohet butoni.

Kërkoni një shembull të ngarkesës: KODI_BLOCK_1

Dërgon një skedar imazhi publik.

Parametrat shtesë:

Parametri Lloji Kërkohet Përshkrimi
lidhja_imazhi varg **Po ** URL-ja publike HTTPS e imazhit.
txt varg Jo Teksti opsional i titrave për t'u shfaqur poshtë imazhit.

Kërkoni një shembull të ngarkesës: 

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

Dërgon një kartë të pasur që përmban tekst, një imazh dhe një buton.

Parametrat shtesë:

Parametri Lloji Kërkohet Përshkrimi
txt varg **Po ** Teksti i mbishkrimit.
lidhja_imazhi varg **Po ** URL-ja publike HTTPS e imazhit.
text_button varg **Po ** Teksti shfaqet në buton.
"button_link" varg **Po ** URL-ja e destinacionit kur klikohet butoni.

Kërkoni një shembull të ngarkesës: KODI_BLOCK_3

Dërgon një skedar video me një titull teksti opsional dhe butona veprimi.

Parametrat shtesë:

Parametri Lloji Kërkohet Përshkrimi
video.url varg **Po ** URL-ja publike HTTPS e skedarit video.
video.miniaturë varg **Po ** URL-ja publike HTTPS e imazhit të pamjes paraprake të videos.
video.madhësia_mb numër i plotë **Po ** Madhësia e përafërt e skedarit të videos në Megabajt.
video.kohëzgjatja_sek numër i plotë **Po ** Kohëzgjatja e videos në sekonda.
txt varg Jo Teksti opsional i përshkrimit.
text_button varg Jo Teksti opsional i butonit (mund të veprojë si titull ose lidhje).
"button_link" varg Jo URL-ja e lidhjes së butonit opsional.

Kërkoni një shembull të ngarkesës: 

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

Dërgon fjalëkalime një herë në Viber (OTP) duke përdorur një shabllon të miratuar paraprakisht.

Shënim

Kur dërgoni mesazhe OTP, duhet të vendosni metodën e dërgimit në viber_otp.

Parametrat shtesë:

| Parametri | Lloji | Kërkohet | Përshkrimi |
| :--- | :--- | :--- | :--- |
| `shabllon.id` | varg | **Po ** | ID-ja e shabllonit të Viber OTP e miratuar paraprakisht. |
| `shabllon.gjuh` | varg | **Po ** | Kodi i gjuhës së modelit (p.sh., `en`, `uk`). |
| "shabllon.params.pin" | varg | **Po ** | Vlera e pinit OTP për të injektuar në shabllon. |
| "template.params.emri_platformës_biznesit" | varg | **Po ** | Mbajtësja e emrit të biznesit në shabllon. |
| "template.params.code_validity_time" | varg | **Po ** | Periudha e vlefshmërisë PIN në minuta. |

**Kërkoni një shembull të ngarkesës:**
```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
```

Dërgon një kartë mesazhi interaktive që përmban rrëshqitje (karta) të shumta që përdoruesi mund t'i rrëshqasë.

Parametrat shtesë:

Parametri Lloji Kërkohet Përshkrimi
txt varg **Po ** Teksti i titullit të karuselit.
carousel[N].titull varg **Po ** Titulli i kartës 'N' (duke filluar nga 0).
carousel[N].image_url varg **Po ** URL-ja e imazhit publik HTTPS të kartës 'N'.
carousel[N].etiketa_primare varg **Po ** Titulli i butonit kryesor të kartës "N".
carousel[N].url_primare varg **Po ** URL-ja e lidhjes së butonit kryesor të kartës 'N'.
carousel[N].etiketa_sekondare varg Jo Titulli i butonit dytësor i kartës "N".
carousel[N].url_secondary varg Jo URL-ja e lidhjes së butonit dytësor të kartës "N".

Kërkoni një shembull të ngarkesës: 

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

Dërgon një mesazh që përmban një anketë interaktive ose pyetje.

Parametrat shtesë:

Parametri Lloji Kërkohet Përshkrimi
txt varg **Po ** Teksti i pyetjes së anketës.
opsionet e_anketës[N] varg **Po ** Teksti i opsionit të anketës për artikullin "N" (indeksi duke filluar nga 0). Kërkohen të paktën 2 opsione.
"lloji_opsioni" numër i plotë **Po ** Lloji i përzgjedhësit: 1 (RadioButtons) ose 2 (Butonat e rregullt).

Kërkoni një shembull të ngarkesës: 

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

Formati i përgjigjes

Pika përfundimtare e përputhshmërisë së Messagio API kthen përgjigjet në format XML me një kod statusi HTTP 200 OK.

Përgjigja e pranuar (Suksese).

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

Përgjigjet e gabimit

Nëse vërtetimi i parametrave të kërkesës dështon ose vërtetimi dështon, përgjigja do të kthejë një kod jo zero.

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

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

Thirrje

URL-të e kthimit të thirrjes duhet të implementohen dhe të strehohen në platformën tuaj. SMSBAT dërgon kthime thirrjesh HTTP për të përditësuar sistemin tuaj në lidhje me ngjarjet e dorëzimit, përgjigjet e sondazhit dhe përgjigjet e përdoruesve.

1. Rikthimi i telefonatës për statusin e dorëzimit

Dërgohet kur një mesazh kalon statusin (i dorëzuar, lexuar, dështuar).

  • Lloji i përmbajtjes: application/x-www-form-urlencoded
  • Metoda: POST

Kërkoni formatet e ngarkesës:

  • Dorëzuar: 
    msg_id=MESSAGE_GUID&status=delivered
  • Shikuar/lexuar: 
    msg_id=MESSAGE_GUID&status=delivered&type=seen
  • E padorëzuar / Dështuar: 
    msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

Përshkrimi i fushave:

  • msg_id: ID-ja unike e mesazhit SMSBAT (GUID) u kthye në përgjigjen SendMessage.
  • 'status': Rezultati i dorëzimit ('i dorëzuar', 'i padorëzuar' ose 'statusi i panjohur').
  • "Lloji": Cakto të "shihet" kur mesazhi është parë nga marrësi.
  • "status_extended": Arsye teknike specifike për statusin e padorëzuar (p.sh. "VIBER_EXPIRED", "VIBER_BLOCKED_BY_USER", "VIBER_USER_NOT_FOUND", "VIBER_NO_DEVICE").

2. Përgjigjja e anketës Callback

Aktivizohet kur një përdorues zgjedh një opsion përgjigjeje në një mesazh Viber Survey.

  • Lloji i përmbajtjes: application/x-www-form-urlencoded
  • Metoda: POST

Kërkoni formatin e ngarkesës: 

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. Kthimi i mesazhit të përdoruesit në hyrje

Aktivizohet kur një përdorues dërgon një përgjigje me tekst ose media në shërbimin tuaj Viber Business.

  • Lloji i përmbajtjes: application/json
  • Metoda: POST

Kërkoni formatin e ngarkesës: 

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

Përshkrimi i fushave:

  • msg_id: ID unike e mesazhit e krijuar për përgjigjen hyrëse.
  • tekst: Përmbajtja e tekstit e dërguar nga përdoruesi (mund të jetë null nëse ai dërgon vetëm media).
  • media: URL e drejtpërdrejtë për të shkarkuar çdo bashkëngjitje të medias të dërguar nga përdoruesi (mund të jetë 'null' nëse vetëm tekst).
  • telefon: Numri i telefonit të dërguesit në format ndërkombëtar.
  • sender_bm_id: ID-ja e dërguesit të Viber Business.