API

Uwierzytelnianie

Wysyłając żądania API, musisz umieścić swój klucz API w nagłówku HTTP. Format nagłówka powinien wyglądać następująco:

X-TopMessage-Key: {API_KEY}

Zarządzaj kluczami API

tutaj

Wysyłaj wiadomości

Z łatwością wyślij jedną lub więcej wiadomości do swoich klientów za pośrednictwem preferowanych przez nich kanałów, takich jak SMS i WhatsApp, korzystając z jednego, ujednoliconego interfejsu API. Zacznij od prostej wiadomości tekstowej, określając miejsce docelowe i treść, lub wykorzystaj zaawansowane funkcje, aby ulepszyć swoją strategię komunikacji.

Przykłady przypadków użycia

Poniżej przedstawiono kilka przykładów przypadków użycia interfejsu API TopMessage:

Prosty SMS
Spersonalizowane SMS-y
SMS ze skróconym linkiem
Weryfikacja SMS-em
SMS Z Szablonem
WhatsApp Z Szablonem
Odpowiedź w dowolnej formie WhatsApp
Zaplanowana wiadomość
Wiadomości zbiorcze

Pełne parametry żądania

Nazwa	Uprzejmy	Opis
data	`object`	Zawiera poniższe szczegóły wysyłanej wiadomości.

Obiekt danych

Nazwa	Uprzejmy	Opis
from	`string`	Nazwa wyświetlana, z której zostanie wysłana Twoja wiadomość. Sprawdź dostępne nazwy lub utwórz nową na stronie nadawców.Przejdź do strony nadawców.
to	`string[]`	Numer telefonu komórkowego odbiorcy w formacie międzynarodowym.
text	`string`	Twoja wiadomość tekstowa, która zostanie wysłana do odbiorców.
channel	`string`	Kanał komunikacyjny przesyła Twoją wiadomość. Możliwe wartości: `SMS` I `WHATSAPP` Domyślny: `SMS`
template_id	`string`	Unikalny identyfikator Twojego wysłanego szablonu. Możesz sprawdzić dostępne szablony lub utworzyć nowy na stronie szablonów w swoim koncie.Przejdź do strony szablonów.
parameters	`string[]`	Wartości te służą do zastąpienia symboli zastępczych w szablonie wiadomości, co pozwala dostosować wiadomość dla każdego odbiorcy. Domyślny: Pusty
shorten_URLs	`boolean`	Wskazuje, czy adresy URL HTTPS w tekście powinny zostać zastąpione skróconymi adresami URL. Możliwe wartości: `TRUE` I `FALSE` Domyślny: `FALSE`
request_id	`string`	Unikalny identyfikator żądania wygenerowanego przez Ciebie w celu śledzenia żądań. Domyślny: `NULL`
schedule	`string`	Określa czas, kiedy wiadomość ma zostać wysłana. Czas musi być w UTC i musi być zgodny z formatem ISO-8601 ("2024-12-01T18:00:00Z"). Czas zaplanowany nie może być ustawiony na więcej niż 1 rok w przyszłość. Domyślny: Teraz

Pełne parametry odpowiedzi

Parametry odpowiedzi

Odpowiedź zawiera wszystkie parametry z żądania wraz z dodatkowymi parametrami wymienionymi poniżej.

Obiekt danych

Nazwa	Uprzejmy	Opis
account_id	`string`	Unikalny identyfikator Twojego konta.
id	`string`	Unikalny identyfikator Twojej wiadomości.
status	`string`	Początkowy status Twojej wiadomości. Możliwe wartości: `PENDING`, `FAILED`, `DELIVERED`, `SEEN`
create_date	`string`	Godzina zainicjowania wiadomości
update_date	`string`	Data ostatniej aktualizacji statusu Twojej wiadomości.
segment_count	`integer`	Liczba segmentów, z których składała się Twoja wiadomość.
encoding	`string`	Kodowanie Twojej wiadomości. Możliwe wartości: `STANDARD` I `UNICODE`

POST

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

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

Poproś o próbkę

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

Próbka odpowiedzi

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