Messagio API Kompatibbiltà

SMSBAT jappoġġja saff ta' kompatibilità mal-Messagio API. Dan jippermettilek temigra l-integrazzjonijiet Viber eżistenti tiegħek iddisinjati għal Messagio direttament għal SMSBAT mingħajr ma jkollok tikteb mill-ġdid l-istruttura tat-tagħbija tiegħek jew tibdel il-loġika tal-integrazzjoni.

Settings tal-Konnessjoni

Biex tgħaddi t-talbiet permezz ta' SMSBAT, aġġorna l-URL bażi u l-kredenzjali ta' awtentikazzjoni fl-integrazzjoni tiegħek:

Bażi URL: https://restapi.smsbat.com
Endpoint: POST /api/SendMessage
Format tat-Talba: application/x-www-form-urlencoded (Formola tad-Data)

Awtentikazzjoni u Kredenzjali

It-talbiet huma awtentikati bl-użu ta' parametri mibgħuta direttament fid-dejta tal-formola tal-korp tat-talba:

Parametru	Tip	Meħtieġa	Deskrizzjoni
"utent"	spag	Iva	Il-login tal-kont tiegħek SMSBAT jew l-identifikatur tal-utent.
"sinjal"	spag	Iva	API sigriet jew firma rreġistrata għall-isem tal-mittent.
"minn"	spag	Iva	Isem alfa tal-mittent irreġistrat.
`metodu_mittenti`	spag	Iva	Tip ta' kanal. Uża "viber" għal messaġġi regolari ta' Viber Business jew "viber_otp" għal mudelli Viber OTP.
`telefon`	spag	Iva	Numru tat-telefon tar-riċevitur f'format internazzjonali (eż., `380501234567`).

Tipi ta 'Messaġġ Viber

Agħżel tab hawn taħt biex tara l-parametri speċifiċi u titlob payloads għal strutturi differenti ta' messaġġi Viber:

Messaġġ ta' TestTest + ButtonMessaġġ tal-ImmaġiniTest + Immaġni + ButtunaMessaġġ VideoMudell OTP

Tibgħat messaġġ sempliċi.

Parametri addizzjonali:

Parametru	Tip	Meħtieġa	Deskrizzjoni
`txt`	spag	Iva	Test tal-messaġġ.

Talba Eżempju ta' Tagħbija:

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

Tibgħat messaġġ b'buttuna interattiva ta' sejħa għall-azzjoni.

Parametri addizzjonali:

Parametru	Tip	Meħtieġa	Deskrizzjoni
`txt`	spag	Iva	Test tal-messaġġ.
`button_test`	spag	Iva	Test muri fuq il-buttuna.
`button_link`	spag	Iva	URL tad-destinazzjoni meta l-buttuna tiġi kklikkjata.

Talba Eżempju ta' Tagħbija:

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

Tibgħat fajl immaġni pubbliku.

Parametri addizzjonali:

Parametru	Tip	Meħtieġa	Deskrizzjoni
`link_immaġni`	spag	Iva	URL HTTPS pubbliku tal-immaġni.
`txt`	spag	Le	Test tal-titoli mhux obbligatorju biex jintwera taħt l-immaġni.

Talba Eżempju ta' Tagħbija:

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

Tibgħat karta rikka li fiha test, immaġni, u buttuna.

Parametri addizzjonali:

Parametru	Tip	Meħtieġa	Deskrizzjoni
`txt`	spag	Iva	Test tal-titoli.
`link_immaġni`	spag	Iva	URL HTTPS pubbliku tal-immaġni.
`button_test`	spag	Iva	Test muri fuq il-buttuna.
`button_link`	spag	Iva	URL tad-destinazzjoni meta l-buttuna tiġi kklikkjata.

Talba Eżempju ta' Tagħbija:

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

Tibgħat fajl tal-vidjo b'caption ta' test fakultattiv u buttuni ta' azzjoni.

Parametri addizzjonali:

