API

Authentifizierung

Wenn Sie API-Anfragen stellen, müssen Sie Ihren API-Schlüssel in den HTTP-Header aufnehmen. Das Header-Format sollte folgendermaßen aussehen:

X-TopMessage-Key: {API_KEY}

API-Schlüssel verwalten

hier

Nachrichten senden

Senden Sie Ihren Kunden ganz einfach eine oder mehrere Nachrichten über ihre bevorzugten Kanäle wie SMS und WhatsApp mithilfe einer einzigen, einheitlichen API. Beginnen Sie mit einer einfachen Textnachricht, indem Sie das Ziel und den Inhalt definieren, oder nutzen Sie erweiterte Funktionen, um Ihre Kommunikationsstrategie zu verbessern.

Anwendungsbeispiele

Nachfolgend sind einige Anwendungsbeispiele für die TopMessage-API aufgeführt:

Einfache SMS
Personalisierte SMS
SMS mit verkürztem Link
Bestätigungs-SMS
SMS mit Vorlage
WhatsApp mit Vorlage
Freiform-Antwort auf WhatsApp
Geplante Nachricht
Massennachrichten

Vollständige Anforderungsparameter

Name	Typ	Beschreibung
data	`Objekt`	Enthält die folgenden Details der gesendeten Nachricht.

Datenobjekt

Name	Typ	Beschreibung
from	`string`	Anzeigename, von dem Ihre Nachricht gesendet wird. Sie können auf der Absenderseite die verfügbaren Namen überprüfen oder einen neuen für Ihr Konto erstellen.Zur Absenderseite gehen.
to	`string[]`	Die Mobiltelefonnummer(n) des Empfängers im internationalen Format.
text	`string`	Ihr Nachrichtentext, der an den/die Empfänger gesendet werden soll.
channel	`string`	Der Kommunikationskanal, über den Ihre Nachricht gesendet wurde. Möglichen Werte: `SMS` und `WHATSAPP` Standard: `SMS`
template_id	`string`	Eindeutiger Bezeichner Ihrer gesendeten Vorlage. Sie können die verfügbaren Vorlagen auf der Vorlagenseite einsehen oder eine neue erstellen.Zur Vorlagenseite gehen.
parameters	`string[]`	Diese Werte werden verwendet, um die Platzhalter in Ihrer Nachrichtenvorlage zu ersetzen, sodass Sie die Nachricht für jeden Empfänger anpassen können. Standard: Leer
shorten_URLs	`boolean`	Gibt an, ob HTTPS-URLs im Text durch verkürzte URLs ersetzt werden sollen. Möglichen Werte: `TRUE` und `FALSE` Standard: `FALSE`
request_id	`string`	Eindeutige Kennung der von Ihnen generierten Anfrage zum Verfolgen von Anfragen. Standard: `NULL`
schedule	`string`	Gibt die Zeit an, zu der die Nachricht gesendet werden soll. Die Zeit muss in UTC sein und dem ISO-8601-Format folgen ("2024-12-01T18:00:00Z"). Die geplante Zeit kann nicht mehr als 1 Jahr in der Zukunft festgelegt werden. Standard: Jetzt

Vollständige Antwortparameter

Antwortparameter

Die Antwort enthält alle Parameter aus der Anfrage sowie die unten aufgeführten zusätzlichen Parameter.

Datenobjekt

Name	Typ	Beschreibung
account_id	`string`	Eindeutige Kennung Ihres Kontos.
id	`string`	Eindeutige Kennung Ihrer Nachricht.
status	`string`	Anfangsstatus Ihrer Nachricht. Möglichen Werte: `PENDING`, `FAILED`, `DELIVERED`, `SEEN`
create_date	`string`	Zeitpunkt, zu dem die Nachricht initiiert wurde
update_date	`string`	Datum der letzten Statusaktualisierung Ihrer Nachricht.
segment_count	`integer`	Die Anzahl der Segmente, aus denen Ihre Nachricht bestand.
encoding	`string`	Kodierung Ihrer Nachricht. Möglichen Werte: `STANDARD` und `UNICODE`

POST

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

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

Anfragebeispiel

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"
        }
    }
)

Antwortbeispiel

{
    "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"
        }
    ]
}