Help Center Compatibilità API GMS

Compatibilità API GMS

SMSBAT supporta un livello di compatibilità con l’API GMS. This allows you to migrate your existing integrations designed for GMS directly to SMSBAT without having to modify your message routing schemas, payload structures, or callback listeners.

Impostazioni di connessione

Per instradare le richieste tramite SMSBAT, aggiorna l’URL di base e le credenziali di autenticazione nella tua integrazione:

URL di base: https://restapi.smsbat.com
Endpoint: POST /api/GMSMessage/send_message
Formato della richiesta: “application/json”.
Autenticazione: Autenticazione HTTP di base (utilizza le credenziali API SMSBAT)

Richiedi parametri

L’API di compatibilità GMS accetta un oggetto JSON con i seguenti parametri di livello superiore:

Parametro	Digitare	Obbligatorio	Descrizione
`numero_telefono`	stringa	Sì	Numero di telefono del destinatario in formato internazionale (ad esempio, `380501234567`).
“tag”	stringa	Sì	Nome mittente registrato/nome alfabetico.
`canali`	matrice	Sì	Elenco dei canali da provare, in ordine di priorità. Valori supportati: `viber`, `sms`, `push`. Ad esempio, `["viber", "sms"]`.
`opzioni_canale`	oggetto	Sì	Mappa contenente le opzioni per ciascun canale attivo (vedi sotto).
`id_extra`	stringa	No	Il tuo ID messaggio interno lato cliente.
`callback_url`	stringa	No	URL dell’endpoint sul sistema per ricevere richiamate sullo stato della consegna.
`codice_divisione`	stringa	No	Identificatore del codice di divisione opzionale (il valore predefinito è `main`).

Impostazioni delle opzioni del canale

L’oggetto “channel_options” contiene configurazioni specifiche del canale.

Utilizzato quando “viber” è elencato nell’array “channels”.

Parametro	Digitare	Obbligatorio	Descrizione
”testo”	stringa	Sì	Testo del corpo del messaggio.
`ttl`	intero	Sì	Time-To-Live in secondi.
`img`	stringa	No	URL HTTPS pubblico dell’immagine da visualizzare.
`didascalia`	stringa	No	Etichetta di testo del pulsante.
`azione`	stringa	No	URL di destinazione quando si fa clic sul pulsante.
`opzioni_sondaggio`	matrice	No	Matrice di stringhe (da 2 a 5 elementi) da visualizzare come opzioni del sondaggio.
`carousel_items`	matrice	No	Serie di oggetti diapositiva da visualizzare come carosello Viber (vedi struttura nella scheda).

Esempio di richiesta Viber:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Hello from SMSBAT!",
      "ttl": 60,
      "img": "https://www.example.com/image.png",
      "caption": "Open",
      "action": "https://www.example.com"
    }
  }
}

Abilita la messaggistica Viber con un fallback automatico degli SMS se la consegna di Viber fallisce entro il TTL.

Esempio di richiesta di fallback:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber", "sms"],
  "channel_options": {
    "viber": {
      "text": "Your order is ready!",
      "ttl": 60,
      "caption": "Details",
      "action": "https://www.example.com/order"
    },
    "sms": {
      "text": "Your order is ready: https://www.example.com/order",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}

Utilizzato quando “sms” è elencato nell’array “channels”.

Parametro	Digitare	Obbligatorio	Descrizione
”testo”	stringa	Sì	Testo del corpo del messaggio.
`nome_alfa`	stringa	Sì	Nome alfa del mittente.
`ttl`	intero	Sì	Time-To-Live in secondi.
`ctr`	booleano	No	Abilita il tracciamento dei clic CTR sui collegamenti nel testo (`true`/`false`).

Esempio di richiesta SMS:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["sms"],
  "channel_options": {
    "sms": {
      "text": "Your verification code is 1234",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}

Utilizzato per creare sondaggi e sondaggi Viber.

Note

La configurazione del sondaggio Viber deve avere tra 2 e 5 opzioni all’interno di survey_options.

Esempio di richiesta di sondaggio:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Please rate our service:",
      "ttl": 60,
      "survey_options": [
        "Excellent",
        "Good",
        "Bad"
      ]
    }
  }
}

