HTTPS API v2 / Wysyłanie wiadomości WhatsApp

Wywołanie adresu

Aby wysłać wiadomość WhatsApp za pośrednictwem Zdalnej obsługi, należy przesłać żądanie HTTP POST z treścią BODY w formacie JSON.

messages/send_whatsapp

Dostępne parametry

Parametr Typ Przykładowa wartość lub format Opis
username String login Login użytkownika API.
password String haslo Hasło użytkownika API.
whatsapp_id String Identyfikator agenta WhatsApp np. 54c53be2-cbb8-11ec-9d64-0242ac120002 Identyfikator dostepny jest w naszym panelu, przypisany dla każdej stworzonej konfiguracji agenta WhatsApp.
phone String|Array +48500600700 Numer lub tablica numerów telefonów.
message Object {} Struktura wiadomości WhatsApp w postaci obiektu JSON.
details Boolean true, false lub brak Parametr wyświetlający w odpowiedzi zwrotnej szczegóły wysłanych wiadomości.
date DateTime ISO np.
„2015-02-22 12:25:55”		 Parametr opcjonalny, pozwalający na określenie terminu wysyłki dla wiadomości typu TEMPLATE.
unique_id String|Array np. 6asTD3fif98gj Parametr opcjonalny, pozwalający na zdefiniowanie własnego identyfikatora wysyłanej wiadomości. Identyfikator może mieć minimalnie 3 znaki i maksymalnie 50 znaków alfanumerycznych (a-z, A-Z, 0-9). Dla grupowych wysyłek, kolejne unique_id muszą być unikalne oraz ilość unique_id musi być zgodna z ilością numerów.
group_id String|Array np. 123456789

Identyfikator lub identyfikatory grup w Panelu Klienta. Identyfikatory te można pobrać korzystając z akcji groups/index lub kopiując je z poziomu edycji grupy w Panelu Klienta.

Parametry oznaczone jako wymagane muszą zostać przekazane w każdym żądaniu. Pozostałe parametry są opcjonalne i umożliwiają m.in. określenie typu wiadomości, zaplanowanie wysyłki itp.

Typy wiadomości

API umożliwia wysyłanie wiadomości WhatsApp w dwóch trybach: Standard oraz Template. Wybór odpowiedniego trybu zależy od tego, czy z odbiorcą prowadzona jest aktywna konwersacja.

1. Standard TEXT - wiadomość tekstowa

Przykładowa struktura JSON:

{
   "standard_text": {
        "body":"Przykładowa treść wiadomości",
        "link_preview":true
   }
}

Obiekt standard_text służy do wysyłki prostej wiadomości tekstowej:

Parametr Typ Wymagany Opis
body String Tak Treść wiadomości tekstowej wysyłanej do odbiorcy.  Maksymalnie 4096 znaków. Adresy URL są automatycznie zamieniane na hiperłącza.
link_preview Boolean Nie Określa, czy WhatsApp ma generować podgląd linków zawartych w wiadomości (np. tytuł strony, opis, miniatura). Dostępne opcje true | false.

Wiadomość standard_text to najprostszy typ wiadomości WhatsApp, który nie wymaga użycia szablonów zatwierdzonych przez Meta.

Jeśli w treści znajdują się linki, parametr link_preview kontroluje ich podgląd w aplikacji WhatsApp.

2. Standard BUTTON - wiadomość z przyciskami odpowiedzi (REPLY BUTTON)

Przykładowa struktura JSON:

{
   "standard_button": {
        "header":{
             "image":"https://sciezka_do_pliku"
        },
        "body":"Przykładowa treść wiadomości",
        "footer":"Przykładowa treść stopki",
        "buttons":{
             "1":{
                  "text":"Opis buttona",
                  "template":"btn-1",
                  "type":"reply"
             },
             "2":{
                  "text":"Opis buttona",
                  "template":"btn-2",
                  "type":"reply"
             }
        }
   }
}

Obiekt standard_button definiuje standardową wiadomość WhatsApp z nagłówkiem, treścią, stopką oraz interaktywnymi przyciskami:

Parametr Typ Wymagany Opis
header Object Nie Nagłówek wiadomości. Może zawierać obraz wyświetlany nad treścią wiadomości.
header.image String Nie Publiczny adres URL obrazu wyświetlanego w nagłówku wiadomości. Obsługiwany format to JPEG, PNG, rozmiar do 5MB.
body String Tak Główna treść wiadomości wyświetlana odbiorcy.  Maksymalnie 1024 znaków. Adresy URL są automatycznie zamieniane na hiperłącza.
footer String Nie Tekst wyświetlany w stopce wiadomości.  Maksymalnie 60 znaków.
buttons Object Tak Lista interaktywnych przycisków wyświetlanych pod wiadomością (maksymalnie 3 elementy).

Parametry obiektu buttons:

