Help Center Compatibilità API Messagio

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:

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&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png

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

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:**
```http
POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber_otp&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&template.id=otp_template_123&template.lang=en&template.params.pin=123456&template.params.business_platform_name=SMSBAT&template.params.code_validity_time=7
```

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:

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=Top+picks+for+you&carousel%5B0%5D.title=First+Offer&carousel%5B0%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-1.png&carousel%5B0%5D.primary_label=Open&carousel%5B0%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-1&carousel%5B0%5D.secondary_label=Details&carousel%5B0%5D.secondary_url=https%3A%2F%2Fwww.example.com%2Fitem-1%2Fdetails&carousel%5B1%5D.title=Second+Offer&carousel%5B1%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-2.png&carousel%5B1%5D.primary_label=Open&carousel%5B1%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-2

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:

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=Please+rate+our+service&survey_options%5B0%5D=Excellent&survey_options%5B1%5D=Good&survey_options%5B2%5D=Average&option_type=1

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:

msg_id=MESSAGE_GUID&status=delivered&type=seen

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:

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

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:

{
  "msg_id": "INBOUND_MESSAGE_GUID",
  "text": "Hello, I have a question",
  "media": "https://example.com/user-attachment.png",
  "phone": "380501234567",
  "sender_bm_id": "12345"
}

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.

Search Results

Compatibilità API Messagio

Impostazioni di connessione

Autenticazione e credenziali

Tipi di messaggi Viber

Formato della risposta

Risposta accettata (riuscita).

Risposte agli errori

Richiamate

1. Richiamata sullo stato della consegna

2. Richiamata della risposta al sondaggio

3. Richiamata messaggio utente in entrata