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żywany do wysyłki.
password String hasło Hasło do konta.
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żywany do wysyłki.
password String hasło Hasło do konta.
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.