Messagio API Compatibility

Sinusuportahan ng SMSBAT ang isang layer ng compatibility sa Messagio API. Nagbibigay-daan ito sa iyong i-migrate ang iyong mga umiiral nang Viber integration na idinisenyo para sa Messagio nang direkta sa SMSBAT nang hindi kinakailangang muling isulat ang iyong payload structure o baguhin ang integration logic.

Mga Setting ng Koneksyon

Upang iruta ang mga kahilingan sa pamamagitan ng SMSBAT, i-update ang base URL at mga kredensyal sa pagpapatunay sa iyong pagsasama:

Base URL: https://restapi.smsbat.com
Endpoint: POST /api/SendMessage
Format ng Kahilingan: application/x-www-form-urlencoded (Data ng Form)

Pagpapatotoo at Mga Kredensyal

Ang mga kahilingan ay pinatotohanan gamit ang mga parameter na direktang ipinadala sa loob ng data ng form ng katawan ng kahilingan:

Parameter	Uri	Kinakailangan	Paglalarawan
`user`	string	Oo	Ang iyong SMSBAT account login o user identifier.
`sign`	string	Oo	API secret o signature na nakarehistro para sa pangalan ng nagpadala.
`mula sa`	string	Oo	Alpha name ng rehistradong nagpadala.
`paraan ng_pagpapadala`	string	Oo	Uri ng channel. Gumamit ng `viber` para sa mga regular na mensahe ng Viber Business o `viber_otp` para sa mga template ng Viber OTP.
`telepono`	string	Oo	Numero ng telepono ng tatanggap sa internasyonal na format (hal., `380501234567`).

Mga Uri ng Mensahe ng Viber

Pumili ng tab sa ibaba upang tingnan ang mga partikular na parameter at humiling ng mga payload para sa iba't ibang istruktura ng mensahe ng Viber:

Text MessageText + ButtonMensahe ng LarawanText + Imahe + ButtonMensahe sa VideoOTP Template

Nagpapadala ng simpleng text message.

Mga Karagdagang Parameter:

Parameter	Uri	Kinakailangan	Paglalarawan
`txt`	string	Oo	Text ng mensahe.

Halimbawa ng Paghiling ng Payload:

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

Nagpapadala ng text message na may interactive na call-to-action na button.

Mga Karagdagang Parameter:

Parameter	Uri	Kinakailangan	Paglalarawan
`txt`	string	Oo	Text ng mensahe.
`button_text`	string	Oo	Ipinapakita ang teksto sa pindutan.
`button_link`	string	Oo	Destination URL kapag na-click ang button.

Humiling ng Payload Halimbawa:

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

Nagpapadala ng pampublikong file ng imahe.

Mga Karagdagang Parameter:

Parameter	Uri	Kinakailangan	Paglalarawan
`image_link`	string	Oo	Pampublikong HTTPS URL ng larawan.
`txt`	string	Hindi	Opsyonal na caption text na ipapakita sa ibaba ng larawan.

Humiling ng Payload Halimbawa:

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

Nagpapadala ng rich card na naglalaman ng text, isang imahe, at isang button.

Mga Karagdagang Parameter:

Parameter	Uri	Kinakailangan	Paglalarawan
`txt`	string	Oo	Teksto ng caption.
`image_link`	string	Oo	Pampublikong HTTPS URL ng larawan.
`button_text`	string	Oo	Ipinapakita ang teksto sa pindutan.
`button_link`	string	Oo	Destination URL kapag na-click ang button.

Humiling ng Payload Halimbawa:

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

Nagpapadala ng video file na may opsyonal na text caption at action button.

Mga Karagdagang Parameter:

Parameter	Uri	Kinakailangan	Paglalarawan
`video.url`	string	Oo	Pampublikong HTTPS URL ng video file.
`video.thumbnail`	string	Oo	Pampublikong HTTPS URL ng larawan ng preview ng video.
`video.size_mb`	integer	Oo	Tinatayang laki ng video file sa Megabytes.
`video.duration_sec`	integer	Oo	Ang tagal ng video sa mga segundo.
`txt`	string	Hindi	Opsyonal na teksto ng paglalarawan.
`button_text`	string	Hindi	Opsyonal na text ng button (maaaring kumilos bilang isang caption o link).
`button_link`	string	Hindi	Opsyonal na URL ng link ng button.

Humiling ng Payload Halimbawa:

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

Nagpapadala ng Viber One-Time Passwords (OTP) gamit ang isang paunang inaprubahang template.

Tala

Kapag nagpapadala ng mga mensaheng OTP, dapat mong itakda ang sending_method sa viber_otp.

Mga Karagdagang Parameter:

