Jak wysłać pierwszego SMS-a przez API w 5 minut – kompletny przewodnik

Załóż konto na stronie rejestracji – dostajesz 100 SMS gratis, bez karty kredytowej i bez umowy. Aktywacja jest natychmiastowa, więc nie czekasz na akceptację handlową ani na „kontakt w ciągu 24h".

W panelu przejdź do Ustawienia → API → Generuj i utwórz Bearer Token. To poświadczenie w stylu OAuth2: dołączasz je w nagłówku każdego żądania. Potraktuj token jak hasło – trzymaj go w zmiennych środowiskowych (np. ACTIO_TOKEN), nigdy w repozytorium ani w kodzie front-endu. Jeśli token wycieknie, unieważnij go w panelu i wygeneruj nowy; stary natychmiast przestaje działać.

Najszybszy test to jedno wywołanie z terminala. Endpoint przyjmuje JSON i zwraca identyfikator wiadomości oraz status:

curl -X POST https://msg-api.actio.pl/api/sms \
  -H "Authorization: Bearer $ACTIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "FirmaXYZ",
    "to": "48732129000",
    "body": "Twój kod logowania: 482910"
  }'

Trzy pola robią całą robotę: from (nazwa nadawcy lub numer w formacie E.164), to (numer odbiorcy w E.164 bez znaku „+") oraz body (treść w UTF-8). Pełna referencja, w tym pola opcjonalne jak scheduled_at i idempotency_key, jest w dokumentacji.

API jest czystym REST-em, więc działa z każdym językiem, który mówi po HTTP – bez instalowania zamkniętych bibliotek. W Node.js wystarczy wbudowany fetch:

const res = await fetch("https://msg-api.actio.pl/api/sms", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ACTIO_TOKEN}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    from: "FirmaXYZ",
    to: "48732129000",
    body: "Twój kod: 482910"
  })
});
const data = await res.json();
console.log(data.message_id);

W Pythonie analogicznie użyjesz requests.post(...), w PHP cURL, w Go standardowego net/http. Gotowe wycinki w pięciu językach znajdziesz w dokumentacji – kopiujesz, podmieniasz token i działa.

Wysłanie SMS-a to dopiero połowa historii – chcesz wiedzieć, czy dotarł. Zamiast odpytywać API w pętli (kosztowne i wolne), skonfiguruj webhook: wskazujesz swój URL, a my wysyłamy na niego event przy każdej zmianie statusu – sms.delivered, sms.failed, sms.expired, sms.bounced. Payload zawiera message_id, znacznik czasu i operatora docelowego. Dzięki temu Twój system reaguje w czasie rzeczywistym, np. ponawia wysyłkę na inny numer, gdy SMS się odbił.

Na produkcji liczy się odporność na powtórzenia. Jeśli Twój serwer wyśle ten sam request dwa razy (timeout, retry kolejki), bez zabezpieczenia odbiorca dostanie dwa SMS-y. Rozwiązanie to nagłówek/pole idempotency_key (UUID v4): ten sam klucz gwarantuje, że wiadomość wyjdzie tylko raz.

Warto też z góry obsłużyć najczęstsze kody odpowiedzi: 401 (zły token), 402 (brak środków), 422 (błędny numer lub treść), 429 (limit – sprawdź nagłówek Retry-After). Dobra integracja loguje message_id i status, a przy 429 stosuje wykładniczy backoff.

To samo API obsłuży trzy zupełnie różne scenariusze bez zmiany integracji: powiadomienia transakcyjne (status zamówienia, przypomnienie o wizycie), kody 2FA / OTP oraz masowe kampanie do tysięcy odbiorców. Rozliczenie jest pay-as-you-go, bez abonamentu i progów wejścia – stawkę dla swojego wolumenu sprawdzisz w cenniku.