GMS API Compatibility

Sinusuportahan ng SMSBAT ang isang layer ng compatibility sa GMS API. Nagbibigay-daan ito sa iyong i-migrate ang iyong mga kasalukuyang pagsasama-sama na idinisenyo para sa GMS nang direkta sa SMSBAT nang hindi kinakailangang baguhin ang iyong mga schema sa pagruruta ng mensahe, mga istruktura ng payload, o mga tagapakinig ng callback.

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/GMSMessage/send_message
Format ng Kahilingan: application/json
Authentication: HTTP Basic Authentication (gumagamit ng iyong SMSBAT API credentials)

Mga Parameter ng Kahilingan

Ang GMS compatibility API ay tumatanggap ng JSON object na may mga sumusunod na top-level na parameter:

Parameter	Uri	Kinakailangan	Paglalarawan
`numero_telepono`	string	Oo	Numero ng telepono ng tatanggap sa internasyonal na format (hal., `380501234567`).
`tag`	string	Oo	Nakarehistrong pangalan ng nagpadala / pangalan ng alpha.
`mga channel`	array	Oo	Listahan ng mga channel na susubukan, sa priority order. Mga sinusuportahang value: `viber`, `sms`, `push`. Hal., `["viber", "sms"]`.
`channel_options`	bagay	Oo	Mapa na naglalaman ng mga opsyon para sa bawat aktibong channel (tingnan sa ibaba).
`extra_id`	string	Hindi	Ang iyong internal na customer-side message ID.
`callback_url`	string	Hindi	Endpoint URL sa iyong system upang makatanggap ng mga callback sa katayuan ng paghahatid.
`division_code`	string	Hindi	Opsyonal na division code identifier (naka-default sa `pangunahin`).

Mga Setting ng Mga Pagpipilian sa Channel

Ang object na channel_options ay naglalaman ng mga configuration na tukoy sa channel.

Mensahe ng ViberViber na may SMS FallbackSMS MessageViber SurveyViber CarouselPush Message

Ginagamit kapag nakalista ang viber sa array ng channels.

Parameter	Uri	Kinakailangan	Paglalarawan
`teksto`	string	Oo	Teksto ng katawan ng mensahe.
`ttl`	integer	Oo	Time-To-Live sa ilang segundo.
`img`	string	Hindi	Pampublikong HTTPS URL ng larawang ipapakita.
`caption`	string	Hindi	Label ng text ng button.
`aksyon`	string	Hindi	Destination URL kapag na-click ang button.
`survey_options`	array	Hindi	Array ng mga string (2 hanggang 5 item) na ipapakita bilang mga opsyon sa survey.
`carousel_items`	array	Hindi	Array ng mga slide object na ipapakita bilang isang Viber carousel (tingnan ang istraktura sa tab).

Halimbawa ng Kahilingan sa Viber:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Hello from SMSBAT!",
      "ttl": 60,
      "img": "https://www.example.com/image.png",
      "caption": "Open",
      "action": "https://www.example.com"
    }
  }
}

Ine-enable ang Viber messaging na may awtomatikong SMS fallback kung nabigo ang paghahatid ng Viber sa loob ng TTL.

Halimbawa ng Fallback Request:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber", "sms"],
  "channel_options": {
    "viber": {
      "text": "Your order is ready!",
      "ttl": 60,
      "caption": "Details",
      "action": "https://www.example.com/order"
    },
    "sms": {
      "text": "Your order is ready: https://www.example.com/order",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}

Ginagamit kapag ang sms ay nakalista sa hanay ng channels.

Parameter	Uri	Kinakailangan	Paglalarawan
`teksto`	string	Oo	Teksto ng katawan ng mensahe.
`alpha_name`	string	Oo	Pangalan ng alpha ng nagpadala.
`ttl`	integer	Oo	Time-To-Live sa ilang segundo.
`ctr`	boolean	Hindi	Paganahin ang pagsubaybay sa pag-click ng CTR sa mga link sa text (`true`/`false`).

Halimbawa ng Kahilingan sa SMS:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["sms"],
  "channel_options": {
    "sms": {
      "text": "Your verification code is 1234",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}

Ginagamit upang lumikha ng mga poll at survey ng Viber.

Babala

Ang configuration ng Viber survey ay dapat na nasa pagitan ng 2 at 5 na opsyon sa loob ng survey_options.

Halimbawa ng Kahilingan sa Survey:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Please rate our service:",
      "ttl": 60,
      "survey_options": [
        "Excellent",
        "Good",
        "Bad"
      ]
    }
  }
}