Utilizzato per inviare cartoline con diapositive con immagini scorrevoli. Ogni diapositiva supporta immagine, titolo e pulsanti.

Esempio di richiesta carosello:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Choose an offer",
      "ttl": 60,
      "carousel_items": [
        {
          "title": "Offer 1",
          "image_url": "https://www.example.com/offer-1.png",
          "primary_label": "Open",
          "primary_url": "https://www.example.com/offer-1",
          "secondary_label": "More",
          "secondary_url": "https://www.example.com/offers"
        },
        {
          "title": "Offer 2",
          "image_url": "https://www.example.com/offer-2.png",
          "primary_label": "Open",
          "primary_url": "https://www.example.com/offer-2"
        }
      ]
    }
  }
}

Utilizzato quando “push” è elencato nell’array “channels”.

Parametro	Digitare	Obbligatorio	Descrizione
”titolo”	stringa	Sì	Testo del titolo della notifica push.
”testo”	stringa	Sì	Testo del corpo del messaggio.
`ttl`	intero	Sì	Time-To-Live in secondi.
`img`	stringa	No	URL HTTPS pubblico dell’immagine da visualizzare.
`didascalia`	stringa	No	Etichetta di testo del pulsante.
`azione`	stringa	No	URL di destinazione quando si fa clic sul pulsante.
`ctr`	booleano	No	Abilita il tracciamento dei clic.

Esempio di richiesta push:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["push"],
  "channel_options": {
    "push": {
      "title": "Order update",
      "text": "Your order is ready for pickup!",
      "ttl": 60,
      "img": "https://www.example.com/push.png",
      "caption": "Open",
      "action": "https://www.example.com/order",
      "ctr": false
    }
  }
}

Formato della risposta

L’endpoint restituisce risposte in formato JSON con un codice di stato “HTTP 200 OK”.

Risposta riuscita

{
  "MessageId": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "ErrorCode": null,
  "ErrorText": null
}

Risposte agli errori

Se la convalida o l’elaborazione falliscono, verrà restituita una risposta di errore con un “ErrorCode” non nullo e un “ErrorText” dettagliato.

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "This type of Message is not supported by the system"
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "There can be from 2 to 5 survey options."
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 400,
  "ErrorText": "Cannot send to international number: alpha name 'ALPHA' is not registered."
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 500,
  "ErrorText": "Internal server error."
}

Formato di consegna della richiamata

Se nella richiesta è stato specificato “callback_url”, SMSBAT invia gli aggiornamenti sullo stato di consegna come payload JSON POST al tuo endpoint.

Esempio di richiesta di richiamata

POST /your-callback-endpoint HTTP/1.1
Host: yoursystem.com
Content-Type: application/json

{
  "number": "380501234567",
  "time": 1719237600000,
  "status": 2,
  "substatus": 23,
  "hyber_status": 23033,
  "message_id": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "extra_id": "ORDER-12345",
  "sent_via": "viber",
  "matching_template_id": 0
}

Descrizione dei campi di richiamata

Campo	Digitare	Descrizione
”numero”	stringa	Numero di telefono del destinatario.
`tempo`	numero	Timestamp dell’evento in millisecondi Unix.
`stato`	numero	Identificatore di stato semplificato (vedi tabella Codici di stato).
`sottostato`	numero	Identificatore di stato dettagliato (vedi tabella codici di sottostato).
`hyber_status`	numero	Codice di stato interno SMSBAT dettagliato (vedi tabella Stato Hyber).
`id_messaggio`	stringa	ID del messaggio SMSBAT (GUID) generato al momento dell’invio.
`id_extra`	stringa	ID lato cliente fornito nella richiesta originale.
`inviato_via`	stringa	Canale che ha elaborato il messaggio: `viber`, `sms` o `rcs`.
`matching_template_id`	numero	Stato di corrispondenza del modello Viber (ove applicabile).

Mappature dello stato

1. Stato semplificato (`status`)

