HTTPS API v2 / Wysyłanie wiadomości WhatsApp
Wywołanie adresu
Aby przy pomocy Zdalnej obsługi wysłać wiadomość WhatsApp należy przesłać określone zgłoszenie protokołem HTTP lub HTTPS metodą POST.
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. |
| phone | String|Array | +48500600700 | Numer lub tablica numerów telefonów. |
| sender | String | Nazwa nadawcy, która wcześniej musi zostać zgłoszona i zaakceptowana | Każda nazwa nadawcy musi zostać najpierw dodana w naszym Panelu, a następnie zatwierdzona przez administratora SerwerSMS.pl |
| text* | String | tresc | Treść wiadomości |
| template* | String | szablon_kyrt | Parametr określający identyfikator szablonu, który podmieni treść wysyłanej wiadomości. Listę szablonów WhatsApp można pobrać korzystając z akcji templates/whatsapp. Każdy szablon musi zostać najpierw zgłoszony w naszym Panelu i zaakceptowany przez administratora. |
| params* | Array | array(1 => 'Pierwszy parametr') | Tablica parametrów, które podmienią treść w odpowienim miejscu szablonu. |
| 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 wiadomości. |
| 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 pogrubieniem są obowiązkowe. Pozostałe są opcjonalne.
* Wymagane jest podanie parametru zamiennie, tzn. należy przekazać 'text' lub 'template' wraz z tablicą 'params'.
Zwrot odpowiedzi
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":"2014-10-16 16:49:05",
"text":"Test SerwerSMS.pl"
}]
}
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":3104,
"type":"WhatsappError",
"message":"Brak uprawnień do wysyłki 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-200 numerów w jednym zapytaniu. Przyspieszy to znacznie proces przekazywania danych do SerwerSMS.pl i zmniejszy ilość koniecznych do wysłania zapytań.