Wiadomości SMS

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äöñüà

Uwaga

Znaki: ^ { } [ ] ~ € \ | <enter> zawsze liczone są podwójnie (bez względu na to czy wysyłamy SMS ze znakami specjalnymi czy bez) ze względu na wymogi specyfikacji GSM.

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

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

Wiadomości MMS

Bramka umożliwia także wysłanie wiadomości MMS. Taka wiadomość składa się z krótkiego tematu oraz obrazka w formacie jpg, gif lub png.

Cennik

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

Wysyłanie wiadomości SMS  

sms/send

Wysyła wiadomość SMS.

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ḱa pojedyńczej wiadomości SMS Jeśli ta opcja przyjmuje wartość true wtedy wiadomość zostanie wysłana tylko jeśli zmieści się w pojecynczym 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)
1150 SMS nie zostanie wysłany, konieczne jest podpisanie umowy

sms/sendmms

Wysyła wiadomość MMS.

Parametr Wymagany Uwagi Opis
gsm tak Numer telefonu W formacie +48XXXXXXXXX lub XXXXXXXXX
subject tak Temat wiadomości  String nie przekraczający 30 znaków
image tak Obrazek wysłany w wiadomości MMS String reprezentujący bezwzględny URL do obrazka
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/sendmms -d '{"gsm":"phoneNumber","subject":"Example MMS message","messageId":432523,"image":"http://d2651x052v6uoq.cloudfront.net/media/sass/images/logo.png"}'

Poprawna odpowiedź:

{"status":"OK"}

Błędna odpowiedź:

{  
   "status":"ERROR",
   "errors":[  
      {  
         "message":"Subject of MMS message too long, limit 30 characters",
         "code":1110
      }
   ]
}

Kody błędów:

Kod błędu Opis
1101 Numer GSM jest błędny
1102 Temat wiadomości MMS jest pusty
1110 Temat wiadomości MMS jest za długi
1150 SMS nie zostanie wysłany, konieczne jest podpisanie umowy

Pobranie raportu doręczenia wiadomości

sms/reports

Raporty wiadomości SMS/MMS.

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 wynosi1000 rekordów. Jeśli w odpowiedzi będzie znalezionych więcej rekordów zwracane jest pierwsze1000, kolejne dane należy pobierać korzystając z parametru page

Możliwe statusy wiadomości SMS/MMS:

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 zosał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 poluresponses 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.