SMS w n8n bez kodu: HTTP Request, ponowienia i webhook DLR

1. Przygotuj dane i Credentials

Utwórz konto SMS i zweryfikuj własny numer testowy. Zapisz klucz z zakresem send w Credentials typu HTTP Header Auth: nazwa nagłówka Authorization, wartość Bearer TWÓJ_KLUCZ. Zakres read przyda się do późniejszego odczytu wiadomości. Nie umieszczaj sekretu w zwykłym polu workflow ani w eksportowanym przykładzie.

Na wejściu przygotuj ID zgłoszenia, numer w formacie międzynarodowym i gotową treść. Filtr powinien odrzucać rekordy bez numeru oraz zdarzenia, dla których wynik wysyłki jest już zapisany. Self-hosting n8n nie zatrzymuje danych wyłącznie na Twoim serwerze: numer i treść trafią do API SMS.

2. Ustaw HTTP Request i body JSON

Wybierz POST i URL https://api.przypominamy.com/v1/messages. Podłącz zapisane Credentials. Włącz Send Body, ustaw JSON i zmapuj pola to, text, reference. Mapowanie pól jest wygodniejsze niż ręczne sklejanie JSON, szczególnie gdy imię lub treść zawierają cudzysłów.

{
  "to": "+48600100200",
  "text": "Otrzymalismy zgloszenie 4711. Dziekujemy!",
  "reference": "formularz-4711"
}

Dodaj nagłówek Idempotency-Key, np. n8n-formularz-4711, oparty na ID zgłoszenia. Nie opieraj go wyłącznie na ID wykonania workflow: nowe wykonanie może nadal dotyczyć tego samego zgłoszenia. Pomiń from, aby użyć domyślnego nadawcy konta, lub podaj zatwierdzoną nazwę.

3. Uruchom jedną próbę i zapisz wynik

Wykonanie node wysyła prawdziwy SMS, także z kluczem testowym. Zacznij od jednego rekordu z własnym numerem. Odczytaj ID wiadomości, status i koszt z odpowiedzi API, a następnie zapisz je w rekordzie źródłowym. Nie sprawdzaj fikcyjnego pola success; użyj kodu HTTP i rzeczywistej struktury odpowiedzi.

Jeśli zapis wyniku nie powiedzie się po przyjęciu SMS, zachowaj klucz operacji i payload. Ponowne uruchomienie z nowym kluczem może wysłać drugi SMS. Pole reference służy do powiązania i wyszukiwania, nie zastępuje nagłówka idempotencji.

4. Webhook DLR: potwierdzenie doręczenia

Utwórz osobny workflow z Webhook node przyjmującym POST. Test URL i Production URL są różne; do stałej konfiguracji użyj adresu produkcyjnego i aktywuj workflow. Adres oraz sekret ustaw zgodnie z dokumentacją webhooków. Zmiana konfiguracji konta wymaga zakresu manage.

Przed aktualizacją rekordu zweryfikuj nagłówek X-Przypominamy-Signature: HMAC-SHA256 z czasu i surowego body. Jeśli workflow nie zapewnia poprawnej weryfikacji surowych bajtów, wykonaj ją w adapterze przed n8n. Zdarzenie message.delivered zawiera wiadomość w data.message. W Webhook node body jest zwykle dostępne pod $json.body; sprawdź wynik własnego node przed mapowaniem.

5. Ogranicz tempo i rozdziel błędy

Limit API wynosi 120 żądań na minutę na klienta, wspólnie dla równoległych workflow. Ustaw batching i przerwy z zapasem, zamiast zakładać, że każdy workflow ma osobny limit. Dla błędnego numeru popraw dane, dla braku salda zatrzymaj wysyłki i powiadom operatora. Po timeoutcie sprawdź historię i ponawiaj wyłącznie tę samą operację.

Przetestuj duplikat zdarzenia, pusty numer, przerwę po żądaniu oraz powtórzony webhook DLR. Jeśli wolisz dedykowane pola zamiast HTTP, zobacz opis community node n8n i sprawdź możliwość instalacji na swoim środowisku. Ten poradnik nie zawiera pliku workflow do importu.

Najczęstsze pytania