GMS API saderība

SMSBAT atbalsta saderības slāni ar GMS API. Tas ļauj migrēt esošās GMS integrācijas tieši uz SMSBAT, nemainot ziņojumu maršrutēšanas shēmas, slodzes struktūras vai atzvanīšanas klausītājus.

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/GMSMessage/send_message
Pieprasījuma formāts: "application/json".
Autentifikācija: HTTP pamata autentifikācija (izmanto jūsu SMSBAT API akreditācijas datus)

Pieprasīt parametrus

GMS saderības API pieņem JSON objektu ar šādiem augstākā līmeņa parametriem:

Parametrs	Tips	Nepieciešams	Apraksts
`tālruņa_numurs`	stīga	Jā	Saņēmēja tālruņa numurs starptautiskā formātā (piemēram, `380501234567`).
"atzīme"	stīga	Jā	Reģistrētais sūtītāja vārds / alfa vārds.
`kanāli`	masīvs	Jā	Izmēģināmo kanālu saraksts prioritārā secībā. Atbalstītās vērtības: "viber", "sms", "push". Piemēram, `["viber", "sms"]`.
`kanāla_opcijas`	objekts	Jā	Karte, kurā ir opcijas katram aktīvajam kanālam (skatiet tālāk).
"papildu_id"	stīga	Nē	Jūsu iekšējā klienta puses ziņojuma ID.
`atzvanīšanas_url`	stīga	Nē	Galapunkta URL jūsu sistēmā, lai saņemtu piegādes statusa atzvanīšanu.
"sadaļa_kods"	stīga	Nē	Izvēles iedalījuma koda identifikators (pēc noklusējuma “galvenais”).

Kanāla opciju iestatījumi

Objektā "channel_options" ir kanālam raksturīgas konfigurācijas.

Viber ziņojumsViber ar SMS atkāpšanosSMS ziņaViber aptaujaViber karuselisPush Message

Izmanto, ja "viber" ir norādīts "kanālu" masīvā.

Parametrs	Tips	Nepieciešams	Apraksts
`teksts`	stīga	Jā	Ziņojuma pamatteksts.
`ttl`	vesels skaitlis	Jā	Dzīves laiks sekundēs.
"img"	stīga	Nē	Parādāmā attēla publiskais HTTPS URL.
"tiksts"	stīga	Nē	Pogas teksta etiķete.
"darbība"	stīga	Nē	Galamērķa URL, noklikšķinot uz pogas.
`aptaujas_iespējas`	masīvs	Nē	Virkņu masīvs (2–5 vienumi), ko parādīt kā aptaujas opcijas.
`karuseļa_vienumi`	masīvs	Nē	Slaidu objektu masīvs, ko parādīt kā Viber karuseli (skatiet struktūru cilnē).

Viber pieprasījuma piemērs:

{
  "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"
    }
  }
}

Iespējo Viber ziņojumapmaiņu ar automātisku īsziņu atkāpšanos, ja Viber piegāde neizdodas TTL ietvaros.

Atkāpšanās pieprasījuma piemērs:

{
  "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
    }
  }
}

Izmanto, ja sms ir norādīts masīvā "kanāli".

Parametrs	Tips	Nepieciešams	Apraksts
`teksts`	stīga	Jā	Ziņojuma pamatteksts.
"alfa_nosaukums"	stīga	Jā	Sūtītāja alfa vārds.
`ttl`	vesels skaitlis	Jā	Dzīves laiks sekundēs.
`ctr`	Būla	Nē	Iespējot VKS klikšķu izsekošanu saitēm tekstā (patiess/false).

SMS pieprasījuma piemērs:

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

Izmanto, lai izveidotu Viber aptaujas un aptaujas.

Brīdinājums

Viber aptaujas konfigurācijā ir jābūt no 2 līdz 5 opcijām survey_options.

Aptaujas pieprasījuma piemērs:

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

Izmanto, lai nosūtītu pārvelkamu attēlu slaidu kartītes. Katrs slaids atbalsta attēlu, nosaukumu un pogas.

Karuseļa pieprasījuma piemērs:

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" } ] } } }

Tiek izmantots, ja “kanālu” masīvā ir norādīts “push”.

Parametrs	Tips	Nepieciešams	Apraksts
"nosaukums"	stīga	Jā	Pašpiegādes paziņojuma virsraksta teksts.
`teksts`	stīga	Jā	Ziņojuma pamatteksts.
`ttl`	vesels skaitlis	Jā	Dzīves laiks sekundēs.
"img"	stīga	Nē	Parādāmā attēla publiskais HTTPS URL.
"tiksts"	stīga	Nē	Pogas teksta etiķete.
"darbība"	stīga	Nē	Galamērķa URL, noklikšķinot uz pogas.
`ctr`	Būla	Nē	Iespējot klikšķu izsekošanu.

Push pieprasījuma piemērs:

{
  "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
    }
  }
}

Atbildes formāts

Galapunkts atgriež atbildes JSON formātā ar statusa kodu HTTP 200 OK.

Veiksmīga atbilde

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

Kļūdu atbildes

Ja validācija vai apstrāde neizdodas, tiks atgriezta kļūdas atbilde ar “ErrorCode”, kas nav nulle, un detalizēts “ErrorText”.

