Kontroler służy do wysyłki pojedynczych wiadomości SMS. Domyślnie wszystkie parametry muszą być przekazane w kodowaniu UTF-8.

Uwagi ogólne

Numery telefonu muszą być podawane w formacie 9 lub 11 cyfrowym (np. 48502602702 lub 502602702), możliwe jest także dodanie znaku „+” przed prefixem kraju (np. +48502602702). Obecnie sms'y są wysyłane tylko do polskich numerów, czyli do numerów z prefiksami rozpoczynających się od +48.

Treść pojedynczej wiadomości to standardowo do 160 znaków lub 70 znaków w przypadku wystąpienia chociaż jednego znaku specjalnego. Maksymalna długość wiadomości wynosi 459 znaków (lub 200 ze znakami specjalnymi) i jest wysłana jako 3 połączone SMS-y.

Znakami specjalnymi są wszystkie znaki nie mieszczące się w zestawie znaków:
@£$¥èéùìòÇØøÅå_^{}\[~]| ÆæßÉ!"#¤%&'()*€+,-./0-9:;<=>?A-ZÄÖÑܧ¿a-zäöñüà

SMS bez znaków specjalnych		SMS ze znakami specjalnymi
Maksymalna ilość znaków	Ilość SMSów	Maksymalna ilość znaków	Ilość SMSów
160	1	70	1
306	2	134	2
459	3	200	3

Rodzaje wiadomości SMS

Kontroler umożliwia wysłanie wiadomości dwóch rodzajów: wiadomości typu PRO oraz 2WAY.

SMS typu PRO to wiadomość wysyłana z nadpisem alfanumerycznym, czyli zdefiniowanym polem nadawcy. Pole to nie może zawierać więcej niż 11 znaków z zestawu a-zA-Z0-9 oraz znak myślnika „-”. Aby korzystać z SMS typu PRO konieczne jest zgłoszenie nadpisu w systemie FreshMail.

SMS typu 2WAY to wiadomość wysłana z konkretnego numeru telefonu na który odbiorca może odpowiedzieć. Odpowiedź zostanie zarejestrowana w systemie FreshMail.

Cennik

Aby móc korzystać z wysyłki SMS należy w pierwszej kolejności podpisać umowę. Ceny za sms typu PRO, 2WAY są zawarte w umowie.

Wysyłanie wiadomości SMS  

Wywołanie: POST /rest/sms

Dane w POST.

Parametr	Wymagany	Uwagi	Opis
gsm	tak	Numer telefonu	W formacie +48XXXXXXXXX lub XXXXXXXXX
text	tak	Treść wiadomości SMS
from	nie	Nadpis w wiadomości SMS	Nadpis w pierwszej kolejności musi zostać zgłoszony, aby można było z niego korzystać. Aby wysłać wiadomość typu 2WAY należy w polu from umieścić wartość 2way
single	nie	Wysyłka pojedynczej wiadomości SMS	Jeśli ta opcja przyjmuje wartość true wtedy wiadomość zostanie wysłana tylko jeśli zmieści się w pojedynczym SMSie, jeśli wiadomość będzie za długa nie zostanie wysłana
messageId	nie	Identyfikator wiadomości	String nie przekraczający 42 znaki. Zostanie zwrócony razem z raportem doręczenia

 

Przykładowe żądanie (wykonane za pomocą biblioteki Curl):

curl -v -H "X-Rest-ApiKey:APIKEY" -H "X-Rest-ApiSign:APISIGN" -H "Content-Type:application/json" https://api.freshmail.com/rest/sms -d '{"gsm":"phoneNumber","text":"Example SMS message","messageId":432523,"from":"Recepcja"}'

Poprawna odpowiedź:

{"status":"OK"}

Błędna odpowiedź:

{
   "status":"ERROR",
   "errors":[
      {
         "message":"SMS inscription (from) doesn't exist",
         "code":1105
      }
   ]
}

Kody błędów:

Kod błędu	Opis
1101	Numer GSM jest błędny
1102	Treść SMSa jest pusta
1103	Treść SMSa jest za długa (SMS bez znaków specjalnych)
1104	Treść SMSa jest za długa (SMS ze znakami specjalnymi)
1105	Nadawca jest błędny
1106	Nadawca został niepotwierdzony (nadawca jest poprawny, ale oczekuje na weryfikację)
1107	Żądanie jest w złym kodowaniu, obsługiwane kodowanie to UTF-8
1108	Treść SMSa jest za długa (SMS bez znaków specjalnych z opcją single=1)
1109	Treść SMSa jest za długa (SMS ze znakami specjalnymi z opcją single=1)
1110	Numer nadawcy SMSa 2WAY nie jest skonfigurowany lub wygasł
1150	SMS nie zostanie wysłany, konieczne jest podpisanie umowy

Pobranie raportu doręczenia wiadomości

sms/reports

Raporty wiadomości SMS

Parametr	Wymagany	Uwagi	Opis
startDate	nie	Data od której zostaną pobrane raporty	W formacie YYYY-MM-DD HH:ii:ss lub YYYY-MM-DD
endDate	nie	Data od której zostaną pobrane raporty	W formacie YYYY-MM-DD HH:ii:ss lub YYYY-MM-DD
page	nie	Strona z wynikami którą chcemy pobrać, w domyśle zawsze pobieramy stronę nr 1	Nadpis w pierwszej kolejności musi zostać zgłoszony, aby można było z niego korzystać. Aby wysłać wiadomość typu 2WAY należy w polu from umieścić wartość 2way

 

