Platforma komunikacyjna dla deweloperów: MessageFlow API

MessageFlow API to ujednolicone REST API do wysyłki i zarządzania wiadomościami e-mail, SMS, mobile push i Viber. Jako platforma komunikacyjna dla deweloperów łączy w jednym miejscu ruch marketingowy i transakcyjny, zarządzanie kontaktami i śledzenie dostarczenia w czasie rzeczywistym – zgodnie ze specyfikacją JSONAPI i OpenAPI 3.0.2, z obsługą kompresji Gzip.

Dokumentacja API

Jedno REST API – cztery kanały komunikacyjne. Każdy z dedykowanymi endpointami, niezależnym śledzeniem statusów i wydzieloną sekcją w jednej, scentralizowanej dokumentacji deweloperskiej. Zyskaj dostęp do pełnych referencji technicznych, przewodników po uwierzytelnianiu i przykładów requestów. Specyfikacja API jest dostępna w formacie OpenAPI 3.0.2 – gotowa do importu do Postman lub Swagger UI bezpośrednio z dev.messageflow.com/openapi.yaml.

E-mail API

Wysyłaj wiadomości transakcyjne przez REST do 200 odbiorców w pojedynczym żądaniu. Dynamiczne szablony obsługują zmienne, instrukcje warunkowe i pętle po zbiorach danych – wspólny szablon dla wszystkich odbiorców. Statusy dostarczenia możesz pobierać przez API (metody GET), odbierać w czasie rzeczywistym za pomocą webhooków lub przeglądać w panelu analitycznym.

SMS API

Wysyłaj SMS-y transakcyjne z pełnym śledzeniem DLR. Nasze API do dostarczania wiadomości obsługuje Unicode, skracanie linków, priorytetowy routing i komunikację dwukierunkową (SMS przychodzące przez webhooki).

Mobile push API

Wysyłaj powiadomienia push przez REST API na iOS i Android. Zapewniamy obsługę wielojęzycznych treści, obrazów, silent push, TTL i akcji po kliknięciu (URL lub deeplink). Nasze statusy push rozróżniają sześć stanów – od przyjęcia przez operatora aż po interakcję użytkownika.

Viber API

Wybierz API komunikacyjne MessageFlow i wysyłaj wiadomości transakcyjne kanałem OTT Viber z obsługą czterech formatów treści: tekst, obraz, tekst z akcją oraz tekst z obrazem i akcją. Sender wymaga wcześniejszej rejestracji i może mieć maksymalnie 28 znaków. W jednym żądaniu obsłużysz do 200 odbiorców.

Model integracji

MessageFlow API zostało zbudowane na sprawdzonej architekturze technicznej – dostosowanej do środowisk produkcyjnych wysokiej skali.

Architektura i format danych

Wszystkie endpointy REST zwracają JSON z obiektem meta zawierającym kod HTTP, liczbę błędów oraz uniqId – identyfikator każdego żądania, niezbędny przy kontakcie ze wsparciem technicznym. Nasza specyfikacja REST API jest zgodna z JSONAPI i OpenAPI 3.0.2.

{
"meta": {
"numberOfErrors": NUMBER_OF_ELEMENTS_IN_ERRORS (number),
"numberOfData": NUMBER_OF_ELEMENTS_IN_DATA (number),
"status": HTTP_STATUS (number),
"uniqId": UNIQUE_REQUEST_ID (string)
"someField": SOME_VALUE (string)
},
"data": [],
"errors": [
{
"title": ERROR_TITLE (string),
"message": ERROR_MESSAGE (string),
"code": ERROR_CODE (string),
"meta":{
"parameter": SOME_VALUE (string),
"value": SOME_VALUE (string),
"source": SOME_VALUE (string),
"someField": SOME_VALUE (string)
}
}
]
}

Uwierzytelnianie kluczami API

Kontrola dostępu do API opiera się na parze kluczy – Authorization i Application-Key – generowanych i zarządzanych bezpośrednio z panelu. Każdy klucz możesz dodatkowo powiązać z listą dozwolonych adresów IP: nawet przejęty klucz nie umożliwi dostępu do API spoza zaufanej infrastruktury. To istotna warstwa ochrony wszędzie tam, gdzie bezpieczeństwo danych klientów jest krytyczne.

$ curl --request POST \
--header 'Content-Type: application/json' \
--header 'Application-Key: ' \
--header 'Authorization: ' \
--url '...'
--data '{ ... }'

Architektura zdarzeniowa i webhooki