Parametru	Tip	Meħtieġa	Deskrizzjoni
`video.url`	spag	Iva	URL HTTPS pubbliku tal-fajl tal-vidjo.
`video.thumbnail`	spag	Iva	URL HTTPS pubbliku tal-immaġni tal-preview tal-vidjo.
`video.size_mb`	numru sħiħ	Iva	Daqs approssimattiv tal-fajl tal-vidjo f'Megabytes.
`video.duration_sec`	numru sħiħ	Iva	Tul tal-vidjo f'sekondi.
`txt`	spag	Le	Test ta' deskrizzjoni fakultattiv.
`button_test`	spag	Le	Test tal-buttuna mhux obbligatorju (jista' jaġixxi bħala caption jew link).
`button_link`	spag	Le	URL tal-link tal-buttuna fakultattiva.

Talba Eżempju ta' Tagħbija:

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

Tibgħat Viber One-Time Passwords (OTP) billi tuża mudell approvat minn qabel.

Nota

Meta tibgħat messaġġi OTP, trid issettja sending_method għal viber_otp.

Parametri addizzjonali:

| Parametru | Tip | Meħtieġa | Deskrizzjoni |
| :--- | :--- | :--- | :--- |
| `template.id` | spag | **Iva** | Viber OTP template ID approvat minn qabel. |
| `template.lang` | spag | **Iva** | Kodiċi tal-lingwa tal-mudell (eż., `en`, `uk`). |
| `template.params.pin` | spag | **Iva** | Il-valur tal-pin OTP biex tinjetta fil-mudell. |
| `template.params.business_platform_name` | spag | **Iva** | Il-post tal-isem tan-negozju fil-mudell. |
| `template.params.code_validity_time` | spag | **Iva** | Perjodu ta' validità tal-PIN f'minuti. |

**Talba Eżempju ta' Tagħbija:**
```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
```

Messaġġ tal-karużellMessaġġ ta' Stħarriġ

Tibgħat karta ta' messaġġ interattiva li fiha slajds multipli (kards) li l-utent jista' jgħaddi minnha.

Parametri addizzjonali:

Parametru	Tip	Meħtieġa	Deskrizzjoni
`txt`	spag	Iva	Test tat-titolu tal-karużell.
`karużell[N].titolu`	spag	Iva	Titolu tal-karta "N" (li tibda minn 0).
`carousel[N].image_url`	spag	Iva	URL tal-immaġni HTTPS pubbliku tal-karta "N".
`carousel[N].primary_label`	spag	Iva	It-titlu tal-buttuna prinċipali tal-karta "N".
`carousel[N].primary_url`	spag	Iva	URL tal-link tal-buttuna prinċipali tal-karta "N".
`carousel[N].secondary_label`	spag	Le	Titoli tal-buttuna sekondarja tal-karta "N".
`carousel[N].secondary_url`	spag	Le	Link tal-buttuna sekondarja URL tal-karta "N".

Talba Eżempju ta' Tagħbija:

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

Tibgħat messaġġ li jkun fih stħarriġ interattiv jew mistoqsija ta' stħarriġ.

Parametri addizzjonali:

Parametru	Tip	Meħtieġa	Deskrizzjoni
`txt`	spag	Iva	Test tal-mistoqsija tal-istħarriġ.
`għażliet_istħarriġ[N]`	spag	Iva	Test tal-għażla tal-istħarriġ għall-oġġett "N" (indiċi li jibda minn 0). Mill-inqas 2 għażliet huma meħtieġa.
`option_type`	numru sħiħ	Iva	Tip ta' selettur: "1" (RadioButtons) jew "2" (Butuni regolari).

Talba Eżempju ta' Tagħbija:

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

Format ta’ Rispons

L-endpoint tal-kompatibilità tal-API Messagio jirritorna tweġibiet f'format XML b'kodiċi tal-istatus HTTP 200 OK.

Rispons Aċċettat (Suċċess).

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

Risposti għal Żbalji

Jekk il-validazzjoni tal-parametri tat-talba tfalli jew l-awtentikazzjoni tfalli, ir-rispons se jirritorna kodiċi mhux żero.

Firma nieqsaMhux awtorizzat

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

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

Sejħiet lura

L-URLs ta' callback iridu jiġu implimentati u ospitati fuq il-pjattaforma tiegħek. SMSBAT jibgħat callbacks HTTP biex taġġorna s-sistema tiegħek rigward l-avvenimenti tal-kunsinna, it-tweġibiet tal-istħarriġ, u t-tweġibiet tal-utenti.

1. Callback tal-Istatus ta' Kunsinna

Mibgħut meta messaġġ jaqleb l-istatus (konsenjat, moqri, falla).

Content-Type: application/x-www-form-urlencoded
Metodu: POST

Itlob Formati tat-Tagħbija:

Kkonsenjat:
```
msg_id=MESSAGE_GUID&status=delivered
```

Ara/Aqra:

msg_id=MESSAGE_GUID&status=delivered&type=seen

Ma twasslux / falliet:

msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

Deskrizzjoni tal-Oqsma:

msg_id: SMSBAT uniku messaġġ ID (GUID) lura fir-rispons SendMessage.
status: Riżultat tal-kunsinna (konsenjat, mhux ikkonsenjat, jew istatus mhux magħruf).
tip: Issettjat għal `dehra' meta l-messaġġ ikun rawh min jirċievi.
status_extended: Raġuni teknika speċifika għall-istatus mhux imwassal (eż. VIBER_EXPIRED, VIBER_BLOCKED_BY_USER, VIBER_USER_NOT_FOUND, VIBER_NO_DEVICE).

2. Tweġiba għall-Istħarriġ

Tqanqal meta utent jagħżel għażla ta' rispons f'messaġġ ta' Viber Survey.

Content-Type: application/x-www-form-urlencoded
Metodu: POST

Format tat-Tagħbija tat-Talba:

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. Callback tal-Messaġġ tal-Utent Deħlin

Tqanqal meta utent jibgħat tweġiba ta' test jew tal-midja lura lis-servizz Viber Business tiegħek.

Kontenut-Tip: applikazzjoni/json
Metodu: POST

Format tat-Tagħbija tat-Talba:

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

Deskrizzjoni tal-Oqsma:

msg_id: L-ID uniku tal-messaġġ iġġenerat għat-tweġiba deħlin.
test: Kontenut tat-test mibgħut mill-utent (jista' jkun 'null' jekk bagħtu midja biss).
media: URL dirett biex tniżżel kwalunkwe attachments tal-midja mibgħuta mill-utent (jista 'jkun 'null' jekk test biss).
telefon: In-numru tat-telefon tal-mittent f'format internazzjonali.
sender_bm_id: L-ID tal-mittent ta' Viber Business.