Přeskočit obsah

Odeslat zprávu

Odesílejte zprávy přes SMSBAT API pomocí koncového bodu /bat/messagelist.

Koncový bod

POST /bat/messagelist

Struktura požadavku

Tělo požadavku je pole JSON objektů zpráv:

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

Parametry

Požadované parametry

Parametr Typ Popis
"od" řetězec Alfanumerické ID odesílatele
do řetězec Telefonní číslo příjemce ve formátu E.164 (např. +380XXXXXXXXX)
"typ" řetězec Typ zprávy: sms, viber_promo, viber_trans, viber_carousel, viber_survey, viber_otp, rcs, flashcall
"text" řetězec Obsah zprávy (vyžadováno pro většinu typů, volitelně pro některé)

Volitelné parametry

Parametr Typ Popis
customerMessageId řetězec Váš interní identifikátor pro sledování
ttl celé číslo Doba žití v sekundách
messageData objekt Typově specifická konfigurace (liší se podle typu zprávy)

Autentizace

Vyberte jednu ze tří metod ověření:

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

Odpověď

Úspěšná odpověď

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

Pole odpovědí

Pole Typ Popis
messagelistId celé číslo Jedinečný identifikátor pro seznam zpráv
ID zprávy řetězec Jedinečný identifikátor pro každou zprávu
"stav" řetězec Stav zprávy: přijato, zamítnuto, neúspěšné
"díly" celé číslo Počet částí zprávy (pro SMS)
customerMessageId řetězec Váš interní identifikátor (pokud je uveden)
do řetězec Telefonní číslo příjemce

Typy zpráv

SMS

Jednoduché textové zprávy:

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

Promo akce Viber

Propagační zprávy s multimédii:

{
  "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 Transakční

Oznámení o transakci:

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

Viber OTP

Jednorázová upozornění na heslo:

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

Zpracování chyb

Stavové kódy HTTP

Kód Popis
200 Žádost byla úspěšná
400 Špatný požadavek - neplatné parametry
401 Neautorizováno - ověření se nezdařilo
429 Příliš mnoho požadavků – překročen limit rychlosti
500 Interní chyba serveru

Odpověď na chybu

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

Nejlepší postupy

Formát telefonního čísla

Pro telefonní čísla vždy používejte formát E.164:

  • ✅ Správně: +380XXXXXXXXX
  • ❌ Nesprávné: 380XXXXXXXXX, 0XXXXXXXXX

Text zprávy

  • Udržujte SMS kratší než 160 znaků, abyste se vyhnuli více částí
  • Pro mezinárodní znaky použijte kódování UTF-8
  • Před hromadným odesláním otestujte speciální znaky

TTL (Time-to-Live)

  • Nastavte vhodné TTL pro časově citlivé zprávy
  • OTP zprávy: 300-600 sekund (5-10 minut)
  • Propagační zprávy: 3600-86400 sekund (1-24 hodin)

ID zprávy zákazníka

  • Používejte jedinečné identifikátory pro každou zprávu
  • Pomáhá se sledováním a laděním
  • Užitečné pro korelaci se záznamy vašeho systému

Limity sazeb

Kontaktujte svého správce účtu pro informace o:

  • Zprávy za sekundu
  • Zprávy za den
  • Souběžná připojení

Další kroky