Ginagamit upang magpadala ng mga na-swipeable na slide card ng imahe. Sinusuportahan ng bawat slide ang imahe, pamagat, at mga pindutan.

Halimbawa ng Kahilingan sa Carousel:

href="#__codelineno-4-1">{ "phone_number": "380501234567", "tag": "MySender", "channels": ["viber"], "channel_options": { "viber": { "text": "Choose an offer", "ttl": 60, "carousel_items": [ { "title": "Offer 1", "image_url": "https://www.example.com/offer-1.png", "primary_label": "Open", "primary_url": "https://www.example.com/offer-1", "secondary_label": "More", "secondary_url": "https://www.example.com/offers" }, { "title": "Offer 2", "image_url": "https://www.example.com/offer-2.png", "primary_label": "Open", "primary_url": "https://www.example.com/offer-2" } ] } } }

Ginagamit kapag nakalista ang push sa array ng channels.

Parameter	Uri	Kinakailangan	Paglalarawan
`pamagat`	string	Oo	Teksto ng pamagat ng push notification.
`teksto`	string	Oo	Teksto ng katawan ng mensahe.
`ttl`	integer	Oo	Time-To-Live sa ilang segundo.
`img`	string	Hindi	Pampublikong HTTPS URL ng larawang ipapakita.
`caption`	string	Hindi	Label ng text ng button.
`aksyon`	string	Hindi	Destination URL kapag na-click ang button.
`ctr`	boolean	Hindi	Paganahin ang pagsubaybay sa pag-click.

Halimbawa ng Push Request:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["push"],
  "channel_options": {
    "push": {
      "title": "Order update",
      "text": "Your order is ready for pickup!",
      "ttl": 60,
      "img": "https://www.example.com/push.png",
      "caption": "Open",
      "action": "https://www.example.com/order",
      "ctr": false
    }
  }
}

Format ng Tugon

Ang endpoint ay nagbabalik ng mga tugon sa JSON format na may HTTP 200 OK na status code.

Matagumpay na Tugon

{
  "MessageId": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "ErrorCode": null,
  "ErrorText": null
}

Mga Tugon sa Error

Kung nabigo ang pagpapatunay o pagpoproseso, isang tugon ng error na may hindi null na ErrorCode at detalyadong ErrorText ay ibabalik.

Hindi Sinusuportahang Channel/PagpipilianDi-wastong Bilang ng Opsyon sa SurveyHindi Nakarehistrong Alpha NameInternal Processing Error

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "This type of Message is not supported by the system"
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "There can be from 2 to 5 survey options."
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 400,
  "ErrorText": "Cannot send to international number: alpha name 'ALPHA' is not registered."
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 500,
  "ErrorText": "Internal server error."
}

Format ng Paghahatid ng Callback

Kung ang callback_url ay tinukoy sa kahilingan, ang SMSBAT ay nagpapadala ng mga update sa katayuan ng paghahatid bilang JSON POST payload sa iyong endpoint.

Halimbawa ng Kahilingan sa Callback

POST /your-callback-endpoint HTTP/1.1
Host: yoursystem.com
Content-Type: application/json

{
  "number": "380501234567",
  "time": 1719237600000,
  "status": 2,
  "substatus": 23,
  "hyber_status": 23033,
  "message_id": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "extra_id": "ORDER-12345",
  "sent_via": "viber",
  "matching_template_id": 0
}

Paglalarawan ng Mga Field ng Callback

Patlang	Uri	Paglalarawan
`numero`	string	Numero ng telepono ng tatanggap.
`oras`	numero	timestamp ng event sa Unix millisecond.
`status`	numero	Pinasimpleng status identifier (tingnan ang talahanayan ng Status code).
`substatus`	numero	Detalyadong status identifier (tingnan ang talahanayan ng Substatus code).
`hyber_status`	numero	Detalyadong SMSBAT internal status code (tingnan ang Hyber Status table).
`mensahe_id`	string	SMSBAT message ID (GUID) nabuo sa pagpapadala.
`extra_id`	string	Ang customer-side ID ay ibinigay sa orihinal na kahilingan.
`pinadala_sa pamamagitan ng`	string	Channel na nagproseso ng mensahe: `viber`, `sms`, o `rcs`.
`matching_template_id`	numero	Status ng pagtutugma ng template ng Viber (kung saan naaangkop).