| Parameter | Uri | Kinakailangan | Paglalarawan |
| :--- | :--- | :--- | :--- |
| `template.id` | string | **Oo** | Pre-approved Viber OTP template ID. |
| `template.lang` | string | **Oo** | Code ng wika ng template (hal., `en`, `uk`). |
| `template.params.pin` | string | **Oo** | Ang halaga ng OTP pin na i-inject sa template. |
| `template.params.business_platform_name` | string | **Oo** | Ang placeholder ng pangalan ng negosyo sa template. |
| `template.params.code_validity_time` | string | **Oo** | Panahon ng bisa ng PIN sa ilang minuto. |

**Humiling ng Payload Halimbawa:**
```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
```

Mensahe ng CarouselMensahe ng Survey

Nagpapadala ng interactive na message card na naglalaman ng maraming slide (mga card) na maaaring i-swipe ng user.

Mga Karagdagang Parameter:

Parameter	Uri	Kinakailangan	Paglalarawan
`txt`	string	Oo	Teksto ng pamagat ng carousel.
`carousel[N].title`	string	Oo	Pamagat ng card `N` (nagsisimula sa 0).
`carousel[N].image_url`	string	Oo	Pampublikong HTTPS image URL ng card `N`.
`carousel[N].pangunahing_label`	string	Oo	Pangunahing button na caption ng card na `N`.
`carousel[N].pangunahing_url`	string	Oo	URL ng link ng main button ng card `N`.
`carousel[N].pangalawang_label`	string	Hindi	Pangalawang button na caption ng card na `N`.
`carousel[N].secondary_url`	string	Hindi	URL ng link ng pangalawang button ng card `N`.

Humiling ng Payload Halimbawa:

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

Nagpapadala ng mensahe na naglalaman ng interactive na poll o survey na tanong.

Mga Karagdagang Parameter:

Parameter	Uri	Kinakailangan	Paglalarawan
`txt`	string	Oo	Teksto ng tanong sa survey.
`survey_options[N]`	string	Oo	Text ng opsyon sa survey para sa item na `N` (index na nagsisimula sa 0). Hindi bababa sa 2 opsyon ang kinakailangan.
`type_option`	integer	Oo	Uri ng selector: `1` (RadioButtons) o `2` (regular Buttons).

Humiling ng Payload Halimbawa:

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 ng Tugon

Ang endpoint ng compatibility ng Messagio API ay nagbabalik ng mga tugon sa XML format na may status code na HTTP 200 OK.

Tinanggap (Tagumpay) na Tugon

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

Mga Tugon sa Error

Kung nabigo ang pagpapatunay ng mga parameter ng kahilingan o nabigo ang pagpapatunay, magbabalik ang tugon ng isang hindi zero na code.

Nawawalang LagdaHindi awtorisado

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

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

Mga callback

Dapat ipatupad at i-host ang mga callback URL sa iyong platform. Nagpapadala ang SMSBAT ng mga HTTP callback upang i-update ang iyong system tungkol sa mga kaganapan sa paghahatid, mga tugon sa survey, at mga tugon ng user.

1. Callback ng Katayuan ng Paghahatid

Ipinadala kapag ang isang mensahe ay lumipat sa katayuan (naihatid, nabasa, nabigo).

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

Humiling ng Mga Format ng Payload:

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

Nakita/Nabasa:

msg_id=MESSAGE_GUID&status=delivered&type=seen

Hindi naihatid / Nabigo:

msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

Deskripsyon ng Field:

msg_id: SMSBAT unique message ID (GUID) ibinalik sa SendMessage na tugon.
status: Delivery outcome (delivered, undelivered, o status unknown).
type: Itakda sa nakita kapag ang mensahe ay tiningnan ng tatanggap.
status_extended: Partikular na teknikal na dahilan para sa hindi naihatid na status (hal. VIBER_EXPIRED, VIBER_BLOCKED_BY_USER, VIBER_USER_NOT_FOUND, VIBER_NO_DEVICE).

2. Sagutin ng Survey ang Callback

Na-trigger kapag pumili ang isang user ng opsyon sa pagtugon sa isang mensahe ng Viber Survey.

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

Humiling ng Payload Format:

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. Papasok na User Message Callback

Na-trigger kapag nagpadala ang isang user ng text o media reply pabalik sa iyong serbisyo ng Viber Business.

Content-Type: application/json
Paraan: POST

Humiling ng Payload Format:

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

Deskripsyon ng Field:

msg_id: Ang natatanging message ID na nabuo para sa papasok na tugon.
text: Text content na ipinadala ng user (maaaring null kung nagpadala lang sila ng media).
media: Direktang URL para mag-download ng anumang media attachment na ipinadala ng user (maaaring null kung text lang).
telepono: Ang numero ng telepono ng nagpadala sa internasyonal na format.
sender_bm_id: Ang Viber Business sender ID.