Neatbalstīts kanāls/opcijaNederīgu aptaujas opciju skaitsNereģistrēts alfa vārdsIekšējā apstrādes kļūda

{
  "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."
}

Atzvanīšanas piegādes formāts

Ja pieprasījumā tika norādīts “callback_url”, SMSBAT nosūta piegādes statusa atjauninājumus kā JSON POST lietderīgo slodzi jūsu galapunktam.

Atzvanīšanas pieprasījuma piemērs

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
}

Atzvanīšanas lauku apraksts

Lauks	Tips	Apraksts
"skaitlis"	stīga	Saņēmēja tālruņa numurs.
`laiks`	numurs	Notikuma laikspiedols Unix milisekundēs.
`statuss`	numurs	Vienkāršots statusa identifikators (skatiet Statusa kodu tabulu).
"apakšstatuss"	numurs	Detalizēts statusa identifikators (skatiet apakšstatusa kodu tabulu).
`hiber_statuss`	numurs	Detalizēts SMSBAT iekšējā statusa kods (skatiet hiberstatusa tabulu).
`message_id`	stīga	SMSBAT ziņojuma ID (GUID), kas ģenerēts nosūtīšanas laikā.
"papildu_id"	stīga	Klienta puses ID, kas norādīts sākotnējā pieprasījumā.
`nosūtīts_caur`	stīga	Kanāls, kas apstrādāja ziņojumu: "viber", "sms" vai "rcs".
`matching_template_id`	numurs	Viber veidnes atbilstības statuss (ja piemērojams).

Statusa kartējumi

1. Vienkāršots statuss (`statuss`)

Kods	Nozīme
"1"	Ziņa pieņemta vai tiek piegādāta.
"2"	Ziņa piegādāta.
"3"	Apstrādes vai piegādes kļūda.

2. Detalizēts statuss (apakšstatuss)

Kods	Nozīme
"12"	Pieņemts apstrādei.
"23"	Piegādāts.
"24"	Redzēts/lasīts.
"35"	Nav piegādāts TTL ietvaros (beidzies derīguma termiņš).
"36"	Piegādes kļūda.

3. Kanāla veids (`sent_via`)

Kanāls	Apraksts
`viber`	Statuss, ko rada Viber kanāls.
`sms`	Statuss, ko rada SMS kanāls.
`rcs'	Statuss, ko rada RCS kanāls.

4. Detalizēts SMSBAT statuss ("hyber_status")

Kods	Kanāls	Statuss	Apakšstatuss	Nozīme
23033	`viber`	"2"	"23"	Viber ziņa piegādāta.
24013	`viber`	"2"	"24"	Viber ziņojumu nolasīja adresāts (redzēts).
36013	`viber`	"3"	"36"	Viber iekšēja kļūda.
36023	`viber`	"3"	"36"	Nederīgs vai nepieejams Viber pakalpojuma ID.
36033	`viber`	"3"	"36"	Nederīgi Viber kravnesības dati.
36037	`viber`	"3"	"36"	Viber attēla URL ir pārāk garš.
36038	`viber`	"3"	"36"	Nederīgs Viber attēla URL.
36039	`viber`	"3"	"36"	Viber teksts ir pārāk garš.
36044	`viber`	"3"	"36"	Tukšs Viber teksts.
36053	`viber`	"3"	"36"	Neatbalstīts Viber ziņojuma veids.
36063	`viber`	"3"	"36"	Nederīgi Viber parametri.
36073	`viber`	"3"	"36"	Viber pakalpojumu sniedzēja taimauts.
36083	`viber`	"3"	"36"	Saņēmējs bloķējis Viber sūtītāju.
36093	`viber`	"3"	"36"	Adresāts nav reģistrēts kā Viber lietotājs.
36103	`viber`	"3"	"36"	Nav atrasta neviena Android/iOS ierīce ar Viber atbalstu.
36113	`viber`	"3"	"36"	Neatļauta IP adrese Viber sūtīšanai.
36123	`viber`	"3"	"36"	Konstatēts Viber ziņojuma dublikāts.
36143	`viber`	"3"	"36"	Viber norēķinu kļūda.
36153	`viber`	"3"	"36"	Ziņojumu bloķē platformas melnais saraksts.
36163	`viber`	"3"	"36"	Viber platformas iekšējās apstrādes kļūda.
36173	`viber`	"3"	"36"	Nepareiza vai trūkstoša Viber etiķete.
36183	`viber`	"3"	"36"	Nederīga Viber TTL vērtība.
12011	`sms` / `rcs`	"1"	"12"	SMS/RCS pieņemts.
36011	`sms` / `rcs`	"1"	"12"	SMS/RCS ceļā.
23011	`sms` / `rcs`	"2"	"23"	SMS/RCS piegādāts.
35015	`sms` / `rcs`	"3"	"35"	SMS/RCS derīguma termiņš beidzies (nav piegādāts TTL ietvaros).
36021	`sms` / `rcs`	"3"	"36"	SMS/RCS ziņojums izdzēsts.
36031	`sms` / `rcs`	"3"	"36"	SMS/RCS nevar piegādāt.
36041	`sms` / `rcs`	"3"	"36"	Nezināms SMS/RCS piegādes statuss.
36051	`sms` / `rcs`	"3"	"36"	SMS/RCS ziņojums noraidīts.