Sari la conținut

Trimite mesaj

Trimiteți mesaje prin SMSBAT API folosind punctul final /bat/messagelist.

Punct final

POST /bat/messagelist

Structura cererii

Corpul cererii este o matrice JSON de obiecte mesaj:

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

Parametri

Parametri obligatorii

Parametru Tip Descriere
din șir ID alfanumeric al expeditorului
la șir Numărul de telefon al destinatarului în format E.164 (de ex., +380XXXXXXXXX)
tip șir Tip mesaj: sms, viber_promo, viber_trans, viber_carousel, viber_survey, viber_otp, rcs, flashcall
text șir Conținutul mesajului (necesar pentru majoritatea tipurilor, opțional pentru unele)

Parametri opționali

Parametru Tip Descriere
customerMessageId șir Identificatorul dvs. intern pentru urmărire
ttl întreg Timp de viață în secunde
messageData obiect Configurație specifică tipului (variază în funcție de tipul de mesaj)

Autentificare

Alegeți una dintre cele trei metode de autentificare:

=== „Antetul cheii API”

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

=== „Autentificare de bază HTTP”

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

=== „Cheia API ca parolă”

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

Răspuns

Răspuns de succes

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

Câmpuri de răspuns

Câmp Tip Descriere
messagelistId întreg Identificator unic pentru lista de mesaje
messageId șir Identificator unic pentru fiecare mesaj
starea șir Starea mesajului: acceptat, respins, eșuat
piese întreg Numărul de părți ale mesajului (pentru SMS)
customerMessageId șir Identificatorul dvs. intern (dacă este furnizat)
la șir Numărul de telefon al destinatarului

Tipuri de mesaje

SMS

Mesaje text simple:

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

Promo Viber

Mesaje promoționale cu rich media:

{
  "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 tranzacțional

Notificări privind tranzacțiile:

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

Viber OTP

Notificări unice privind parola:

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

Gestionarea erorilor

Codurile de stare HTTP

Cod Descriere
200 Solicitare reușită
400 Solicitare greșită - parametri nevalidi
401 Neautorizat - autentificarea eșuată
429 Prea multe solicitări - limita ratei a fost depășită
500 Eroare internă server

Răspuns de eroare

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

Cele mai bune practici

Format numărul de telefon

Utilizați întotdeauna formatul E.164 pentru numerele de telefon:

  • ✅ Corect: +380XXXXXXXXX
  • ❌ Incorect: 380XXXXXXXXX, 0XXXXXXXXX

Textul mesajului

  • Păstrați SMS-urile sub 160 de caractere pentru a evita mai multe părți
  • Utilizați codificarea UTF-8 pentru caracterele internaționale
  • Testați caracterele speciale înainte de a trimite în bloc

TTL (Time-to-Live)

  • Setați TTL adecvat pentru mesajele sensibile la timp
  • Mesaje OTP: 300-600 secunde (5-10 minute)
  • Mesaje promoționale: 3600-86400 secunde (1-24 ore)

ID mesajul clientului

  • Utilizați identificatori unici pentru fiecare mesaj
  • Ajută la urmărire și depanare
  • Util pentru corelarea cu înregistrările sistemului dumneavoastră

Limite de rate

Contactați managerul de cont pentru informații despre:

  • Mesaje pe secundă
  • Mesaje pe zi
  • Conexiuni concurente

Următorii pași