Documentazione API TopMessage

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:

Invia un singolo messaggio SMS – perfetto per comunicazioni dirette uno a uno come avvisi o conferme.

Parametri di richiesta completi

Nome	Tipo	Descrizione
data	`object`	Contiene informazioni sul messaggio.

Data Object

Nome	Tipo	Descrizione
from	`string`	Nome 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 TopMessage
to	`string[]`	I numeri di cellulare del destinatario in formato internazionale. 391511234567
text	`string`	Il tuo messaggio di testo da inviare ai destinatari. Ciao! Sto provando questa fantastica funzione SMS. https://topmessage.it

Parametri di risposta completi

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

Nome	Tipo	Descrizione
data	`object`	Contiene informazioni sul messaggio.

Data Object

Nome	Tipo	Descrizione
id	`string`	Identificatore univoco del tuo messaggio.
account_id	`string`	Identificatore univoco del tuo account.
status	`string`	Stato iniziale del tuo messaggio. Valori possibili: `PENDING`, `FAILED`, `DELIVERED`, `SEEN`
from	`string`	Nome 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
to	`string[]`	I numeri di cellulare del destinatario in formato internazionale.
text	`string`	Il tuo messaggio di testo da inviare ai destinatari.
channel	`string`	Il canale di comunicazione invia il tuo messaggio. Valori possibili: `SMS` E `WHATSAPP` Predefinito: `SMS`
segment_count	`integer`	Il numero di segmenti di cui era composto il messaggio.
encoding	`string`	Codifica del tuo messaggio. Valori possibili: `STANDARD` E `UNICODE`
direction	`string`	Indica il flusso del messaggio: se è stato inviato dal tuo sistema o ricevuto da un utente. Valori possibili: `OUTBOUND`, `INBOUND`
country	`string`	Specifica il paese del destinatario per i messaggi in uscita e del mittente per quelli in entrata. Il valore è fornito nel formato ISO 3166-1 alpha-2.
type	`string`	Indica il tipo di contenuto del messaggio inviato o ricevuto. Aiuta a capire se si tratta di un testo semplice, di un modello o di un messaggio multimediale (come immagini o video), incluso contenuto interattivo per WhatsApp.
schedule	`string`	Specifica 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
create_date	`string`	Ora in cui è stato avviato il messaggio
update_date	`string`	Data dell'ultimo aggiornamento dello stato del tuo messaggio.

POST

https://api.topmessage.it/v1/messages

X-TopMessage-Key: {API_KEY}
Content-Type: application/json

Richiedi campione

Payload

cURL

Java

Python

PHP

Node.js

{
    "data": {
        "from": "TopMessage",
        "to": [
            "391511234567"
        ],
        "text": "Ciao! Sto provando questa fantastica funzione SMS. https://topmessage.it"
    }
}

Esempio di risposta

{
    "data": [
        {
            "id": "0f15fa5d-97ef-46d5-844a-f507f1c4c461",
            "account_id": "0d1f7f1c-27df-41bf-8bdc-5666608a4285",
            "status": "PENDING",
            "from": "TopMessage",
            "to": "391511234567",
            "text": "Ciao! Sto provando questa fantastica funzione SMS. https://topmessage.it",
            "channel": "SMS",
            "segment_count": "1",
            "encoding": "STANDARD",
            "direction": "OUTBOUND",
            "country": "IT",
            "type": "text",
            "schedule": "2024-11-10T08:11:46Z",
            "create_date": "2024-11-10T08:11:46Z",
            "update_date": "2024-11-10T08:11:46Z"
        }
    ]
}