Preskočiť na obsah

Odoslať správu

Posielajte správy cez SMSBAT API pomocou koncového bodu /bat/messagelist.

Koncový bod

POST /bat/messagelist

Štruktúra požiadavky

Telo požiadavky je pole JSON objektov správy:

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

Parametre

Povinné parametre

Parameter Typ Popis
"od" reťazec Alfanumerické ID odosielateľa
"do" reťazec Telefónne číslo príjemcu vo formáte E.164 (napr. +380XXXXXXXXX)
"typ" reťazec Typ správy: sms, viber_promo, viber_trans, viber_carousel, viber_survey, viber_otp, rcs, flashcall
"text" reťazec Obsah správy (vyžadované pre väčšinu typov, voliteľné pre niektoré)

Voliteľné parametre

Parameter Typ Popis
customerMessageId reťazec Váš interný identifikátor na sledovanie
ttl celé číslo Čas do života v sekundách
messageData objekt Typovo špecifická konfigurácia (líši sa podľa typu správy)

Autentifikácia

Vyberte si jednu z troch metód overenia:

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

Odpoveď

Úspešná odpoveď

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

Polia odpovedí

Pole Typ Popis
messagelistId celé číslo Jedinečný identifikátor pre zoznam správ
messageId reťazec Jedinečný identifikátor pre každú správu
"stav" reťazec Stav správy: prijaté, odmietnuté, neúspešné
"časti" celé číslo Počet častí správy (pre SMS)
customerMessageId reťazec Váš interný identifikátor (ak je uvedený)
"do" reťazec Telefónne číslo príjemcu

Typy správ

SMS

Jednoduché textové správy:

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

Viber Promo

Propagačné správy s multimediálnymi údajmi:

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

Oznámenia o transakciách:

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

Viber OTP

Jednorazové upozornenia na heslo:

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

Spracovanie chýb

Stavové kódy HTTP

Kód Popis
200 Žiadosť úspešná
400 Nesprávna požiadavka – neplatné parametre
401 Neoprávnené - overenie zlyhalo
429 Príliš veľa žiadostí – prekročený limit rýchlosti
500 Interná chyba servera

Odpoveď na chybu

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

Osvedčené postupy

Formát telefónneho čísla

Pre telefónne čísla vždy používajte formát E.164:

  • ✅ Správne: +380XXXXXXXXX
  • ❌ Nesprávne: 380XXXXXXXXX, 0XXXXXXXXX

Text správy

  • Udržujte SMS do 160 znakov, aby ste sa vyhli viacerým častiam
  • Pre medzinárodné znaky použite kódovanie UTF-8
  • Pred hromadným odoslaním otestujte špeciálne znaky

TTL (Time-to-Live)

  • Nastavte vhodné TTL pre časovo citlivé správy
  • OTP správy: 300-600 sekúnd (5-10 minút)
  • Propagačné správy: 3600-86400 sekúnd (1-24 hodín)

ID správy zákazníka

  • Pre každú správu používajte jedinečné identifikátory
  • Pomáha so sledovaním a ladením
  • Užitočné pre koreláciu so záznamami vášho systému

Obmedzenia sadzieb

Kontaktujte svojho správcu účtu, ktorý vám poskytne informácie o:

  • Správy za sekundu
  • Správy za deň
  • Súbežné pripojenia

Ďalšie kroky