HTTPS API v2 / Obsługa wiadomości Premium SMS
Zasada działania
Przy użyciu HTTPS API można obsługiwać również ruch Premium SMS, tworząc np. własne schematy konkursów, loterii czy czaty SMS (np. w przypadku gdy funkcjonalność Panelu Klienta nie jest wystarczająca dla Abonenta). Komunikacja Premium SMS przy użyciu HTTPS API polega na odebraniu zapytania z nową wiadomością lub ewentualne wylistowanie dostępnych wiadomości Premium oraz przesłanie zapytania dotyczącego wysyłki odpowiedzi.
URL przesyłający informację o nowej wiadomości Premium
W Panelu Klienta można ustawić adres URL z odpowiednimi parametrami, na jaki wysyłane mają być informacje dotyczące nowych wiadomości Premium. Ustawienia te można zaktualizować w Panelu Klienta → Premium SMS → Prefixy i numery → Edycja wybranego hasła (lub stworzenie nowego) → Treść odpowiedzi → HTTPS XML API.
Przykładowy URL może mieć postać:
https://www.adres.pl/skrypt.php?z_numeru=#NUMEROD#&wiadomosc=#WIADOMOSC#&na_numer=#NUMERDO#&data=#DATA#&idsms=#IDSMS#&limit=#LIMIT#
Opis parametrów:
| Parametr | Przykładowa wartość lub format | Opis |
|---|---|---|
| #NUMEROD# | 48500600700 | Numer 9-cio cyfrowy z jakiego przyszła wiadomość Premium. |
| #WIADOMOSC# | test | Treść wiadomości. |
| #NUMERDO# | 71200 | Numer Premium na jaki została wysłana wiadomość. |
| #DATA# | „2011-09-26 12:23:56” | Data w formacie YYY-MM-DD HH:ii:ss. |
| #IDSMS# | 1234 | Identyfikator numeryczny wiadomości. |
| #LIMIT# | 2 | Liczba przysługujących odpowiedzi dla wybranej wiadomości. |
Poprawna odpowiedź na zapytanie powinna być zwrócona jako plain/text i zawierać jedynie „OK”.
Listowanie wiadomości Premium
Jeśli z jakiegoś powodu odbiór wiadomości się nie powiedzie, lub klient preferuje ręczne pobieranie listy dostępnych wiadomości w ramach Premium API, istnieje możliwość przesłania zapytania do systemu, które zwróci listę wiadomości oczekujących na odpowiedź.
premium/index
W rezultacie zostanie wygenerowany dokument JSON np. taki jak poniższy:
{
"items":[{
"id":120270659,
"to_number":"71160",
"from_number":"48500600700",
"date":"2013-05-10 15:29:05",
"limit":1,
"text":"INT.test"
},
{
"id":120269997,
"to_number":"71160",
"from_number":"48500600500",
"date":"2013-05-10 15:17:27",
"limit":1,
"text":"PAS.premium"
}]
}
Wysyłanie odpowiedzi Premium
premium/send
Aby wysłać odpowiedź na określoną wiadomość Premium należy użyć jej identyfikatora otrzymanego wraz z wiadomością.
Dostępne parametry
| Parametr | Typ | Przykładowa wartość lub format | Opis |
|---|---|---|---|
| username | String | login | Login użytkownika API. |
| password | String | hasło | Hasło użytkownika API. |
| phone | String | np.: +48500600700 | Numer telefonu. |
| id | Integer | np.: 123456789 | Identyfikator wiadomości, na którą wysyłana jest odpowiedź. |
| gate | Integer | np.: 71160 | Numer bramki Premium. |
| text | String | treść | Treść wiadomości. |
Parametry oznaczone pogrubieniem są obowiązkowe. Pozostałe są opcjonalne.
W rezultacie zostanie wygenerowany dokument JSON np. taki jak poniższy:
{
"success":true
}
Listowanie statystyk dla usługi Quiz Premium
quiz/view
Aby wyświetlić statystyki należy podać identyfikator quizu.
Dostępne parametry
| Parametr | Typ | Przykładowa wartość lub format | Opis |
|---|---|---|---|
| username | String | login | Login użytkownika API. |
| password | String | hasło | Hasło użytkownika API. |
| id | Integer | np.: 123 | Identyfikator quizu. |
Parametry oznaczone pogrubieniem są obowiązkowe. Pozostałe są opcjonalne.
W rezultacie zostanie wygenerowany dokument JSON np. taki jak poniższy:
{
"id":123,
"name":"jakaś nazwa quizu",
"items":[{
"id":1,
"count":8,
},
{
"id":2,
"count":10,
}]
}
Tabela dostępnych ilości odpowiedzi w zależności od numeru Premium
Dla każdej wiadomości przychodzącej w ramach numeru Premium, przysługuje pula wiadomości wychodzących (również przez kanał Premium), z użyciem tego samego numeru na jaki SMS został pierwotnie wysłany. Poniższa tabela ilustruje ilości dostępnych odpowiedzi w ramach 1 wiadomości przychodzącej uzależnionej od taryfy numeru Premium.
| Stawka | Przykładowy numer | Ilość odpowiedzi |
|---|---|---|
| 0,50 zł | 70906 | 1 |
| 1,00 zł | 7100 | 2 |
| 2,00 zł | 7200 | 4 |
| 3,00 zł | 7300 | 6 |
| 4,00 zł | 7400 | 8 |
| 5,00 zł | 7500 | 10 |
| 6,00 zł | 7600 | 12 |
| 9,00 zł | 7900 | 18 |
| 19,00 zł | 91900 | 38 |
| 25,00 zł | 92500 | 38 |
Zalecane ustawienia
Aby obsługiwać usługę Premium SMS przez API, należy w ustawieniach haseł Premium zaznaczyć opcję odpowiedzi na API. Dodatkowo, w celu informacyjnym, warto zaznaczyć opcję przesyłania dalej wiadomości na adres URL, w ten sposób Klient może być informowany o nowej wiadomości przychodzącej bez konieczności cyklicznego odpytywania API SerwerSMS.pl o nowe wiadomości.