Vai al contenuto

Invia messaggio

Invia messaggi tramite l'API SMSBAT utilizzando l'endpoint /bat/messagelist.

Punto finale

POST /bat/messagelist

Richiedi struttura

Il corpo della richiesta è un array JSON di oggetti del messaggio:

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

Parametri

Parametri obbligatori

Parametro Digitare Descrizione
"da" stringa ID mittente alfanumerico
"a" stringa Numero di telefono del destinatario in formato E.164 (es. +380XXXXXXXXX)
"tipo" stringa Tipo di messaggio: sms, viber_promo, viber_trans, viber_carousel, viber_survey, viber_otp, rcs, flashcall
"testo" stringa Contenuto del messaggio (obbligatorio per la maggior parte dei tipi, facoltativo per alcuni)

Parametri facoltativi

Parametro Digitare Descrizione
customerMessageId stringa Il tuo identificatore interno per il monitoraggio
ttl intero Tempo di vita in secondi
messaggioData oggetto Configurazione specifica del tipo (varia in base al tipo di messaggio)

Autenticazione

Scegli uno dei tre metodi di autenticazione:

CODICE_BLOCCO_2

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

Risposta

Risposta riuscita

CODICE_BLOCCO_5

Campi di risposta

Campo Digitare Descrizione
messagelistId intero Identificatore univoco per l'elenco dei messaggi
messaggioId stringa Identificatore univoco per ogni messaggio
stato stringa Stato del messaggio: accettato, rifiutato, fallito
"parti" intero Numero di parti del messaggio (per SMS)
customerMessageId stringa Il tuo identificatore interno (se fornito)
"a" stringa Numero di telefono del destinatario

Tipi di messaggi

SMS

Messaggi di testo semplici:

CODICE_BLOCCO_6

Promozione Viber

Messaggi promozionali con rich media:

CODICE_BLOCCO_7

Transazionale Viber

Notifiche sulle transazioni:

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

Viber OTP

Notifiche password monouso:

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

Gestione degli errori

Codici di stato HTTP

Codice Descrizione
200 Richiesta riuscita
400 Richiesta errata: parametri non validi
401 Non autorizzato: autenticazione non riuscita
429 Troppe richieste: limite di velocità superato
500 Errore interno del server

Risposta all'errore

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

Migliori pratiche

Formato del numero di telefono

Utilizza sempre il formato E.164 per i numeri di telefono:

  • ✅ Corretto: +380XXXXXXXXX
  • ❌ Errato: 380XXXXXXXXX, 0XXXXXXXXX

Testo del messaggio

  • Mantieni gli SMS sotto i 160 caratteri per evitare parti multiple
  • Utilizza la codifica UTF-8 per i caratteri internazionali
  • Prova i caratteri speciali prima dell'invio in blocco

TTL (Time-to-Live)

  • Imposta il TTL appropriato per i messaggi urgenti
  • Messaggi OTP: 300-600 secondi (5-10 minuti)
  • Messaggi promozionali: 3600-86400 secondi (1-24 ore)

ID messaggio cliente

  • Utilizza identificatori univoci per ciascun messaggio
  • Aiuta con il monitoraggio e il debug
  • Utile per la correlazione con i record del sistema

Limiti di velocità

Contatta il tuo account manager per informazioni su:

  • Messaggi al secondo
  • Messaggi al giorno
  • Connessioni simultanee

Passaggi successivi