API

API

Authenticatie

Wanneer u API-verzoeken doet, moet u uw API-sleutel in de HTTP-header opnemen. Het headerformaat zou er als volgt uit moeten zien:

X-TopMessage-Key: {API_KEY}
Beheer uw API-sleutels

hier

Berichten verzenden

Stuur eenvoudig één of meerdere berichten naar uw klanten via hun favoriete kanalen, zoals sms en WhatsApp, met behulp van één uniforme API. Begin met een eenvoudig sms-bericht door de bestemming en inhoud te definiëren, of maak gebruik van geavanceerde functies om uw communicatiestrategie te verbeteren.

Gebruiksvoorbeelden

Hieronder volgen enkele voorbeelden van use cases voor de TopMessage API:

  • Eenvoudig sms'en
  • Gepersonaliseerde SMS-berichten
  • SMS met verkorte link
  • SMS-verificatie
  • SMS met sjabloon
  • WhatsApp met sjabloon
  • WhatsApp antwoord in vrije vorm
  • Gepland bericht
  • Bulkberichten
Volledige aanvraagparameters
NaamVriendelijkBeschrijving
dataobjectBevat de onderstaande details van het bericht dat wordt verzonden.
GegevensObject
NaamVriendelijkBeschrijving
fromstringWeergavenaam waarvan je bericht wordt verzonden. Je kunt de beschikbare namen bekijken of een nieuwe aanmaken op de afzenderspagina.Ga naar de afzenderspagina.
tostring[]Het (de) mobiele telefoonnummer(s) van de ontvanger in internationaal formaat.
textstringUw sms-bericht dat naar de ontvanger(s) wordt verzonden.
channelstringHet communicatiekanaal stuurt uw boodschap door.
Mogelijke waarden: SMS En WHATSAPP
Standaard: SMS
template_idstringUnieke identificatie van je verzonden sjabloon. Je kunt de beschikbare sjablonen bekijken of een nieuwe aanmaken via de sjablonenpagina van je account.Ga naar de sjablonenpagina.
parametersstring[]Deze waarden worden gebruikt om de tijdelijke aanduidingen in uw berichtsjabloon te vervangen, waardoor u het bericht voor elke ontvanger kunt aanpassen.
Standaard: Leeg
shorten_URLsbooleanGeeft aan of HTTPS-URL's in de tekst moeten worden vervangen door verkorte URL's.
Mogelijke waarden: TRUE En FALSE
Standaard: FALSE
request_idstringUnieke identificatie van het verzoek dat door u wordt gegenereerd om verzoeken te traceren.
Standaard: NULL
schedulestringGeeft de tijd aan wanneer het bericht verzonden moet worden. De tijd moet in UTC zijn en het ISO-8601-formaat volgen ("2024-12-01T18:00:00Z"). De geplande tijd mag niet meer dan 1 jaar in de toekomst worden ingesteld.
Standaard: Nu
Volledige responsparameters
Reactieparameters

Het antwoord bevat alle parameters van de aanvraag, samen met de aanvullende parameters die hieronder worden vermeld.

GegevensObject
NaamVriendelijkBeschrijving
account_idstringUnieke identificatie van uw account.
idstringUnieke identificatie van uw bericht.
statusstringInitiële status van uw bericht.
Mogelijke waarden: PENDING, FAILED, DELIVERED, SEEN
create_datestringTijdstip waarop het bericht is geïnitieerd
update_datestringLaatste statusupdatedatum van uw bericht.
segment_countintegerHet aantal segmenten waaruit uw bericht bestond.
encodingstringCodering van uw bericht.
Mogelijke waarden: STANDARD En UNICODE
POST
https://api.topmessage.nl/v1/messages
X-TopMessage-Key: {API_KEY}
Content-Type: application/json
Monster aanvragen

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