Zamiast cyklicznego pollingu Twoja aplikacja otrzymuje powiadomienia o zdarzeniach w momencie ich wystąpienia – bez zbędnych requestów i opóźnień. Webhooki obsługują wszystkie kanały i pełen zakres zdarzeń: statusy dostarczenia, kliknięcia, otwarcia i błędy. Każde powiadomienie jest kryptograficznie podpisane (SHA1). Dla każdego kanału konfigurujesz dwa adresy URL: jeśli główny endpoint jest niedostępny, zdarzenie automatycznie trafia na zapasowy.

[{
"externalId":"xxxxxxxxxxxxxxxxxxxxxxxx",
"phoneNumber":"+48XXXXXXXXX",
"status":1,
"statusDesc":"DELIVERED",
"statusTime":"2021-04-27T00:00:18",
"webhookUrl":"xxxxxxxxxxxxxxx"
}]

Śledzenie dostarczenia i obsługa statusów

MessageFlow API dostarcza kompletny model statusów dla każdego kanału. Taka architektura pozwala aplikacji integrującej reagować na zdarzenia w czasie rzeczywistym: automatycznie aktualizować rekordy w systemach docelowych, wyzwalać logikę fallback na alternatywne kanały komunikacji oraz utrzymywać rygorystyczną higienę bazy odbiorców poprzez zautomatyzowaną obsługę twardych zwrotek i skarg spamowych.

E-mail API: statusy wiadomości

injected ok  hardbounce softbounce spambounce deferred dropped

Webhooki raportują siedem stanów dla każdej wiadomości — od injected (przyjęta do kolejki) przez ok (dostarczona) aż po hardbounce, softbounce, spambounce, deferreddropped. Każde zdarzenie niesie pełną historię stanów wiadomości (allStatuses), dane nadawcy i odbiorcy oraz znacznik czasu. Platforma automatycznie weryfikuje adresy email przed wysyłką przez wbudowaną bazę spam trapów – bez żadnej konfiguracji z Twojej strony.

SMS API: statusy DLR

SENT DELIVERED UNDELIVERED EXPIRED REJECTED

Zyskaj pełny wgląd w dostarczenie każdego SMS-a: DELIVERED, UNDELIVERED, EXPIRED, REJECTED. Architektura pozwala na monitorowanie raportów DLR na dwa sposoby: asynchronicznie w czasie rzeczywistym za pomocą webhooków lub poprzez odpytywanie dedykowanego endpointa metodą GET. Wybór modelu należy do Ciebie – możesz też wskazać docelowy adres webhooka bezpośrednio w żądaniu wysyłki, kierując statusy DLR do wybranego endpointa niezależnie od domyślnej konfiguracji.

Push API: statusy dostarczenia i interakcji

DELIVERED OPENED REJECTED EXPIRED

Push API raportuje cztery wartości pola statusDesc: DELIVERED, OPENED, REJECTEDEXPIRED, które pozwalają rozróżnić dostarczenie, otwarcie, odrzucenie oraz wygaśnięcie powiadomienia. Pole statusDetails dodatkowo precyzuje typ zdarzenia lub interakcji, np. NOTIFICATION_CLICK_ACTION. Dzięki temu można analizować nie tylko sam fakt dostarczenia push, ale również późniejsze działania użytkownika.

Ustrukturyzowane błędy i odpowiedzi częściowe

Każda odpowiedź z błędem zawiera obiekt JSON z kodem, opisem i kontekstem – parametrem, wartością i źródłem problemu. HTTP 207 Multi-Status oznacza częściowe powodzenie żądania – np. 180 z 200 odbiorców zostało przetworzonych poprawnie, a 20 odrzuconych.

Wydajność i przepustowość

MessageFlow API zostało zaprojektowane pod środowiska produkcyjne, gdzie wolumen wysyłki jest wysoki, a niezawodność dostarczenia – krytyczna.

Kolejkowanie i wysoka przepustowość

Chwilowe przeciążenie po stronie operatora nie zatrzymuje wysyłki. Architektura kolejkowania wiadomości sprawia, że każda wiadomość czeka w kolejce i wychodzi, gdy droga jest wolna – bez konieczności ręcznego ponawiania żądań.


Redundancja i monitoring niezawodności

