Wysyłka wiadomości

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

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/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śc 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 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.