Vai al contenuto

Compatibilità API Messagio

SMSBAT supporta un livello di compatibilità con Messagio API. Ciò ti consente di migrare le tue integrazioni Viber esistenti progettate per Messagio direttamente su SMSBAT senza dover riscrivere la struttura del carico utile o modificare la logica di integrazione.

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/SendMessage
  • Formato richiesta: application/x-www-form-urlencoded (dati del modulo)

Autenticazione e credenziali

Le richieste vengono autenticate utilizzando parametri inviati direttamente all'interno dei dati del modulo del corpo della richiesta:

Parametro Digitare Obbligatorio Descrizione
"utente" stringa Sì Il login del tuo account SMSBAT o l'identificativo utente.
"segno" stringa Sì Segreto API o firma registrata per il nome del mittente.
"da" stringa Sì Nome alfa del mittente registrato.
metodo_di_invio stringa Sì Tipo di canale. Utilizza viber per i normali messaggi Viber Business o viber_otp per i modelli OTP di Viber.
"telefono" stringa Sì Numero di telefono del destinatario in formato internazionale (ad esempio, 380501234567).

Tipi di messaggi Viber

Scegli una scheda qui sotto per visualizzare i parametri specifici e richiedere payload per diverse strutture di messaggi Viber:

Invia un semplice messaggio di testo.

Parametri aggiuntivi:

Parametro Digitare Obbligatorio Descrizione
txt stringa Sì Testo del messaggio.

Esempio di richiesta di carico utile: 

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Hello+from+SMSBAT%21

Invia un messaggio di testo con un pulsante interattivo di invito all'azione.

Parametri aggiuntivi:

Parametro Digitare Obbligatorio Descrizione
txt stringa Sì Testo del messaggio.
pulsante_testo stringa Sì Testo visualizzato sul pulsante.
pulsante_link stringa Sì URL di destinazione quando si fa clic sul pulsante.

Esempio di richiesta di carico utile: 

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Check+our+latest+offers%21&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Invia un file immagine pubblico.

Parametri aggiuntivi:

Parametro Digitare Obbligatorio Descrizione
link_immagine stringa Sì URL HTTPS pubblico dell'immagine.
txt stringa No Testo della didascalia opzionale da visualizzare sotto l'immagine.

Esempio di richiesta di carico utile: CODICE_BLOCCO_2

Invia una scheda dettagliata contenente testo, un'immagine e un pulsante.

Parametri aggiuntivi:

Parametro Digitare Obbligatorio Descrizione
txt stringa Sì Testo della didascalia.
link_immagine stringa Sì URL HTTPS pubblico dell'immagine.
pulsante_testo stringa Sì Testo visualizzato sul pulsante.
pulsante_link stringa Sì URL di destinazione quando si fa clic sul pulsante.

Esempio di richiesta di carico utile: 

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Hot+deals+inside%21&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Invia un file video con una didascalia di testo opzionale e pulsanti di azione.

Parametri aggiuntivi:

Parametro Digitare Obbligatorio Descrizione
video.url stringa Sì URL HTTPS pubblico del file video.
video.miniatura stringa Sì URL HTTPS pubblico dell'immagine di anteprima del video.
video.dimensione_mb intero Sì Dimensioni approssimative del file video in megabyte.
video.durata_sec intero Sì Durata del video in secondi.
txt stringa No Testo descrittivo facoltativo.
pulsante_testo stringa No Testo del pulsante facoltativo (può fungere da didascalia o collegamento).
pulsante_link stringa No URL di collegamento del pulsante facoltativo.

Esempio di richiesta di carico utile: 

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Watch+this+tutorial%21&video.url=https%3A%2F%2Fwww.example.com%2Fvideo.mp4&video.thumbnail=https%3A%2F%2Fwww.example.com%2Fvideo-thumbnail.png&video.size_mb=1&video.duration_sec=3&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Invia Viber One-Time Password (OTP) utilizzando un modello pre-approvato.

Nota

Quando invii messaggi OTP, devi impostare sending_method su viber_otp.

Parametri aggiuntivi:

| Parametro | Digitare | Obbligatorio | Descrizione |
| :--- | :--- | :--- | :--- |
| `template.id` | stringa | **Sì** | ID modello OTP Viber pre-approvato. |
| `template.lang` | stringa | **Sì** | Codice della lingua del modello (ad esempio, `en`, `uk`). |
| `template.params.pin` | stringa | **Sì** | Il valore del pin OTP da inserire nel modello. |
| `template.params.business_platform_name` | stringa | **Sì** | Il segnaposto del nome dell'azienda nel modello. |
| `template.params.code_validity_time` | stringa | **Sì** | Periodo di validità del PIN in minuti. |

