Setera SMS API Gateway - Panoramica

L'SMS API Gateway di Setera consente alle aziende di inviare e ricevere messaggi SMS attraverso semplici integrazioni via API. È una soluzione scalabile, veloce e sicura per automatizzare le comunicazioni verso clienti, partner o dipendenti.

Sono disponibili due modalità operative (profili):

• 1-Way SMS (MT - Mobile Terminated): invio di SMS verso i destinatari

• 2-Way SMS (MO - Mobile Originated): invio e ricezione di SMS tramite webhook o email

Caratteristiche dei profili SMS

Per utilizzare il servizio SMS Setera (sia per l'invio che per la ricezione), è necessario disporre di un profilo SMS dedicato.
Ogni profilo è configurato con capacità specifiche, che variano in base al tipo di utilizzo (1-way o 2-way).

Nota: l’utilizzo di un Sender ID Testuale per impersonare soggetti terzi comporta la sospensione immediata del profilo.

INDICE DEI CONTENUTI

• Profili per SMS API
  • 1-Way SMS (Solo Invio)
  • 2-Way SMS (Invio + Ricezione)
• Modalità di Invio SMS
  • Metodo GET
  • Metodo POST (JSON)
• Ricezione SMS (2-Way / MO)
  • Webhook URL (POST JSON)
  • Ricezione via Email
• Report di Consegna (Delivery Reports)
• Recupero API Key
• Codici di Errore Comuni

Profili per SMS API

1-Way SMS (Solo Invio)

Permette l'invio di SMS a uno o più destinatari. Non è possibile ricevere risposte.

Ideale per:

• Notifiche automatiche (OTP, Token, ecc...)

• Comunicazioni unidirezionali (Conferme, Promemoria appuntamenti ecc...)

• Promozioni e campagne marketing

2-Way SMS (Invio + Ricezione)

Consente anche la ricezione di risposte via webhook o email. Il profilo 2-way SMS richiede una configurazione dedicata del canale di ricezione.

Ideale per:

• Supporto clienti via SMS

• Sondaggi, conferme o feedback

• Conversazioni interattive con i clienti

Modalità di Invio SMS

Setera SMS API Gateway supporta i metodi di invio GET e POST:

Metodo GET

Endpoint:

https://sms-api.setera.com/api/plain.php

Parametri URL:

• key: API Key specifica dell’account

• type: Tipo di messaggio (text o unicode)

• contacts: Numeri di telefono nel formato E.164 (senza segno +), separati da virgole

• senderid: ID mittente approvato

• msg: Contenuto del messaggio (max 740 caratteri, URL encoded)

Esempio:

https://sms-api.setera.com/api/plain.php?key=a1b2c3d4f5g6&type=text&contacts=358401234567,358507654321&senderid=3584577508999&msg=hello%20world!

{
    "status": "success",
    "items": [
        {
            "shoot_id": "api_67f66d8d307c1",
            "messageid": 392605,
            "destination": "358401234567",
            "status": "sent"
        }
    ]
}

Metodo POST (JSON)

Endpoint:

https://sms-api.setera.com/api/json.php

{
  "key": "a1b2c3d4f5g6",
  "type": "text",
  "contacts": "358401234567,358507654321",
  "senderid": "3584577508999",
  "msg": "hello world!"
}

Risposta di esempio:

{
  "status": "success"
}

Risposta con errore:

{
  "status": "error",
  "error": "Authentication Failure",
  "code": "1001"
}

Ricezione SMS (2-Way / MO)

Se si sceglie la tipologia 2-way, puoi ricevere SMS tramite:

Webhook URL (POST JSON)

Formato del messaggio ricevuto:

{
  "msg_id": "101",
  "from": "358401234567",
  "to": "3584577508999",
  "message": "hello world!"
}

• from: Numero del mittente (utente finale)

• to: Numero configurato su Setera

• message: Testo del messaggio ricevuto

Il contenuto viene inviato via POST alla URL specificata al momento della configurazione.

Ricezione via Email

Setera può inoltrare i messaggi ricevuti anche tramite email.

Esempio di email:

From: Setera SMS <sms@setera.com>
To: <tua_email@dominio.it>
Subject: Text From : +358401234567 To +3584577508999

Hello World!

È possibile configurare sia Webhook che Email in parallelo per lo stesso account.

Report di Consegna (Delivery Reports)

È possibile verificare lo stato di consegna degli SMS inviati tramite:

Endpoint:

https://sms-api.setera.com/app/miscapi/YOUR_API_KEY/getJsonDLR/SMS_SHOOT_ID

Risposta di esempio:

[
  {
    "destination": "358401234567",
    "status": "delivered"
  },
  {
    "destination": "358507654321",
    "status": "failed"
  }
]

Recupero API Key

In caso di smarrimento, la API Key può essere recuperata tramite:

Endpoint:

https://sms-api.setera.com/app/getJsonkey/USERNAME/PASSWORD/

Codici di Errore Comuni