Wiadomości

Wyślij SMS (jeden lub wielu odbiorców)

Wysyła SMS do jednego numeru (to jako string) lub do wielu (to jako tablica do 500 numerów, duplikaty usuwane). Koszt = liczba odbiorców × liczba części × cena za część. Saldo jest sprawdzane przed wysyłką. Wymaga zakresu send.

Numery przyjmujemy w formacie E.164 (+48600100200), bez plusa (48600100200) lub jako 9 cyfr (traktowane jako polskie).

Grupy i personalizacja: to może być "group:<id lub nazwa grupy>" albo tablicą mieszającą numery i grupy (łącznie do 500 odbiorców po rozwinięciu; pusta lub nieznana grupa = 400/404). Gdy w to jest grupa, placeholdery {{imie}}, {{nazwisko}}, {{email}} i {{<pole_własne>}} w text są podstawiane z kontaktów per odbiorca (także dla numerów podanych wprost, jeśli są w książce); brakująca wartość = pusty ciąg. Zwrócone wiadomości mają spersonalizowany text.

Opt-out: {{opt_out}} (alias {{wypisz}}) w treści zamienia się w osobisty link wypisu api.przypominamy.com/o/<token>. Odbiorcy z czarnej listy dostają status rejected, koszt 0 i nie są liczeni w accepted.

Godziny i ważność: send_window przesuwa wysyłkę spoza okna na najbliższy jego początek (status scheduled), expires_at ogranicza czas prób doręczenia. Te same opcje działają w POST /v1/mms i POST /v1/voice.

Szablony: zamiast text podaj template_id (szablon typu sms z GET /v1/templates) i params z wartościami {{klucz}}; pozostałe placeholdery są podstawiane z kontaktów albo pustym ciągiem. Ten sam mechanizm działa w POST /v1/mms (szablon mms) i POST /v1/voice (szablon vms).

Priorytet: priority: true kieruje SMS do osobnej, szybkiej kolejki u operatora (kody OTP, alerty) - cena za część × 2. Tylko SMS.

Śledzone linki: {{link:https://…}} w treści (do 2 różnych adresów) zamienia się per odbiorca w krótki link api.przypominamy.com/l/<token> z licznikiem kliknięć; zwrócony text ma już podstawiony link, GET /v1/messages/{id} zwraca links[], a przy pierwszym kliknięciu przychodzi webhook link.clicked. Bez dopłaty. {{opt_out}}, linki i pola z kontaktów dzielą wspólny budżet 4 placeholderów na wiadomość.

post/v1/messages

Request

  • Base URL: https://api.przypominamy.com
  • URL: https://api.przypominamy.com/v1/messages
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Rezerwuje operację przed wysyłką. Ten sam klucz i treść odtwarzają zakończony wynik przez 24 h. Inna treść lub operacja w toku/nierozstrzygnięta: 409 idempotency_conflict. Nie ponawiaj z nowym kluczem po timeoutcie. Nierozstrzygnięte operacje wymagają uzgodnienia statusu i nie wygasają automatycznie.

Request body

textstring

Treść. Polskie znaki dozwolone (UCS-2, 70/67 znaków na część). Placeholdery: {{imie}}, {{nazwisko}}, {{email}}, {{<pole_własne>}} (z kontaktów - dla grup i dla numerów, które są w książce) i {{opt_out}} / {{wypisz}} (osobisty link wypisu) oraz {{link:https://…}} (śledzony krótki link per odbiorca, do 2 różnych adresów). Wymagane, chyba że podajesz template_id.

template_idstring

Id szablonu (tpl_…, z GET /v1/templates) zamiast text. Szablon musi być typu sms (w POST /v1/mms - mms, w POST /v1/voice - vms), inaczej 400 z param: "template_id"; nieznany → 404. Placeholdery {{klucz}} podstawiane z params, pozostałe z kontaktów albo pustym ciągiem.

paramsobject

Wartości placeholderów szablonu, np. { "kiedy": "jutro 10:00" } → {{kiedy}}. Klucze bez rozróżniania wielkości liter. Tylko z template_id.

fromstring

Nadpis (nazwa nadawcy). Musi być aktywny na liście GET /v1/senders. Domyślnie nadpis konta.

send_atstring date-time

Zaplanowana wysyłka (ISO 8601), do 90 dni w przód. Daty w przeszłości = wysyłka natychmiast.

send_windowstring

Okno godzin wysyłki w czasie polskim (HH:MM-HH:MM, min. 15 minut, koniec wyłączny). Wysyłka spoza okna (teraz albo send_at) jest przesuwana na najbliższy początek okna i dostaje status scheduled. Pominięte = domyślne okno konta z PATCH /v1/account.

expires_atstring date-time

Ważność: po tym czasie dostawca przestaje próbować doręczyć (status expired). Od 15 minut do 72 godzin po czasie wysyłki.

referencestring

Twój identyfikator (np. id wizyty). Wraca w odpowiedzi, webhookach i jako filtr w GET /v1/messages.

priorityboolean

SMS priorytetowy: osobna, szybka kolejka u operatora (kody OTP, alerty). Cena za część × 2. Tylko SMS - w POST /v1/mms i POST /v1/voice ignorowane. Wartość inna niż true/false → 400.

Example request

{
  "text": "Przypominamy o wizycie jutro o 10:00.",
  "template_id": "tpl_Q3m7kL2pXa9dRt",
  "params": {
    "kiedy": "jutro 10:00",
    "lekarz": "dr Nowak"
  },
  "from": "ZDROWKO",
  "send_at": "2026-09-08T08:00:00Z",
  "send_window": "08:00-20:00",
  "expires_at": "2026-09-08T20:00:00+02:00",
  "reference": "wizyta-4711"
}

Response

Wiadomość przyjęta. Dla to jako string zwracany jest pojedynczy obiekt Message; dla tablicy - obiekt zbiorczy.

OR

Example response

{
  "id": "msg_qY08hZ2mmDXAazdRTytS",
  "to": "+48600100200",
  "from": "ZDROWKO",
  "parts": 1,
  "cost_grosze": 9
}

Changes

No recorded changes to this operation across all 1 revision of this API.