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

Parametri facoltativi

Autenticazione

Scegli uno dei tre metodi di autenticazione:

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

Risposta

Risposta riuscita

    curl -i -X POST \
      -H "Content-Type: application/json" \
      -H "Authorization: Basic base64(login:password)" \
      -d '{
        "messages": [
          {
            "from": "Shopillect",
            "to": "380936670003",
            "type": "sms",
            "text": "Text for SMS Shopillect",
            "ttl": "120"
          }
        ]
      }' \
      "https://restapi.smsbat.com/bat/{referralGuid}/messagelist"
    ```

### 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:

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

Promozione Viber

Messaggi promozionali con rich media:

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

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

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

• Messaggi Viber - Esplora i tipi di messaggi Viber
• Messaggi SMS - Ulteriori informazioni sugli SMS
• Verifica stato - Tieni traccia della consegna dei messaggi