HTTPS XML API / Wysyłanie wiadomości VOICE (Pliki WAV)

Zasada działania

Aby wysłać wiadomość głosową używając pliku WAV, należy wcześniej wczytać plik multimedialny korzystając z opcji wgrywania plików. Dopiero po wgraniu niezbędnych plików (plików WAV o określonych parametrach) możliwe jest wysłanie wiadomości VOICE gdzie abonent określa identyfikator pliku do wysyłki. Plik musi mieć ściśle określone parametry, tj. format WAV, parametry 16 Bit, 8 KHz, 128 kbit/sek, mono - 1 kanał, max 60 sekund). W przeciwnym wypadku plik nie zostanie zapisany w systemie i nie będzie możliwości aby użyć go przy wysyłce.

Wgrywanie pliku

Zapisanie pliku na serwerze polega na przesłaniu adresu URL pliku wraz z odpowiednimi parametrami. System sprawdzi, czy plik istnieje i czy spełnia wymagania, i jeśli weryfikacja przejdzie pomyślnie, dan zostaną zapisane na serwerze a abonent otrzyma dokument XML zawierający identyfikator pliku oraz inne informacje. Wysłanie pliku odbywa się w następujący sposób:

https://api1.serwersms.pl/zdalnie/index.php?login=demo&haslo=demo&akcja=pliki&url_voice=http%3A%2F%2Fwww.serwer.pl%2Fkat%2Fplik.wav

W rezultacie zostanie wygenerowany dokument XML np. taki jak poniższy:

<?xml version="1.0" encoding="UTF-8"?>
<SerwerSMS login="demo">
 <Plik id="734857">
  <Nazwa>plik.WAV</Nazwa>
  <Rozmiar>34325</Rozmiar>
  <Typ>VOICE</Typ>
  <Data>2011-04-01 12:20:30</Data>
 </Plik>
</SerwerSMS>

W przypadku wystąpienia błędu, XML będzie wyglądał np. tak jak poniższy:

<?xml version="1.0" encoding="UTF-8"?>
<SerwerSMS login="demo">
 <Blad>komunikat bledu</Blad>
</SerwerSMS>

Listowanie plików

Aby wylistować wgrane na serwer pliki i pobrać ich identyfikatory, które następnie będzie można użyć w wysyłce MMS, należy wywołać poniższe zapytanie:

https://api1.serwersms.pl/zdalnie/index.php?login=demo&haslo=demo&akcja=pliki&lista=voice

W rezultacie zostanie wygenerowany dokument XML np. taki jak poniższy:

<?xml version="1.0" encoding="UTF-8"?>
<SerwerSMS login="demo">
 <Plik id="734857">
  <Nazwa>plik.wav</Nazwa>
  <Rozmiar>34325</Rozmiar>
  <Typ>VOICE</Typ>
  <Data>2011-04-01 12:20:30</Data>
 </Plik>
 <Plik id="734858">
  <Nazwa>plik1.wav</Nazwa>
  <Rozmiar>34545</Rozmiar>
  <Typ>VOICE</Typ>
  <Data>2011-04-01 12:20:31</Data>
 </Plik>
 <Plik id="734859">
  <Nazwa>plik2.wav</Nazwa>
  <Rozmiar>5463423</Rozmiar>
  <Typ>VOICE</Typ>
  <Data>2011-04-01 12:20:32</Data>
 </Plik>
</SerwerSMS>

Wysyłka Voice

Aby przy pomocy Zdalnej obsługi wysłać wiadomość Voice należy wywołać określony adres URL metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco:

https://api1.serwersms.pl/zdalnie/index.php?login=demo&haslo=demo&akcja=wyslij_sms&glosowy=1&plikwav=231243&numer=%2B48500600700

Wywołanie powyższego adresu (w przypadku podania prawidłowych danych do zalogowania) spowodowałoby wysłanie wiadomości Voice w postaci pliku WAV o identyfikatorze 231243  na numer 500600700.

Dostępne parametry

Parametr Typ Przykładowa wartość lub format Opis
akcja String wyslij_sms Aby wysłać wiadomość SMS należy umieścić tutaj wartość „wyslij_sms”.
login String login Login konta używany do wysyłki
haslo String hasło Hasło do konta
glosowy Integer 1 Ustawienie parametru jako 1 umożliwi wysyłkę VOICE.
numer String +48500600700 Numer lub numery telefonów oddzielane przecinkami.
plikwav String Identyfikator pliku Identyfikator pliku można pobrać poprzez wcześniejsze wgranie i wylistowanie dostępnych plików dla usługi VOICE.
test Integer 1, 0 lub brak Parametr opcjonalny, pozwalający na sprawdzenie zapytania wysyłającego wiadomość. W odpowiedzi generowany jest dokument XML identyczny jak w przypadku standardowego zapytania jednak wiadomość nie jest wysyłana. Przydatne do testowania aplikacji.
numer_nadawcy String +48500600700 Opcjonalnie numer z którego nawiązane zostanie połączenie. Można korzystać z numerów NDI, numerów predefiniowanych oraz dodwać własne numery (z poziomu Panelu Klienta). Domyślnie w przypadku braku parametru połączenie nawiązywane jest z numeru zastrzeżonego.
powtorz Integer 0-10 Ponowne odtworzenie komunikatu. Wartości od 0 do 9 oznaczają odtworzenie po wybraniu klawisza na klawiaturze telefonu o danym numerze. Wartość 10 oznacza odtworzenie komunikatu automatycznie po 2 sekundach od zakończenia wiadomości.

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

Zwrot wygenerowany po przesłaniu jest taki sam jak w przypadku zwykłego wysłania wiadomości SMS.

<?xml version="1.0" encoding="UTF-8"?>
<SerwerSMS login="demo">
 <Wiadomosc>WAV</Wiadomosc>
 <Odbiorcy>
  <Skolejkowane>
   <SMS id="e1389bc4f6" numer="+48500600700" godzina_skolejkowania="2011-07-10 12:42:45"/>
   <SMS id="3ko9iuytdf" numer="+48500600500" godzina_skolejkowania="2011-07-10 12:42:45"/>
  </Skolejkowane>
  <Niewyslane>
   <SMS id="dedb71cd72" numer="6043440" przyczyna="bledny numer odbiorcy"/>
   <SMS id="765dk6109s" numer="+420777099123" przyczyna="niedozwolone wysyłanie SMSow do sieci zagranicznych"/>
  </Niewyslane>
 </Odbiorcy>
</SerwerSMS>

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ń.

Jeśli wysyłany jest ten sam załącznik, optymalne jest jednorazowe jego wgranie a następnie posługiwanie się jego identyfikatorem przy kolejnych wysyłkach wiadomości.