Parametr Typ Wymagany Opis
text String Tak Tekst wyświetlany na przycisku.  Maksymalnie 20 znaków.
template String Tak Element może zostać wykorzystany do identyfikacji wybranej odpowiedzi. Zostaje przekazywany w powiadomieniu Webhook pod kluczem data po kliknięciu przycisku. Maksymalna długość 200 znaków.
type String Tak Typ przycisku. Aktualnie obsługiwana wartość to reply.

3. Standard CTA - wiadomość z przyciskiem przekierowania (CTA URL)

Przykładowa struktura JSON:

{
   "standard_cta": {
        "header":{
             "image":"https://sciezka_do_pliku"
        },
        "body":"Przykładowa treść wiadomości",
        "footer":"Przykładowa treść stopki",
        "buttons":{
             "1":{
                  "text":"Opis buttona",
                  "url":"https://serwersms.pl",
                  "type":"url"
             }
        }
   }
}

Obiekt standard_cta definiuje standardową wiadomość WhatsApp z nagłówkiem, treścią, stopką oraz interaktywnym przekierowaniem URL:

Parametr Typ Wymagany Opis
header Object Nie Nagłówek wiadomości. Może zawierać obraz wyświetlany nad treścią wiadomości.
header.image String Nie Publiczny adres URL obrazu wyświetlanego w nagłówku wiadomości. Obsługiwany format to JPEG. PNG, rozmiar do 5MB.
body String Tak Główna treść wiadomości wyświetlana odbiorcy.  Maksymalnie 1024 znaków. Adresy URL są automatycznie zamieniane na hiperłącza.
footer String Nie Tekst wyświetlany w stopce wiadomości.  Maksymalnie 60 znaków.
buttons Object Tak Interaktywny przycisk wyświetlany pod wiadomością (tylko jeden element).

Parametry obiektu buttons:

Parametr Typ Wymagany Opis
text String Tak Tekst wyświetlany na przycisku.  Maksymalnie 20 znaków.
url String Tak Adres URL służacy do przekierowania.
type String Tak Typ przycisku. Aktualnie obsługiwana wartość to url.

4. Template MARKETING INDIVIDUAL - wiadomość szablonowa marketingowa z przyciskami (URL, CALL, REPLY)

Przykładowa struktura JSON:

{
   "template_marketing_individual": {
        "header":{
             "image":"https://sciezka_do_pliku"
        },
        "name":"serwersmspl_indywidualny_1",
        "params":{
             "body":{
                  "+48500600700":{
                       "#IMIE#":"Jan",
                       "#NAZWISKO#":"Kowalski"
                  }
             }
        }
   }
}

Obiekt template definiuje wiadomość szablonową WhatsApp, należący do jednej z trzech kategorii: Marketing, Utility lub Authentication.

Parametr Typ Wymagany Opis
header.image String Nie Publiczny adres URL obrazu wyświetlanego w nagłówku wiadomości.
name String Tak Nazwa idetyfikująca szablon.
params Object Nie Lista parametrów służąca do personalizacji treści.

Obiekt params umożliwia przekazanie indywidualnych wartości zmiennych dla każdego odbiorcy wiadomości. Kluczem obiektu 'body' jest numer telefonu odbiorcy, natomiast jego wartością jest lista parametrów wykorzystywanych podczas personalizacji treści wiadomości:

Parametr Typ Wymagany Opis
body Object Nie Lista parametrów przypisanych do poszczególnych odbiorców.
body.{phone} Object Tak* Obiekt zawierający wartości parametrów dla wskazanego numeru telefonu. Kluczem jest numer odbiorcy w formacie międzynarodowym (E.164).
body.{phone}.{parameter} String Tak* Wartość parametru wykorzystywana podczas personalizacji wiadomości, np. #IMIE#, #NAZWISKO#.

* - tylko dla spersonalizowanego szablonu

Obsługiwane typy plików

Typ obrazu Rozszerzenie Typ MIME Maksymalny rozmiar
JPEG .jpg / .jpeg image/jpeg 5 MB
PNG .png image/png 5 MB

Zwrotna odpowiedź API

W zależności od przesłanych danych SerwerSMS.pl wygeneruje w odpowiedzi dokument w formacie JSON/XML z informacją na temat wykonanych akcji. I tak w przypadku prawidłowego wysłania wiadomości SMS klient otrzyma przykładowo następują informację:

{
   "success":true,
   "queued":1,
   "unsent":0
}

W przypadku podania dodatkowego parametru details=true, odpowiedź zwrotna zostanie uzupełniona o szczegóły wysyłanych wiadomości, które można zapisać w bazie danych po stronie oprogramowania klienta:

{
   "success":true,
   "queued":1,
   "unsent":0,
   "items":[{
        "id":"1c142d81c7",
        "phone":"+48500600700",
        "status":"queued",
        "queued":"2026-06-30 16:49:05",
        "stat_id":3253
   }]
}

