Help Center Compatibilità API TurboSMS

Compatibilità API TurboSMS

SMSBAT supporta completamente un livello di compatibilità con l’API TurboSMS. Ciò ti consente di migrare le tue integrazioni esistenti progettate per TurboSMS direttamente su SMSBAT senza dover riscrivere le strutture dei messaggi o i payload degli endpoint.

Supportiamo l’invio di messaggi SMS e Viber (comprese funzionalità avanzate come caroselli e sondaggi), il recupero degli stati e il recupero dei dettagli dei messaggi utilizzando esattamente le stesse strutture del corpo della richiesta con cui hai già familiarità.

Autenticazione

L’unica differenza rispetto all’API TurboSMS nativa è il meccanismo di autenticazione. Mentre TurboSMS utilizza un parametro di query “token” personalizzato o un’intestazione di autenticazione specifica, SMSBAT richiede un Bearer Token standard.

Devi includere il token API SMSBAT nell’intestazione “Authorization” per tutte le richieste:

Authorization: Bearer YOUR_SMSBAT_TOKEN

##URL di base

Tutti gli endpoint devono essere indirizzati all’URL di base dell’API SMSBAT:

https://restapi.smsbat.com

Invia messaggio singolo

Endpoint: POST /api/tsms/message/send

Consente l’invio di messaggi SMS e Viber con supporto per la consegna ibrida (Viber con fallback SMS). Elabora una singola richiesta di invio e restituisce i risultati di consegna per ciascun destinatario.

Funzionalità chiave

  • Parametri flessibili: I parametri globali possono essere sostituiti da parametri SMS/Viber specifici.
  • Contenuto: supporta caroselli Viber, sondaggi, file allegati e pulsanti interattivi.
  • Gestione degli errori: Restituisce HTTP 200 anche per gli errori (risposte agli errori strutturati). “codice_risposta: 999” con stato “FATAL_ERROR” per errori di sistema.
  • Errori del destinatario: Errori specifici del destinatario vengono restituiti nell’array response_result. I destinatari non riusciti hanno message_id: null e codici di errore specifici.

Esempio di richiesta (messaggio ibrido)

CODICE_BLOCCO_2

{
  "sender": "GlobalSender",
  "text": "Check out our products",
  "recipients": ["380951111111"],
  "viber": {
    "sender": "ViberSender",
    "text": "Check out our products",
    "is_transactional": false,
    "carousel": [
      {
        "title": "Product 1",
        "image_url": "https://example.com/product1.jpg",
        "button_caption": "Buy Now",
        "button_url": "https://example.com/buy/product1",
        "link_caption": "Learn More",
        "link_url": "https://example.com/product1"
      },
      {
        "title": "Product 2",
        "image_url": "https://example.com/product2.jpg",
        "button_caption": "Buy Now",
        "button_url": "https://example.com/buy/product2",
        "link_caption": "Learn More",
        "link_url": "https://example.com/product2"
      }
    ]
  }
}

Esempio di richiesta (sondaggio Viber)

{
  "sender": "GlobalSender",
  "text": "Please rate our service",
  "recipients": ["380951111111"],
  "viber": {
    "sender": "ViberSender",
    "text": "Please rate our service",
    "is_transactional": true,
    "survey": [
      "Excellent",
      "Good",
      "Average",
      "Poor"
    ]
  }
}

Invia più messaggi (batch)

Endpoint: POST /api/tsms/message/sendmulti

Questo metodo ti consente di inviare più richieste di invio in un’unica richiesta HTTP, risparmiando il sovraccarico della connessione. Chiamare “sendmulti” con dati per 100 richieste sarà più veloce che eseguire 100 richieste “send” individuali.

Esempio di richiesta

CODICE_BLOCCO_5

Esempio di risposta

CODICE_BLOCCO_6

Ottieni lo stato del messaggio

Endpoint: POST /api/tsms/message/status

Recupera gli stati di consegna dei messaggi inviati fornendo il loro message_id.

Esempio di richiesta

CODICE_BLOCCO_7

Ottieni i dettagli del messaggio

Endpoint: POST /api/tsms/messaggio/dettagli

Ti consente di recuperare informazioni dettagliate sui messaggi creati, inclusi i dettagli completi del payload per i canali SMS e Viber, i prezzi e i timestamp esatti.

Esempio di richiesta

{
  "messages": [
      "573dcb46-7851-4e16-bb1f-721c13ef5f38", 
      "f1640579-ea75-4bc1-b708-1c3858bf222d"
  ]
}

Esempio di risposta

{
    "response_code": 0,
    "response_status": "OK",
    "response_result": [
        {
            "message_id": "573dcb46-7851-4e16-bb1f-721c13ef5f38",
            "sms": null,
            "viber": {
                "added": "2025-09-29T14:17:02.577Z",
                "start": "2025-09-29T10:00:00Z",
                "sent": "2025-09-29T14:17:02.577Z",
                "updated": "2025-09-29T14:17:02.577Z",
                "sender": "ViberSender",
                "text": "Viber version of message",
                "recipient": "380982462128",
                "message_type": "promotional",
                "status": "Queued",
                "price": 0,
                "ttl": 3600,
                "caption": "Button text",
                "action": "https://google.com"
            },
            "response_code": 0,
            "response_status": "OK"
        }
    ]
}