Hyppää sisältöön

Lähetä viesti

Lähetä viestejä SMSBAT-sovellusliittymän kautta käyttämällä /bat/messagelist-päätepistettä.

Päätepiste

POST /bat/messagelist

Pyyntörakenne

Pyynnön runko on JSON-joukko viestiobjekteja:

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

Parametrit

Pakolliset parametrit

Parametri Tyyppi Kuvaus
"alkaen" merkkijono Aakkosnumeerinen lähettäjän tunnus
"to" merkkijono Vastaanottajan puhelinnumero E.164-muodossa (esim. +380XXXXXXXXX)
"tyyppi" merkkijono Viestityyppi: "sms", "viber_promo", "viber_trans", "viber_carousel", "viber_survey", "viber_otp", "rcs", "flashcall"
"teksti" merkkijono Viestin sisältö (pakollinen useimmille tyypeille, valinnainen joillekin)

Valinnaiset parametrit

Parametri Tyyppi Kuvaus
customerMessageId merkkijono Sisäinen tunniste seurantaa varten
ttl kokonaisluku Elinaika sekunneissa
messageData esine Tyyppikohtainen kokoonpano (vaihtelee sanomatyypin mukaan)

Todennus

Valitse yksi kolmesta todennustavasta:

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

Vastaus

Menestysvastaus

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

Vastauskentät

Kenttä Tyyppi Kuvaus
messagelistId kokonaisluku Viestiluettelon yksilöivä tunniste
"messageId" merkkijono Jokaisen viestin yksilöllinen tunniste
"tila" merkkijono Viestin tila: "hyväksytty", "hylätty", "epäonnistunut"
"osat" kokonaisluku Viestin osien lukumäärä (tekstiviestille)
customerMessageId merkkijono Sisäinen tunniste (jos sellainen on)
"to" merkkijono Vastaanottajan puhelinnumero

Viestityypit

SMS

Yksinkertaiset tekstiviestit:

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

Viber Promo

Mainosviestit multimedian kanssa:

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

Tapahtumailmoitukset:

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

Viber OTP

Kertaluonteiset salasanailmoitukset:

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

Virheiden käsittely

HTTP-tilakoodit

Koodi Kuvaus
200 Pyyntö onnistui
400 Virheellinen pyyntö – virheelliset parametrit
401 Luvaton – todennus epäonnistui
429 Liian monta pyyntöä – määräraja ylitetty
500 Sisäinen palvelinvirhe

Virhevastaus

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

Parhaat käytännöt

Puhelinnumeron muoto

Käytä aina E.164-muotoa puhelinnumeroissa:

  • ✅ Oikein: +380XXXXXXXXX
  • ❌ Väärin: "380XXXXXXXXX", "0XXXXXXXXX".

Viestiteksti

  • Pidä tekstiviesti alle 160 merkin pituisena välttääksesi useita osia
  • Käytä UTF-8-koodausta kansainvälisille merkeille
  • Testaa erikoismerkkejä ennen joukkolähetystä

TTL (Time-to-Live)

  • Aseta oikea TTL aikaherkille viesteille
  • OTP-viestit: 300-600 sekuntia (5-10 minuuttia)
  • Kampanjaviestit: 3600-86400 sekuntia (1-24 tuntia)

Asiakasviestin tunnus

  • Käytä yksilöllisiä tunnisteita jokaiselle viestille
  • Auttaa seurannassa ja virheenkorjauksessa
  • Hyödyllinen korreloitaessa järjestelmäsi tietueita

Hintarajoitukset

Ota yhteyttä tilivastaavaasi saadaksesi lisätietoja:

  • Viestiä sekunnissa
  • Viestiä päivässä
  • Samanaikaiset yhteydet

Seuraavat vaiheet