Mga Status Mapping

1. Pinasimpleng Katayuan (`status`)

Code	Ibig sabihin
`1`	Tinanggap o inihahatid ang mensahe.
`2`	Naihatid ang mensahe.
`3`	Error sa pagproseso o paghahatid.

2. Detalyadong Katayuan (`substatus`)

Code	Ibig sabihin
`12`	Tinanggap para sa pagproseso.
`23`	Naihatid.
`24`	Nakita/nabasa.
`35`	Hindi naihatid sa loob ng TTL (Expired).
`36`	Error sa paghahatid.

3. Uri ng Channel (`pinadala_via`)

Channel	Paglalarawan
`viber`	Status na ginawa ng Viber channel.
`sms`	Katayuan na ginawa ng SMS channel.
`rcs`	Status na ginawa ng RCS channel.

4. Detalyadong Status ng SMSBAT (`hyber_status`)

Code	Channel	Katayuan	Substatus	Ibig sabihin
23033	`viber`	`2`	`23`	Naihatid ang mensahe ng Viber.
24013	`viber`	`2`	`24`	Ang mensahe ng Viber ay binasa ng tatanggap (Nakita).
36013	`viber`	`3`	`36`	Panloob na error sa Viber.
36023	`viber`	`3`	`36`	Di-wasto o hindi available ang Viber service ID.
36033	`viber`	`3`	`36`	Di-wastong data ng payload ng Viber.
36037	`viber`	`3`	`36`	Masyadong mahaba ang URL ng larawan ng Viber.
36038	`viber`	`3`	`36`	Di-wastong URL ng larawan ng Viber.
36039	`viber`	`3`	`36`	Masyadong mahaba ang Viber text.
36044	`viber`	`3`	`36`	Walang laman ang text ng Viber.
36053	`viber`	`3`	`36`	Hindi sinusuportahang uri ng mensahe ng Viber.
36063	`viber`	`3`	`36`	Di-wastong mga parameter ng Viber.
36073	`viber`	`3`	`36`	Timeout ng Viber provider.
36083	`viber`	`3`	`36`	Ang nagpadala ng Viber ay hinarang ng tatanggap.
36093	`viber`	`3`	`36`	Ang tatanggap ay hindi nakarehistro bilang isang gumagamit ng Viber.
36103	`viber`	`3`	`36`	Walang nakitang Android/iOS device na may suporta sa Viber.
36113	`viber`	`3`	`36`	Hindi awtorisadong IP address para sa pagpapadala ng Viber.
36123	`viber`	`3`	`36`	May nakitang duplicate na mensahe ng Viber.
36143	`viber`	`3`	`36`	Error sa pagsingil sa Viber.
36153	`viber`	`3`	`36`	Na-block ang mensahe ng blacklist ng platform.
36163	`viber`	`3`	`36`	Error sa panloob na pagproseso ng Viber platform.
36173	`viber`	`3`	`36`	Mali o nawawala ang label ng Viber.
36183	`viber`	`3`	`36`	Di-wastong halaga ng Viber TTL.
12011	`sms` / `rcs`	`1`	`12`	Tinanggap ang SMS/RCS.
36011	`sms` / `rcs`	`1`	`12`	SMS/RCS papunta.
23011	`sms` / `rcs`	`2`	`23`	Naihatid ang SMS/RCS.
35015	`sms` / `rcs`	`3`	`35`	Nag-expire ang SMS/RCS (hindi naihatid sa loob ng TTL).
36021	`sms` / `rcs`	`3`	`36`	Ang mensahe ng SMS/RCS ay tinanggal.
36031	`sms` / `rcs`	`3`	`36`	Hindi maihatid ang SMS/RCS.
36041	`sms` / `rcs`	`3`	`36`	Hindi kilalang katayuan ng paghahatid ng SMS/RCS.
36051	`sms` / `rcs`	`3`	`36`	Tinanggihan ang mensahe ng SMS/RCS.