Vai al contenuto

Guida API RESTful SMSBAT

Guida completa all'API RESTful SMSBAT: tutto ciò che devi sapere.

Ultimo aggiornamento: 29 agosto 2025

L'API RESTful SMSBAT ti consente di inviare vari tipi di messaggi: Viber-carousel, Viber-survey, Viber-promo (immagini, video), chat aziendali Viber, messaggi OTP (Viber OTP, Flash Call) e le relative varianti di fallback.

Nota: questa è l'API HTTP unificata per la messaggistica in uscita. Se hai bisogno di integrazioni con bot in entrata (Viber Bot / Telegram Bot), fai riferimento all'API Cascade.

1. Protocollo

  • Protocollo: HTTPS
  • Corpo della richiesta: oggetto JSON contenente un array di messaggi.
  • Metodi:
  • "GET" per recuperare i dati (stato del messaggio, saldo, ecc.)
  • "POST" per creare oggetti (ad esempio, avviare una trasmissione/invio)
  • PATCH per modificare gli oggetti

2. Autorizzazione

Forniamo diversi metodi di autorizzazione per la vostra comodità: - Autenticazione HTTP di base (login e password dalla dashboard). - Intestazione HTTP personalizzata "X-Authorization-Key" contenente un token API. - Campo della password di autenticazione di base HTTP che contiene il token API (passa @ come login).

Token API può essere generato nella Dashboard in Profilo utente.

Richiedi esempi

Con l'autenticazione di base: 

curl -H "Content-Type: application/json" \
  -X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist \
  --user user:password

Con "Chiave di autorizzazione X": 

curl -H "X-Authorization-Key: <token>" \
  -H "Content-Type: application/json" \
  -X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist

3. Invio di messaggi

Nella piattaforma SMSBAT qualsiasi invio di messaggio (anche un singolo messaggio) è considerato un "Broadcast" (messagelist).

Endpoint - Metodo: POST - URL: https://api.smsbat.com/bat/messagelist - Intestazioni: "Tipo di contenuto: application/json".

Struttura del carico utile di base: CODICE_BLOCCO_2

Campi obbligatori per ciascun oggetto messaggio:

  • "da": nome alfa del mittente verificato.
  • "a": numero di telefono del destinatario (formato E.164).
  • type: enumerazione del tipo di messaggio.
  • text: testo principale del messaggio (facoltativo se il tipo non richiede testo).

Valori tipo supportati: - "sms". - viber_service (o viber_trans) - viber_promo - "viber_carousel". - "viber_survey". - "viber_otp". - "viber_session". - "flashcall_callback". - "chiamata flash".

Campi comuni facoltativi:

  • customerMessageId: ID stringa all'interno del tuo sistema (utilizzato per tenere traccia dei callback). Deve essere univoco per messaggio.
  • "dtSend": data/ora ISO8601 dell'invio futuro programmato.
  • dtExpire: ISO8601 Data/Ora del termine di consegna.
  • ttl: Time-To-Live in secondi. (Se "dtExpire" non viene fornito, l'API calcola la mappatura predefinita dal "tipo").

TTL predefiniti (secondi):

  • sms - 86400 (24 ore)
  • "viber_trans" / "viber_service" - 345600
  • "viber_promo" - 604800
  • "viber_session" - 604800

4. Routing di fallback (a cascata)

È possibile specificare una coda di fallback per garantire la consegna dei messaggi se il canale primario non funziona o scade.

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380500505051",
      "text": "test message",
      "type": "viber_service",
      "ttl": 60,
      "fallbacks": [
        {
          "from": "ALPHANAME",
          "to": "380936670003",
          "text": "test sms fallback message2",
          "type": "sms"
        }
      ]
    }
  ]
}
I fallback si attivano quando il provider rifiuta il messaggio principale o quando scade il TTL.

5. Panoramica dei tipi di messaggio e dei dati dei messaggi

I tipi di messaggi complessi richiedono configurazioni aggiuntive inserite nella proprietà "messageData".

5.1 Promozione Viber (viber_promo)

Solo immagine 

"messageData":{
  "img":"https://domain.com/image.png"
}

Testo + pulsante CODICE_BLOCCO_5

Immagine + Testo + Pulsante Combina "img", "buttonText" e "buttonAction".

Carico utile video: CODICE_BLOCCO_6 (Puoi anche combinare le proprietà video con buttonText e buttonAction).

5.2 Transazionale/Servizio Viber (viber_trans, viber_service)

Se disponi di un modello approvato contenente un file allegato: CODICE_BLOCCO_7

Richiede un array "carousel.items" all'interno di "messageData".

Limitazioni: - Lunghezza degli articoli: da 2 a 5 articoli - Titolo: da 2 a 38 caratteri - imageUrl: dimensione consigliata JPEG/PNG 215x185

"messageData": {
  "carousel": {
    "items": [
      {
        "title": "50% Off Shoes!",
        "imageUrl": "https://domain.com/image1.png",
        "primaryButton": { "label": "Shop", "actionUrl": "..." },
        "secondaryButton": { "label": "Details", "actionUrl": "..." }
      }
    ]
  }
}

5.4 Sondaggio/Elenco Viber (viber_survey)

Crea un sondaggio interattivo all'interno della visualizzazione chat. 

"messageData": {
  "survey": {
    "options": [
      "Excellent", "Good", "Normal", "Bad", "Terrible"
    ]
  }
}
La proprietà "testo" del messaggio funge da titolo del sondaggio (massimo 85 caratteri). Puoi passare da 2 a 5 opzioni, ciascuna di massimo 50 caratteri.

5.5 Viber OTP (viber_otp)

Utilizza modelli Viber localizzati preregistrati a livello globale. 

"messageData": {
  "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
  "templateLang": "uk",
  "templateParams": {
    "pin": "3211",
    "business_platform_name": "SMSBAT",
    "code_validity_time": 7
  }
}
I parametri del modello (pin, business_platform_name) fanno rigorosamente distinzione tra maiuscole e minuscole. L'API supporta varie varianti del linguaggio del codice ISO (EN, ES, RU, TR, UK, ecc.).

5.6 Chiamata flash (flashcall)

Le ultime cifre del numero da comporre (il codice generato) devono essere passate tramite il parametro "testo". Se "testo" viene omesso, il codice viene randomizzato ed è necessario estrarlo dal corpo sincrono della risposta 200 OK dell'API ("messaggi/testo").

{
  "from": "FLASHCALL",
  "to": "380500000000",
  "type": "flashcall",
  "text": "340"
}