API

API

Autenticazione

Quando effettui richieste API, devi includere la chiave API nell'intestazione HTTP. Il formato dell'intestazione dovrebbe assomigliare a questo:

X-TopMessage-Key: {API_KEY}
Gestisci le tue chiavi API

qui

Invia messaggi

Invia facilmente uno o più messaggi ai tuoi clienti tramite i loro canali preferiti, come SMS e WhatsApp, utilizzando un'unica API unificata. Inizia con un semplice messaggio di testo definendone destinazione e contenuto, oppure sfrutta funzionalità avanzate per potenziare la tua strategia di comunicazione.

Esempi di casi d'uso

Di seguito sono riportati alcuni esempi di casi d'uso per l'API TopMessage:

  • SMS semplici
  • SMS personalizzati
  • SMS con collegamento abbreviato
  • Verifica tramite SMS
  • SMS con modello
  • WhatsApp con modello
  • Risposta in formato libero di WhatsApp
  • Messaggio pianificato
  • Messaggi in blocco
Parametri di richiesta completi
NomeTipoDescrizione
dataobjectContiene i seguenti dettagli del messaggio inviato.
DataObject
NomeTipoDescrizione
fromstringNome visualizzato dal quale verrà inviato il tuo messaggio. Puoi controllare i nomi disponibili o crearne uno nuovo nella pagina dei mittenti.Vai alla pagina dei mittenti.
tostring[]I numeri di cellulare del destinatario in formato internazionale.
textstringIl tuo messaggio di testo da inviare ai destinatari.
channelstringIl canale di comunicazione invia il tuo messaggio.
Valori possibili: SMS E WHATSAPP
Predefinito: SMS
template_idstringIdentificatore univoco del tuo modello inviato. Puoi controllare i modelli disponibili o crearne uno nuovo dalla pagina dei modelli del tuo account.Vai alla pagina dei modelli.
parametersstring[]Questi valori vengono utilizzati per sostituire i segnaposto nel modello di messaggio, consentendoti di personalizzare il messaggio per ciascun destinatario.
Predefinito: Vuoto
shorten_URLsbooleanIndica se gli URL HTTPS nel testo devono essere sostituiti con URL abbreviati.
Valori possibili: TRUE E FALSE
Predefinito: FALSE
request_idstringIdentificatore univoco della richiesta da te generato per tracciare le richieste.
Predefinito: NULL
schedulestringSpecifica l'orario in cui il messaggio deve essere inviato. L'orario deve essere in UTC e seguire il formato ISO-8601 ("2024-12-01T18:00:00Z"). L'orario programmato non può essere impostato a più di 1 anno nel futuro.
Predefinito: Ora
Parametri di risposta completi
Parametri di risposta

La risposta include tutti i parametri della richiesta, insieme ai parametri aggiuntivi elencati di seguito.

DataObject
NomeTipoDescrizione
account_idstringIdentificatore univoco del tuo account.
idstringIdentificatore univoco del tuo messaggio.
statusstringStato iniziale del tuo messaggio.
Valori possibili: PENDING, FAILED, DELIVERED, SEEN
create_datestringOra in cui è stato avviato il messaggio
update_datestringData dell'ultimo aggiornamento dello stato del tuo messaggio.
segment_countintegerIl numero di segmenti di cui era composto il messaggio.
encodingstringCodifica del tuo messaggio.
Valori possibili: STANDARD E UNICODE
POST
https://api.topmessage.it/v1/messages
X-TopMessage-Key: {API_KEY}
Content-Type: application/json
Richiedi campione

Payload

cURL

Java

Python

