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.