Codice	Significato
”1”	Messaggio accettato o in fase di consegna.
”2”	Messaggio consegnato.
”3”	Errore di elaborazione o consegna.

2. Stato dettagliato (`substatus`)

Codice	Significato
”12”	Accettato per l’elaborazione.
”23”	Consegnato.
”24”	Visto/letto.
”35”	Non consegnato entro TTL (scaduto).
“36”	Errore di consegna.

3. Tipo di canale (`sent_via`)

Canale	Descrizione
`viber`	Stato prodotto dal canale Viber.
`sms`	Stato prodotto dal canale SMS.
`rcs`	Stato prodotto dal canale RCS.

4. Stato SMSBAT dettagliato (`hyber_status`)

Codice	Canale	Stato	Sottostato	Significato
23033	`viber`	”2"	"23”	Messaggio Viber consegnato.
24013	`viber`	”2"	"24”	Messaggio Viber letto dal destinatario (visto).
36013	`viber`	”3"	"36”	Errore interno Viber.
36023	`viber`	”3"	"36”	ID servizio Viber non valido o non disponibile.
36033	`viber`	”3"	"36”	Dati del payload Viber non validi.
36037	`viber`	”3"	"36”	URL dell’immagine Viber troppo lungo.
36038	`viber`	”3"	"36”	URL dell’immagine Viber non valido.
36039	`viber`	”3"	"36”	Il testo di Viber è troppo lungo.
36044	`viber`	”3"	"36”	Testo Viber vuoto.
36053	`viber`	”3"	"36”	Tipo di messaggio Viber non supportato.
36063	`viber`	”3"	"36”	Parametri Viber non validi.
36073	`viber`	”3"	"36”	Timeout del fornitore Viber.
36083	`viber`	”3"	"36”	Mittente Viber bloccato dal destinatario.
36093	`viber`	”3"	"36”	Il destinatario non è registrato come utente Viber.
36103	`viber`	”3"	"36”	Nessun dispositivo Android/iOS con supporto Viber trovato.
36113	`viber`	”3"	"36”	Indirizzo IP non autorizzato per l’invio Viber.
36123	`viber`	”3"	"36”	Rilevato messaggio Viber duplicato.
36143	`viber`	”3"	"36”	Errore di fatturazione Viber.
36153	`viber`	”3"	"36”	Messaggio bloccato dalla lista nera della piattaforma.
36163	`viber`	”3"	"36”	Errore di elaborazione interna della piattaforma Viber.
36173	`viber`	”3"	"36”	Etichetta Viber errata o mancante.
36183	`viber`	”3"	"36”	Valore TTL Viber non valido.
12011	`sms` / `rcs`	”1"	"12”	SMS/RCS accettati.
36011	`sms` / `rcs`	”1"	"12”	SMS/RCS in arrivo.
23011	`sms` / `rcs`	”2"	"23”	SMS/RCS consegnati.
35015	`sms` / `rcs`	”3"	"35”	SMS/RCS scaduto (non consegnato entro TTL).
36021	`sms` / `rcs`	”3"	"36”	Messaggio SMS/RCS eliminato.
36031	`sms` / `rcs`	”3"	"36”	Impossibile inviare SMS/RCS.
36041	`sms` / `rcs`	”3"	"36”	Stato di consegna SMS/RCS sconosciuto.
36051	`sms` / `rcs`	”3"	"36”	Messaggio SMS/RCS rifiutato.

Search Results

Compatibilità API GMS

Impostazioni di connessione

Richiedi parametri

Impostazioni delle opzioni del canale

Formato della risposta

Risposta riuscita

Risposte agli errori

Formato di consegna della richiamata

Esempio di richiesta di richiamata

Descrizione dei campi di richiamata

Mappature dello stato

1. Stato semplificato (status)

2. Stato dettagliato (substatus)

3. Tipo di canale (sent_via)

4. Stato SMSBAT dettagliato (hyber_status)

1. Stato semplificato (`status`)

2. Stato dettagliato (`substatus`)

3. Tipo di canale (`sent_via`)

4. Stato SMSBAT dettagliato (`hyber_status`)