HTTPS API v2 / Wysyłanie wiadomości MMS

Zasada działania

Aby wysłać wiadomość MMS, należy wcześniej wczytać plik multimedialny korzystając z opcji wgrywania plików. Dopiero po wgraniu niezbędnych plików (np. obrazków, dźwięku lub video), możliwe jest wysłanie wiadomości MMS gdzie abonent określa identyfikator pliku do wysyłki.

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

Możliwe jest wgranie określonych typów plików:

Content-Type rozszerzenie pliku
application/vnd.ms-excel xls xlm xla xlc xlt xlw
application/msword doc dot
application/vnd.ms-powerpoint ppt pps pot
application/rtf rtf
application/x-tar tgz tar
application/zip zip
application/pdf pdf
application/smil+xml smi smil
application/ogg ogg
application/vnd.ms-cab-compressed cab
application/vnd.oasis.opendocument.formula odf
application/vnd.oasis.opendocument.chart-template otc
application/vnd.oasis.opendocument.chart odc
audio/midi mid midi kar rmi
audio/mpeg mpga mp2 mp2a mp3 m2a m3a
audio/mpeg3 mp3
audio/mp3 mp3
audio/x-mpegurl m3u
audio/wav wav
audio/x-ms-wma wma
audio/x-aiff aif aiff aifc
audio/x-pn-realaudio ram ra
image/pjpeg pjpeg
image/gif gif
image/jpeg jpeg jpg jpe
image/jpg jpeg jpg jpe
image/png png
image/svg+xml svg svgz
image/vnd.djvu djvu djv
image/vnd.wap.wbmp wbmp wbmp
image/x-icon ico
text/plain txt text conf def list log in
text/richtext rtx
text/csv csv
text/x-java-source java
text/x-vcard vcf
text/x-vcalendar vcs
video/3gpp 3gp
video/3gpp2 3g2
video/quicktime qt mov
video/x-ms-asf asf asx
video/avi avi
video/x-msvideo avi
video/x-sgi-movie movie
video/mp4 mp4 mp4v mpg4
video/mpeg mpeg mpg mpe m1v m2v

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ć akcję:

files/index

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

{
   "items":[{
      "id":"b67d70c22d",
      "name":"plik1.jpg",
      "size":174562,
      "type":"mms",
      "date":"2014-10-07 16:54:53"
   },
   {
      "id":"39b0d42508",
      "name":"plik2.jpg",
      "size":344241,
      "type":"mms",
      "date":"2014-10-07 16:54:53"
   },
   {
      "id":"aad84d6e71",
      "name":"plik3.txt",
      "size":27,
      "type":"mms",
      "date":"2014-10-07 16:50:10"
   }]
}

Wysyłka MMS

Aby przy pomocy zdalnej obsługi wysłać wiadomość MMS należy wywołać określony adres URL metodą POST.

messages/send_mms

Dostępne parametry

Parametr Typ Przykładowa wartość lub format Opis
username String login Login konta używany do wysyłki.
password String hasło Hasło do konta.
title String Tytuł wiadomości MMS Tytuł wiadomości MMS. Dostępne jest 40 znaków.
file_id String|Array Identyfikator pliku Identyfikator pliku można pobrać poprzez wcześniejsze wgranie i wylistowanie dostępnych plików dla usługi MMS. Można jednocześnie wysłać max 10 plików gdzie ich identyfikatory przesłane będą za pomocą tablicy.
phone String|Array +48500600700 Numer lub numery telefonów przekazane w tablicy.
details Boolean true, false lub brak Parametr wyświetlający w odpowiedzi zwrotnej szczegóły wysłanych wiadomości.
text String Treść Treść wiadomości MMS. Zostanie automatycznie zapisana do pliku i dołączona do wiadomości.
date DateTime ISO
np: „2010-11-09 15:23”
Parametr opcjonalny pozwalający na określenie terminu wysyłki wiadomości SMS.
test Boolean true, false lub brak Parametr opcjonalny, pozwalający na sprawdzenie zapytania wysyłającego wiadomość SMS. W odpowiedzi generowany jest dokument JSON/XML identyczny jak w przypadku standardowego zapytania jednak wiadomość nie jest wysyłana.

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":"Tytuł MMS-a"
   },
   {
      "id":"844c2b4af0",
      "phone":"+48500600500",
      "status":"queued",
      "queued":"2014-10-20 12:32:52",
      "parts":1,
      "text":"Tytuł MMS-a"
   },
   {
      "id":"6e373d7856",
      "phone":"45616",
      "status":"unsent",
      "queued":"2014-10-20 12:32:52",
      "error_code":3103,
      "error_message":"Błędny numer odbiorcy",
      "text":"Tytuł MMS-a"
   },
   {
      "id":"bf069fe2c1",
      "phone":"7799123",
      "status":"unsent",
      "queued":"2014-10-20 12:32:52",
      "error_code":3103,
      "error_message":"Błędny numer odbiorcy",
      "text":"Tytuł MMS-a"
   }]
}

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.