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