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ż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"
}

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

Content-Type	rozszerzenie pliku
image/gif	gif
image/jpeg	jpeg
image/jpg	jpg
image/png	png
text/plain	txt

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 użytkownika API.
password	String	hasło	Hasło użytkownika API.
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.