HTTPS API v2 / Wysyłanie wiadomości VOICE

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 użycia 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. Jeśli weryfikacja przejdzie pomyślnie, dane zostaną zapisane na serwerze, a abonent otrzyma dokument JSON/XML zawierający identyfikator pliku. Wysłanie pliku odbywa się w następujący sposób:

files/add

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.
type String mms lub voice Typ wgrywanego pliku.
url String np.: http://www.serwer.pl/kat/plik.jpg Adres URL pliku.
file String plik Upload pliku z dysku. Parametr "url" musi pozostać pusty. Opcja tylko dla plików MMS.

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

{
   "success": true,
   "id": "b67d70c22d"
}

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 VOICE, należy wywołać poniższe zapytanie:

files/index

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

{
   "items":[{
      "id":"c386a0d459",
      "name":"plik1.wav",
      "size":32184,
      "type":"voice",
      "date":"2014-10-06 15:20:37"
   },
   {
      "id":"41cdaf1e99",
      "name":"plik2.wav",
      "size":46126,
      "type":"voice",
      "date":"2014-10-06 15:18:37"
   },
   {
      "id":"4941a4cabd",
      "name":"plik3.wav",
      "size":52144,
      "type":"voice",
      "date":"2014-10-06 15:00:34"
   }]
}

Wysyłka Voice

Aby przy pomocy Zdalnej obsługi wysłać wiadomość VOICE należy wywołać określony adres URL metodą POST:

messages/send_voice

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|Array +48500600700 Numer lub numery telefonów zamieszone w tablicy.
file_id String Identyfikator pliku Identyfikator pliku można pobrać poprzez wcześniejsze wgranie i wylistowanie dostępnych plików dla usługi VOICE.
text String Treść wiadomości Parametr opcjonalny, pozwalający na wysyłkę wiadomości tekstowej przetworzonej przez syntezator mowy. W celu wysyłki tekstu jako wiadomość głosową parametr file_id należy pozostawić pusty.
lector String Maja, Jacek, Ewa, Jan lub pusta wartość (domyślny lektor Maja) Dotyczy wiadomości głosowej z treścią w formie tekstu odczytywanego przez syntezator. Domyślny lektor to Maja.
details Boolean true, false lub brak Parametr wyświetlający w odpowiedzi zwrotnej szczegóły wysłanych wiadomości.
sender_number String +48500600700 Opcjonalnie numer z którego nawiązane zostanie połączenie. Można korzystać z numerów NDI, numerów predefiniowanych oraz dodawać własne numery (z poziomu Panelu Klienta). Domyślnie w przypadku braku parametru połączenie nawiązywane jest z numeru zastrzeżonego.
repeat 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.
test Boolean true, false lub brak Parametr opcjonalny, pozwalający na sprawdzenie zapytania wysyłającego wiadomość. W odpowiedzi generowany jest dokument JSON/XML identyczny jak w przypadku standardowego zapytania jednak wiadomość nie jest wysyłana. Przydatne do testowania aplikacji.
dlr_url String

http://www.twojadres.pl/skrypt.php?smsid=#SMSID#&stan=#STAN#&data=#DATA# 

Parametr pozwala na przekazywanie metodą Push raportów doręczenia na URL Klienta. Ustawienie tej opcji w zapytaniu API nadpisuje ew. ustawienia w Panelu Klienta. Adres powinien być przekazany w formie zakodowanej przez urlencode(). Adres do przekazania raportów obowiązuje dla wszystkich wiadomości przekazanych do realizacji w ramach jednego zapytania.

Dostępne parametry:

#SMSID# - identyfikator wiadomości
#STAN# - stan doręczenia
#DATA# - data zmiany statusu
#PRZYCZYNA# - ew. przyczyna niedorę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.

{
   "success":true,
   "queued":2,
   "unsent":2,
   "items":[{
      "id":"32039da8e9",
      "phone":"+48500600700",
      "status":"queued",
      "queued":"2014-10-20 12:32:52",
      "parts":1,
      "text":"WAV"
   },
   {
      "id":"844c2b4af0",
      "phone":"+48500600500",
      "status":"queued",
      "queued":"2014-10-20 12:32:52",
      "parts":1,
      "text":"WAV"
   },
   {
      "id":"6e373d7856",
      "phone":"45616",
      "status":"unsent",
      "queued":"2014-10-20 12:32:52",
      "error_code":3103,
      "error_message":"Błędny numer odbiorcy",
      "text":"WAV"
   },
   {
      "id":"bf069fe2c1",
      "phone":"7799123",
      "status":"unsent",
      "queued":"2014-10-20 12:32:52",
      "error_code":3103,
      "error_message":"Błędny numer odbiorcy",
      "text":"WAV"
   }]
}

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 plik, optymalne jest jednorazowe jego wgranie a następnie posługiwanie się jego identyfikatorem przy kolejnych wysyłkach wiadomości.