Infrastruktura oparta na redundantnych węzłach z automatycznym failoverem. Stan platformy monitorujesz publicznie przez Status Page – albo wbudowujesz endpoint GET /v2.1/service/status bezpośrednio we własny system monitoringu i reagujesz programistycznie.

                        
{
"meta": {
"numberOfErrors": 0,
"numberOfData": 1,
"status": 200,
"uniqId": "00d928f759"
},
"errors": [
{
"title": "Empty result",
"message": "Not found any result with this query",
"code": "E-0-005"
}
]
}

Zasoby dla developerów

Skorzystaj z gotowych zasobów skracających czas do pierwszej integracji – niezależnie od stosu technologicznego. Przykłady kodu dostępne są w C#, Java, Node.js, PHP, Python i Go – każdy zawiera poprawne uwierzytelnianie, strukturę payloadu i obsługę odpowiedzi API.

Wysyłka SMS przez messaging API
using System.Net.Http.Headers;
var client = new HttpClient();
var request = new HttpRequestMessage
{
Method = HttpMethod.Post,
RequestUri = new Uri("https://api.messageflow.com/v2.1/sms"),
Headers =
{
{ "Accept", "application/json" },
{ "Authorization", "123" },
{ "Application-Key", "123" },
},
Content = new StringContent("{\n \"sender\": \"string\",\n \"message\": \"Twoja wiadomość testowa\",\n \"phoneNumbers\": [\n \"+48111222333\",\n \"+48111222444\"\n ],\n \"phoneNumber\": \"+48111222333\",\n \"validity\": 4320,\n \"scheduleTime\": 0,\n \"type\": 0,\n \"shortLink\": true,\n \"webhookUrl\": \"string\",\n \"externalId\": \"xxxx-xxxx-xxxx\"\n}")
{
Headers =
{
ContentType = new MediaTypeHeaderValue("application/json")
}
}
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.messageflow.com/v2.1/sms"))
.header("Content-Type", "application/json")
.header("Accept", "application/json")
.header("Authorization", "123")
.header("Application-Key", "123")
.method("POST", HttpRequest.BodyPublishers.ofString("{\n \"sender\": \"string\",\n \"message\": \"Twoja wiadomość testowa\",\n \"phoneNumbers\": [\n \"+48111222333\",\n \"+48111222444\"\n ],\n \"phoneNumber\": \"+48111222333\",\n \"validity\": 4320,\n \"scheduleTime\": 0,\n \"type\": 0,\n \"shortLink\": true,\n \"webhookUrl\": \"string\",\n \"externalId\": \"xxxx-xxxx-xxxx\"\n}"))
.build();

HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
import http.client

conn = http.client.HTTPSConnection("api.messageflow.com")

payload = "{\n \"sender\": \"string\",\n \"message\": \"Twoja wiadomość testowa\",\n \"phoneNumbers\": [\n \"+48111222333\",\n \"+48111222444\"\n ],\n \"phoneNumber\": \"+48111222333\",\n \"validity\": 4320,\n \"scheduleTime\": 0,\n \"type\": 0,\n \"shortLink\": true,\n \"webhookUrl\": \"string\",\n \"externalId\": \"xxxx-xxxx-xxxx\"\n}"

headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "123",
'Application-Key': "123"
}

conn.request("POST", "/v2.1/sms", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.messageflow.com/v2.1/sms",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'sender' => 'string',
'message' => 'Twoja wiadomość testowa',
'phoneNumbers' => [
'+48111222333',
'+48111222444'
],
'phoneNumber' => '+48111222333',
'validity' => 4320,
'scheduleTime' => 0,
'type' => 0,
'shortLink' => null,
'webhookUrl' => 'string',
'externalId' => 'xxxx-xxxx-xxxx'
]),
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Application-Key: 123",
"Authorization: 123",
"Content-Type: application/json"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"io"
"net/http"
"strings"
)

func main() {

url := "https://api.messageflow.com/v2.1/sms"

payload := strings.NewReader("{\n \"sender\": \"string\",\n \"message\": \"Hello world!\",\n \"phoneNumbers\": [\n \"+48111222333\",\n \"+48111222444\"\n ],\n \"phoneNumber\": \"+48111222333\",\n \"validity\": 4320,\n \"scheduleTime\": 0,\n \"type\": 0,\n \"shortLink\": true,\n \"webhookUrl\": \"string\",\n \"externalId\": \"xxxx-xxxx-xxxx\"\n}")

req, _ := http.NewRequest("POST", url, payload)

req.Header.Add("Content-Type", "application/json")
req.Header.Add("Accept", "application/json")
req.Header.Add("Authorization", "123")
req.Header.Add("Application-Key", "123")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(res)
fmt.Println(string(body))

}
const response = await fetch('https://api.messageflow.com/v2.1/sms', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'YOUR_AUTHORIZATION_TOKEN',
'Application-Key': 'YOUR_APPLICATION_KEY'
},
body: JSON.stringify({
sender: 'YourCompany',
message: 'Hello world!',
phoneNumbers: ['+48111222333']
})
});