Parametr "success" zawiera informację o powodzeniu przeprowadzonej operacji. W atrybutach "queued" oraz "unset" znajdują się liczby skolejkowanych oraz niewysłanych wiadomości. Sekcja "items" zawiera numery telefonów i ID wiadomości przekazanych do wysłania (oraz wiadomości, których nie skolejkowano z określonego powodu). Unikalny znacznik wiadomości SMS może być wykorzystany później do sprawdzenia w sposób zdalny stanu wysyłki konkretnej wiadomości SMS. W parametrze "text" widnieje treść wysyłanej wiadomości SMS. Numer telefonu jest automatycznie poprawiany i wyświetlany w pełnym formacie wymaganym przez SerwerSMS.pl czyli z numerem kierunkowym kraju (np. +48) na początku.

Oprócz tego może zostać wygenerowany błąd ogólny gdzie nie ma rozgraniczenia na skolejkowane i błędne. Może to nastąpić np. w sytuacji gdy klient nie zdefiniuje treści wiadomości, nie poda numerów telefonów, jego konto nie jest aktywne lub wystąpił inny problem opisany w komunikatach błędów. W przypadku braku odpowiedniego uprawnienia zostanie wygenerowany następujący komunikat:

{
   "error":{
      "code":6200,
      "type":"WhatsAppError",
      "message":"Brak uprawnień do wysyłki wiadomości"
   }
}

Komunikaty błędów

Kod błędu Opis
6200 Brak uprawnień do wysyłki wiadomości
6201 Identyfikator agenta jest nieprawidłowy lub agent jest nieaktywny
6202 Brak przekazanej wiadomości lub jej struktura jest nieprawidłowa
6203 Nieprawidłowy szablon wiadomości
6204 Numery muszą posiadać parametry ustalone w szablonie
6205 Wiadomość musi zawierać nagłówek header, ponieważ szablon został w takiej formie zdefiniowany
6206 Nieprawidłowy typ szablonu dla wskazanej struktury wiadomości

Zalecane ustawienia

W przypadku średnich i dużych ilości wysyłanych wiadomości rzędu kilku tysięcy lub więcej, zalecane jest przekazywanie wiadomości w „paczkach” po ok 50 numerów w jednym zapytaniu. Przyspieszy to znacznie proces przekazywania danych do SerwerSMS.pl i zmniejszy ilość koniecznych do wysłania zapytań.

Listowanie szablonów

System umożliwia zdalne listowanie szablonów WhatsApp. Aby przy pomocy zdalnej obsługi wylistować szablony, należy wywołać określony adres URL metodą POST.

templates/whatsapp

Dostępne parametry

Parametr Typ Wymagany Przykładowa wartość lub format Opis
username String Tak Login Login użytkownika API.
password String Tak Haslo Hasło użytkownika API.
whatsapp_id String Nie 54c53be2-cbb8-11ec-9d64-0242ac120002 Parametr opcjonalny umożliwiający filtrowanie szablonów tylko dla wybranego agenta WhatsApp.
sort String Nie name Parametr opcjonalny umożliwiający sortowanie danych według nazwy szablonu.
order String Nie asc|desc Parametr opcjonalny umożliwiający zmianę kolejności sortowania.

Parametry oznaczone pogrubieniem są obowiązkowe. Pozostałe są opcjonalne.

Zwrot odpowiedzi

{
   "items":[{
         "whatsapp_id":"54c53be2-cbb8-11ec-9d64-0242ac120002",
         "name":"Nazwa szablonu",
         "category":"marketing",
         "language":"pl",
         "template":"serwersms_indywidualny_1",
         "params":{
              "#IMIE#":"Jan"
         },
         "quality":"green",
         "status":"active",
         "created":"2026-06-30 09:00:00"
      },
      {
         "whatsapp_id":"54c53be2-cbb8-11ec-9d64-0242ac120002",
         "name":"Nazwa szablonu",
         "category":"standard",
         "template":{
              "standard_cta":{
                   "body":"Treść wiadomości",
                   "buttons":{
                        "1":{
                             "text":"Kliknij",
                             "url":"http://serwersms.pl",
                             "type":"url"
                        }
                    }
              }
         },
         "created":"2026-06-30 09:00:00"
      }
   ]
}

Parametr Typ Opis Przykład
whatsapp_id String Identyfikator agenta WhatsApp w formie UUID. 54c53be2-cbb8-11ec-9d64-0242ac120002
name String Nazwa szablonu wyświetlana użytkownikowi. Nazwa szablonu
category String Kategoria szablonu (marketing, standard, utility, authentication). marketing
language String Kod języka szablonu. pl
template String

Techniczna nazwa (identyfikator) szablonu w WhatsApp, używana do wysyłki

 serwersms_indywidualny_1
structure Object

Struktura obiektu szablonu w formie JSON.

 {}
params Object Obiekt w formie JSON zawierający parametry spersonalizowane szablonu. Pole występuje tylko dla szablonów posiadających odpowiednie tagi zmiennych. {"#IMIE#":"Jan"}
quality String Ocena jakości szablonu nadawana przez WhatsApp (green, yellow, red). green
status String Status szablonu. active
created DateTime Data i godzina utworzenia szablonu w formie ISO. 2026-06-30 09:00:00