Przykładowe żądanie (wykonane za pomocą biblioteki Curl):

curl -v -H "X-Rest-ApiKey:APIKEY" -H "X-Rest-ApiSign:APISIGN" -H "Content-Type:application/json" https://api.freshmail.com/rest/sms/reports -d '{"startDate":"2015-12-17","endDate":"2015-12-18"}'

Poprawna odpowiedź:

{
   "status":"OK",
   "data":[
      {
         "send_date":"2015-12-17 13:21:42",
         "gsm":"+48555666777",
         "from":"",
         "type":"eco",
         "message_id":"myCustomId-423657",
         "modification_date":"2015-12-17 13:24:13",
         "status":"DELIVERED",
         "responses":[]
      },
      {
         "send_date":"2015-12-17 13:27:21",
         "gsm":"666777888",
         "from":"2way",
         "type":"2way",
         "message_id":"myCustomId-54321345",
         "modification_date":"2015-12-17 13:28:01",
         "status":"DELIVERED",
         "responses":[  
               {  
                  "text":"Great response",
                  "time":"2015-12-30 07:48:33"
               },
               {  
                  "text":"My another response",
                  "time":"2015-12-30 08:34:41"
               }
            ]
      },
      {
         "send_date":"2015-12-17 13:27:29",
         "gsm":"777888999",
         "from":"Recepcja",
         "type":"pro",
         "message_id":"myCustomId-3245154",
         "modification_date":"2015-12-17 13:28:02",
         "status":"SENT",
         "responses":[]
      },
      {
         "send_date":"2015-12-17 13:29:01",
         "gsm":"",
         "from":"Recepcja",
         "type":"pro",
         "message_id":"myCustomId-3245154",
         "modification_date":"2015-12-17 13:29:01",
         "status":"ERROR",
         "error":"INVALID_PHONE_NUMBER",
         "responses":[]
      },
      {
         "send_date":"2015-12-18 09:01:01",
         "gsm":"888999000",
         "from":"",
         "type":"mms",
         "message_id":"myCustomId-41532",
         "modification_date":"2015-12-18 09:01:55",
         "status":"DELIVERED",
         "responses":[]
      }
   ],
   "resultCounts":5,
   "allData":1
}

Pola zawarte w odpowiedzi:

Parametr	Opis
data	Zawiera wszystkie dane o wysłanych w danym okresie wiadomościach SMS
resultCounts	Ilośc zwróconych rekordów w polu data
allData	Czy zostały zwrócone wszystkie rekordy z danego okresu. Limit ilości zwracanych danych wynosi 1000 rekordów. Jeśli w odpowiedzi będzie znalezionych więcej rekordów zwracane jest pierwsze 1000, kolejne dane należy pobierać korzystając z parametru page

Możliwe statusy wiadomości SMS

Parametr	Opis
NOT_FOUND	Błędny numer ID lub raport wygasł
EXPIRED	Wiadomość niedostarczona z powodu zbyt długiego czasu niedostępności numeru
SENT	Wiadomość została wysłana ale operator nie zwrócił jeszcze raportu doręczenia
DELIVERED	Wiadomość dotarła do odbiorcy
UNDELIVERED	Wiadomość niedostarczona (np.: błędny numer, numer niedostępny)
FAILED	Błąd podczas wysyłki wiadomości - prosimy zgłosić
REJECTED	Wiadomość niedostarczona (np.: błędny numer, numer niedostępny)
UNKNOWN	Brak raportu doręczenia dla wiadomości (wiadomość doręczona lub brak możliwości doręczenia)
QUEUE	Wiadomość czeka w kolejce na wysyłkę
ACCEPTED	Wiadomość przyjęta przez operatora
RENEWAL	Wykonana była próba połączenia która nie została odebrana, połączenie zostanie ponowione.
STOP	Wysyłka wiadomość została wstrzymana
ERROR	Wiadomość nie została wysłana

Jeśli wiadomość SMS nie została wysłana (czyli status wiadomości to ERROR) w dodatkowym parametrze error pojawi się powód nie wysłania wiadomości. Poniżej znajdują się możliwe kody błędów wysyłki wiadomości:

Parametr	Opis
INVALID_PHONE_NUMBER	Błędnym numer telefonu lub brak numeru telefonu
WRONG_SENDER_NAME	Niepoprawna nazwa nadawcy (najprawdopodobniej nadpis nie został zgłoszony)
UNKNOWN_ERROR	Wiadomość nie została wysłana, wewnętrzny błąd operatora

Pole modification_date:

W tym polu znajduje się czas ostatniej modyfikacji pola STATUS.

Odpowiedz na wiadomości typu 2WAY

Jeśli w polu from została umieszczona wartość 2way to wiadomość SMS jest wysyłana z numeru telefonu na który odbiorca może odpisać. Wszystkie odpowiedzi na wiadomości znajdują się w polu responses i mają format tablicy. Jeśli odbiorca SMSa odpowie na niego więcej niż jeden raz kolejne odpowiedzi będą elementami tablicy jak w przykładzie powyżej.