const data = await response.json();

console.log(data);

Przewodnik po webhookach

Sprawdź pełną dokumentację konfiguracji webhooków: formaty danych, mechanizmy powtórzeń i weryfikację autentyczności żądań. Gdy główny endpoint nie odpowie w ciągu 500 ms, zdarzenie automatycznie trafia na zapasowy URL. Konfiguracja dostępna w panelu lub bezpośrednio przez API.

Wsparcie techniczne

Oferujemy wsparcie integracyjne dla zespołów developerskich i IT na każdym etapie wdrożenia. Klienci korzystający z dedykowanych Pakietów Supportowych otrzymują dostęp do Technical Account Managera (TAM), który prowadzi integrację i dba o ciągłość działania środowiska produkcyjnego.

Onboarding techniczny

Przeprowadzimy Cię przez cały proces integracji – od wygenerowania pierwszych kluczy API po uruchomienie produkcyjne. Dostosujemy konfigurację do Twojego środowiska technicznego i wymagań bezpieczeństwa.

Konsultacje dostarczalności

Pomożemy Ci wycisnąć maksimum z każdego kanału. Dla email: konfiguracja SPF, DKIM i DMARC. Dla SMS: dobór routingu przez operatorów lokalnych. Działamy razem, żeby Twoje wiadomości trafiały tam, gdzie powinny.

Wsparcie drugiego poziomu

Jeśli napotkasz złożony problem integracyjny, trafia on bezpośrednio do wyspecjalizowanego zespołu technicznego z gwarantowanym czasem odpowiedzi. W zgłoszeniu wystarczy podać meta.uniqId z odpowiedzi API – resztą zajmiemy się my.

FAQ: integracja przez REST API MessageFlow

Oto niektóre z najczęściej zadawanych pytań, na które odpowiadają nasi eksperci.

Każde żądanie wymaga dwóch nagłówków HTTP jednocześnie: Authorization z 128-znakowym kluczem autoryzacji oraz Application-Key z kluczem aplikacji. Oba klucze generujesz w panelu administracyjnym (Konto → Ustawienia → API). Możliwe jest opcjonalne ograniczenie dostępu do API wyłącznie z określonych adresów IP – konfiguracja per klucz. Brak któregokolwiek nagłówka skutkuje odpowiedzią HTTP 401 Unauthorized.

Tak – webhooki to centralny mechanizm powiadomień o zdarzeniach w MessageFlow. Obsługiwane zdarzenia obejmują statusy dostarczenia (DLR), otwarcia, kliknięcia i zdarzenia błędów dla wszystkich kanałów. Dla każdego typu webhooka konfigurujesz dwa URL-e (domyślny i zapasowy) – failover następuje automatycznie. Konfiguracja przez panel (Konto → Ustawienia → Webhooki) lub bezpośrednio przez API.

Statusy dostarczenia przekazywane są przez webhooki w czasie rzeczywistym – bez konieczności pollingu. Dla SMS: kody DLR (DELIVERED, UNDELIVERED, EXPIRED, REJECTED). Dla email: statusy zdarzeń (injected, ok, hardbounce, softbounce, spambounce, dropped, deferred). Dla push: sześć stanów od przyjęcia przez operatora aż po interakcję użytkownika. Dla Viber: statusy dostarczenia i interakcji. Wszystkie zdarzenia dostępne są również w przeszukiwalnym panelu operacyjnym.

REST API MessageFlow oparte jest na formacie JSON zgodnym ze specyfikacją JSONAPI. Żądania obsługują kompresję Gzip (Content-Encoding: gzip) w celu optymalizacji transferu. Specyfikacja API dostępna jest w formacie OpenAPI 3.0.2 pod adresami dev.messageflow.com/openapi.yamldev.messageflow.com/openapi.json – gotowa do importu do Postman lub Swagger UI.

Redlink API to poprzednia nazwa interfejsu API platformy MessageFlow. Jeśli korzystasz z dokumentacji lub kodu opartego na Redlink API, zasoby dostępne są w sekcji historii wersji. Skontaktuj się z zespołem technicznym w przypadku pytań dotyczących migracji.

RSS