**Esempio di richiesta di carico utile:**
__CODICE_BLOCCO_5__

Invia una scheda messaggio interattiva contenente più diapositive (schede) che l'utente può scorrere.

Parametri aggiuntivi:

Parametro Digitare Obbligatorio Descrizione
txt stringa Sì Testo del titolo del carosello.
carosello[N].titolo stringa Sì Titolo della carta "N" (a partire da 0).
carosello[N].url_immagine stringa Sì URL dell'immagine HTTPS pubblica della carta "N".
carosello[N].etichetta_primaria stringa Sì Didascalia del pulsante principale della carta "N".
carosello[N].url_primario stringa Sì URL del collegamento del pulsante principale della carta "N".
carosello[N].etichetta_secondaria stringa No Didascalia del pulsante secondario della carta "N".
carosello[N].url_secondario stringa No URL del collegamento del pulsante secondario della carta "N".

Esempio di richiesta di carico utile: CODICE_BLOCCO_6

Invia un messaggio contenente un sondaggio interattivo o una domanda di sondaggio.

Parametri aggiuntivi:

Parametro Digitare Obbligatorio Descrizione
txt stringa Sì Testo della domanda del sondaggio.
opzioni_indagine[N] stringa Sì Testo dell'opzione di sondaggio per l'elemento "N" (indice che inizia da 0). Sono richieste almeno 2 opzioni.
tipo_opzione intero Sì Tipo di selettore: 1 (RadioButtons) o 2 (Pulsanti normali).

Esempio di richiesta di carico utile: CODICE_BLOCCO_7

Formato della risposta

L'endpoint di compatibilità dell'API Messagio restituisce risposte in formato XML con un codice di stato "HTTP 200 OK".

Risposta accettata (riuscita).

<response>
  <code>0</code>
  <tech_message>OK</tech_message>
  <msg_id phone="380501234567">MESSAGE_GUID</msg_id>
</response>

Risposte agli errori

Se la convalida dei parametri di una richiesta o l'autenticazione fallisce, la risposta restituirà un codice diverso da zero.

<response>
  <code>-1</code>
  <tech_message>PARAM ERROR (sign)</tech_message>
</response>

<response>
  <code>-2</code>
  <tech_message>ERROR(unauthorized)</tech_message>
</response>

Richiamate

Gli URL di richiamata devono essere implementati e ospitati sulla tua piattaforma. SMSBAT invia richiamate HTTP per aggiornare il tuo sistema in merito agli eventi di consegna, alle risposte ai sondaggi e alle risposte degli utenti.

1. Richiamata sullo stato della consegna

Inviato quando un messaggio cambia stato (consegnato, letto, non riuscito).

  • Tipo di contenuto: application/x-www-form-urlencoded
  • Metodo: POST

Richiedi formati di carico utile:

  • Consegnato: 
    msg_id=MESSAGE_GUID&status=delivered
  • Visto/Letto: CODICE_BLOCCO_12
  • Non consegnato/Non riuscito: 
    msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

Descrizione campi:

  • msg_id: ID messaggio univoco SMSBAT (GUID) restituito nella risposta SendMessage.
  • "status": esito della consegna ("consegnato", "non consegnato" o "stato sconosciuto").
  • "tipo": impostato su "visto" quando il messaggio è stato visualizzato dal destinatario.
  • status_extended: motivo tecnico specifico per lo stato di mancata consegna (ad esempio VIBER_EXPIRED, VIBER_BLOCKED_BY_USER, VIBER_USER_NOT_FOUND, VIBER_NO_DEVICE).

2. Richiamata della risposta al sondaggio

Attivato quando un utente seleziona un'opzione di risposta in un messaggio Viber Survey.

  • Tipo di contenuto: application/x-www-form-urlencoded
  • Metodo: POST

Richiedi formato payload: CODICE_BLOCCO_14

3. Richiamata messaggio utente in entrata

Si attiva quando un utente invia una risposta di testo o multimediale al tuo servizio Viber Business.

  • Tipo di contenuto: application/json
  • Metodo: POST

Richiedi formato payload: CODICE_BLOCCO_15

Descrizione campi:

  • msg_id: l'ID del messaggio univoco generato per la risposta in entrata.
  • "testo": contenuto testuale inviato dall'utente (può essere "null" se ha inviato solo contenuti multimediali).
  • media: URL diretto per scaricare eventuali allegati multimediali inviati dall'utente (può essere null se solo testo).
  • phone: numero di telefono del mittente in formato internazionale.
  • sender_bm_id: l'ID mittente di Viber Business.