{
    "data": {
        "from": "TopMessage",
        "to": [
            "48727516980",
            "48727516981"
        ],
        "parameters": {
            "48727516980": ["John"],
            "48727516981": ["Ann"]
        },
        "text": "Hi {first_name}! Just testing out this cool SMS feature.https://topmessage.com",
        "shorten_URLs": true,
        "request_id": "9190cda0-70d8-4127-ac8f-787c083efa1b",
        "schedule": "2024-12-01T00:00:01Z"
    }
}
curl -X POST "https://api.topmessage.com/v1/messages" -H "Content-Type: application/json" -H "X-TopMessage-Key: {API_KEY}" -d '{
    "data": {
        "from": "TopMessage",
        "to": [
            "48727516980",
            "48727516981"
        ],
        "parameters": {
            "48727516980": ["John"],
            "48727516981": ["Ann"]
        },
        "text": "Hi {first_name}! Just testing out this cool SMS feature.https://topmessage.com",
        "request_id": "9190cda0-70d8-4127-ac8f-787c083efa1b",
        "shorten_URLs": true,
        "schedule": "2024-12-01T00:00:01Z"
     }
  }'
String response = HttpClient.newHttpClient().send(
    HttpRequest.newBuilder()
        .uri(URI.create("https://api.topmessage.com/v1/messages"))
        .header("Content-Type", "application/json")
        .header("X-TopMessage-Key", "{API_KEY}")
        .POST(HttpRequest.BodyPublishers.ofString("""
            {
                "data": {
                    "from": "TopMessage",
                    "to": [
                        "48727516980",
                        "48727516981"
                    ],
                    "parameters": {
                        "48727516980": ["John"],
                        "48727516981": ["Ann"]
                    },
                    "text": "Hi {first_name}! Just testing out this cool SMS feature. https://topmessage.com",
                    "request_id": "9190cda0-70d8-4127-ac8f-787c083efa1b",
                    "shorten_URLs": true,
                    "schedule": "2024-12-01T00:00:01Z"
                }
            }
            """))
        .build(),
    HttpResponse.BodyHandlers.ofString()
).body();
response = requests.post(
    "https://api.topmessage.com/v1/messages",
    headers={
        "Content-Type": "application/json",
        "X-TopMessage-Key": "{API_KEY}"
    },
    json={
       "data": {
            "from": "TopMessage",
            "to": ["48727516980", "48727516981"],
            "parameters": {
                "48727516980": ["John"],
                "48727516981": ["Ann"]
            },
            "text": "Hi {first_name}! Just testing out this cool SMS feature.https://topmessage.com",
            "request_id": "9190cda0-70d8-4127-ac8f-787c083efa1b",
            "shorten_URLs": true,
            "schedule": "2024-12-01T00:00:01Z"
        }
    }
)
Esempio di risposta
{
    "data": [
        {
            "id": "0f15fa5d-97ef-46d5-844a-f507f1c4c461",
            "account_id": "0d1f7f1c-27df-41bf-8bdc-5666608a4285",
            "template_id": "7c3f35bc-491e-4580-a8b8-602efae1ccd1",
            "status": "PENDING",
            "from": "TopMessage",
            "to": "48727516980",
            "text": "Hi {first_name}! Just testing out this cool SMS feature. https://topmessage.com",
            "parameters": [
                "John"
            ],
            "channel": "SMS",
            "segment_count": 1,
            "encoding": "STANDARD",
            "schedule": "2024-11-20T08:11:46Z",
            "create_date": "2024-11-25T06:58:22Z",
            "update_date": "2024-11-25T06:58:22Z"
        },
        {
            "id": "6fc214dc-4e51-4fce-bc0a-324a1d8a542b",
            "account_id": "0d1f7f1c-27df-41bf-8bdc-5666608a4285",
            "template_id": "7c3f35bc-491e-4580-a8b8-602efae1ccd1",
            "status": "PENDING",
            "from": "TopMessage",
            "to": "48727516981",
            "text": "Hi {first_name}! Just testing out this cool SMS feature.",
            "parameters": [
                "Ann"
            ],
            "channel": "SMS",
            "segment_count": 1,
            "encoding": "STANDARD",
            "schedule": "2024-11-20T08:11:46Z",
            "create_date": "2024-11-25T06:58:22Z",
            "update_date": "2024-11-25T06:58:22Z"
        }
    ]
}