Skoči na vsebino

Pošlji sporočilo

Pošiljajte sporočila prek API-ja SMSBAT s končno točko /bat/messagelist.

Končna točka

POST /bat/messagelist

Struktura zahteve

Telo zahteve je niz objektov sporočila JSON:

{
  "messages": [
    {
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Your message text",
      "customerMessageId": "your-internal-id",
      "ttl": 3600
    }
  ]
}

Parametri

Zahtevani parametri

Parameter Vrsta Opis
od niz Alfanumerični ID pošiljatelja
do niz Telefonska številka prejemnika v formatu E.164 (npr. +380XXXXXXXXX)
tip niz Vrsta sporočila: sms, viber_promo, viber_trans, viber_carousel, viber_survey, viber_otp, rcs, flashcall
besedilo niz Vsebina sporočila (obvezno za večino vrst, izbirno za nekatere)

Izbirni parametri

Parameter Vrsta Opis
customerMessageId niz Vaš notranji identifikator za sledenje
ttl celo število Življenjski čas v sekundah
podatki sporočila predmet Konfiguracija, specifična za vrsto (se razlikuje glede na vrsto sporočila)

Preverjanje pristnosti

Izberite enega od treh načinov preverjanja pristnosti:

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -H "X-Authorization-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -u "@:your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'

Odgovor

Uspešen odziv

{
  "messagelistId": 123456,
  "messages": [
    {
      "messageId": "abc123def456",
      "status": "accepted",
      "parts": 1,
      "customerMessageId": "your-internal-id",
      "to": "+380XXXXXXXXX"
    }
  ]
}

Polja odgovora

Polje Vrsta Opis
messagelistId celo število Enolični identifikator za seznam sporočil
id sporočila niz Enolični identifikator za vsako sporočilo
stanje niz Status sporočila: sprejeto, zavrnjeno, neuspešno
deli celo število Število delov sporočila (za SMS)
customerMessageId niz Vaš notranji identifikator (če je na voljo)
do niz Telefonska številka prejemnika

Vrste sporočil

SMS

Preprosta besedilna sporočila:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "sms",
  "text": "Your SMS message text"
}

Viber Promo

Promocijska sporočila z obogateno predstavnostjo:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_promo",
  "text": "Check out our new product!",
  "messageData": {
    "image": "https://example.com/image.jpg",
    "button": {
      "text": "View Product",
      "url": "https://example.com/product"
    }
  }
}

Viber Transactional

Obvestila o transakcijah:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_trans",
  "text": "Your order #12345 has been confirmed"
}

Viber OTP

Obvestila o enkratnem geslu:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_otp",
  "messageData": {
    "code": "123456",
    "validity": 300
  }
}

Obravnava napak

Statusne kode HTTP

Koda Opis
200 Zahteva uspešna
400 Slaba zahteva – neveljavni parametri
401 Nepooblaščeno – preverjanje pristnosti ni uspelo
429 Preveč zahtev – omejitev stopnje je presežena
500 Notranja napaka strežnika

Odgovor na napako

{
  "error": {
    "code": "INVALID_RECIPIENT",
    "message": "Invalid phone number format"
  }
}

Najboljše prakse

Oblika telefonske številke

Za telefonske številke vedno uporabite format E.164:

  • ✅ Pravilno: +380XXXXXXXXX
  • ❌ Nepravilno: 380XXXXXXXXX, 0XXXXXXXXX

Besedilo sporočila

  • Naj bo SMS krajši od 160 znakov, da se izognete več delom
  • Uporabite kodiranje UTF-8 za mednarodne znake
  • Preizkusite posebne znake pred množičnim pošiljanjem

TTL (Time-to-Live)

  • Nastavite ustrezen TTL za časovno občutljiva sporočila
  • Sporočila OTP: 300-600 sekund (5-10 minut)
  • Promocijska sporočila: 3600-86400 sekund (1-24 ur)

ID sporočila stranke

  • Uporabite edinstvene identifikatorje za vsako sporočilo
  • Pomaga pri sledenju in odpravljanju napak
  • Uporabno za korelacijo z zapisi vašega sistema

Omejitve stopnje

Za informacije o:

  • Sporočila na sekundo
  • Sporočila na dan
  • Sočasne povezave

Naslednji koraki