Słownik pojęć
Aby ułatwić komunikację, przyjęliśmy pewne nazewnictwo. Poniżej przedstawiamy przyjęte założenia:
Komunikat
jest to informacja o takiej samej treści wysyłana do jednego lub wielu odbiorców,
Wiadomość
jest to treść komunikatu, który trafia do jednego lub wielu odbiorców. Wiadomość może składać się z jednego l\ ub więcej SMSów,
SMS
jest to część składowa wiadomości. Wiadomość może składać się zatem z jednego lub więcej SMSów, co jest uzależnione od długości wiadomości. W dalszej części dokumentacji znajduje się tabela określająca z ilu SMSów składowych może składać się wiadomość. Jest to uzależnione bowiem nie tylko od długości wiadomości, lecz także od rodzaju użytych znaków,
Znaki standardowe
zbiór symboli standardowych, których użycie w wiadomościach jest traktowane jako wprowadzenie pojedynczego znaku. Są to następujące znaki:
@ £ $ ¥ è é ù ì ò Ç Ø ø Å å Δ _ Φ Γ Λ Ω Π Ψ Σ Θ Ξ Æ æ ß É ! " # ¤ % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? ¡ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z Ä Ö Ñ Ü § ¿ a b c d e f g h i j k l m n o p q r s t u v w x y z ä ö ñ ü à
W skład znaków standardowych wchodzą również następujące znaki:
^ { } [ ] ~ \ | € oraz , przy czym znaki te w wiadomościach traktowane jest jako dwa znaki. Znaki specjalne wszelkie znaki nie zaliczone do znaków standardowych. Użycie w wiadomości choćby jednego znaku specjalnego oznacza, że każdy znak, w tym również znak standardowy, jest traktowany jako dwa znaki, co powoduje skrócenie długości wiadomości.
Znaki specjalne
wszelkie znaki nie zaliczone do znaków standardowych. Użycie w wiadomości choćby jednego znaku specjalnego oznacza, że każdy znak, w tym również znak standardowy, jest traktowany jako dwa znaki, co powoduje skrócenie długości wiadomości.
Kodowanie
Wszystkie komunikaty w systemie kodowane są za pomocą kodowania UTF-8. Takie kodowanie jest też wymagane dla wywołań API, aby możliwe było prawidłowe obsługiwanie znaków spoza standardowego zakresu ASCII.
Długość wiadomości
W zależności od liczby znaków użytych w wiadomościach oraz rodzaju znaków (znaki standardowe/niestandardowe) uzależnione jest, z ilu SMSów składowych złożona jest dana wiadomość. Co ważne, użycie w wiadomości choćby jednego znaku niestandardowego powoduje, że dana wiadomość może mieć krótszą długość.
Długość wiadomości (bez znaków niestandardowych) a liczba SMSów składowych
| Długość wiadomości | Liczba SMSów składowych |
|---|---|
| od 1 do 160 | 1 |
| od 161 do 306 | 2 |
| od 307 do 459 | 3 |
| od 460 do 612 | 4 |
| od 613 do 765 | 5 |
| od 766 do 918 | 6 |
Poniższa tabela prezentuje natomiast liczbę SMSów składowych w przypadku, gdy w wysyłanej wiadomości zostanie wprowadzony choćby jeden znak niestandardowy.
Długość wiadomości (ze znakami niestandardowymi) a liczba SMSów składowych
| Długość wiadomości | Liczba SMSów składowych |
|---|---|
| od 1 do 70 | 1 |
| od 71 do 134 | 2 |
| od 135 do 201 | 3 |
| od 202 do 268 | 4 |
| od 269 do 335 | 5 |
| od 336 do 402 | 6 |
Statusy końcowe operacji
Za każdym razem po wysłaniu wiadomości poprzez HTTP/SOAP SSL API, zwracany jest status wysyłki. Jest on potwierdzeniem, czy wiadomość została wysłana prawidłowo. Poniżej znajduje się lista możliwych zwracanych statusów wraz z opisem.
Status zwracane przy wysyłaniu wiadomości SMS
| Status | Opis statusu |
|---|---|
| 001 | Wysłano prawidłowo |
| 002 | Wiadomość prawidłowo przekazana do wysyłki, jednak z przyczyn technicznych zostanie wysłana w późniejszym czasie (dotyczy FasterSMS) |
| 011 | Nie przekazano potrzebnych parametrów - brak danych GET/POST |
| 021 | Zły login lub hasło |
| 022 | Brak wystarczających środków na koncie do realizacji tego typu wysyłki |
| 023 | Problem z wyslaniem wiadomości. Skontaktuj się z BOK. |
| 031 | Pole nadawcy jest zbyt długie (maksymalnie 16 znaków przy nadawcy numerycznym i 11 znaków przy nadawcy alfanumerycznym) |
| 032 | Nie podałeś/-aś ani jednego adresata wiadomości lub podany adresat jest nieprawidłowy (nieprawidłowy/nieistniejący numer komórkowy lub numer stacjonarny) |
| 033 | Nie podałeś/-aś treści wiadomości |
| 034 | Podano czas z przeszłości jako preferowany czas wysyłki |
| 035 | Liczba identyfikatorów własnych jest różna od liczby odbiorców wysyłanej wiadomości |
| 036 | Został wybrany typ wiadomości MaxSMS, ale nie został określony nadawca wiadomości (maksymalnie 11 znaków alfanumerycznych) |
| 037 | Zezwalasz tylko na wysyłanie wiadomości składających się z jednego SMSa, a Twoja wiadomość jest dłuższa |
| 038 | Treść wiadomości przekracza maksymalną dozwoloną pod względem technicznym długość (więcej niż 4 SMSy składowe na wiadomość)i |
| 039 | Wybrałeś wysyłkę typu FasterSMS i równocześnie próbujesz wysłać wiadomość do więcej niż jednego adresata, co jest niedozwolone (FasterSMS służy do wysyłania pojedynczych wiadomości SMS, np. z hasłem jednorazowym) |
| 040 | Nazwa nadawcy wiadomości nie została zarejestrowana. Skontaktuj się z BOK. |
| 080 | Adres IP, z którego przyszło wywołanie API nie znajduje się na liście adresów uprawnionych do korzystania z API. Zaloguj się do Panelu SMS, aby skonfigurować ustawienia API. |
| 041 | Wiadomość zawiera znaki spoza dozwolonego zakresu znaków UTF-8. |
| 091 | Błąd połączenia z bazą. Skontaktuj się z firmą PromoSMS |
| 092 | Błąd podczas wysyłki wiadomości. Skontaktuj się z firmą PromoSMS |
Raporty doręczenia wiadomości
Każda wiadomość może mieć przypisany jeden z czterech rodzajów statusu. Ich pełny opis znajduje się w poniższej tabeli.
Rodzaje statusów
| Status | Opis statusu |
|---|---|
| 0 | Wiadomość nie została jeszcze przekazana do wysyłki. Taki stan możliwy jest zaraz po zleceniu wysyłki (wiadomości są przekazywane do operatora średnio co 15 sekund) lub w przypadku wiadomości, które mają być wysłane w przyszłości (parametr time przy wysyłce) |
| 4 lub 8 | Wiadomość została przekazana do operatora. W tym momencie platforma PromoSMS czeka na realizację zlecenia przez operatora. Stan nr 8 można porównać do wysłania SMS z telefonu, kiedy telefon komórkowy wysłał wiadomość, lecz nie otrzymaliśmy jeszcze potwierdzenia dostarczenia/niedostarczenia od operatora. Ponadto, jeżeli odbiorca ma na przykład wyłączony telefon, a operator próbował dostarczyć prawidłowo tę wiadomość, to także należy spodziewać się takiego stanu wiadomości |
| 1 | Status o numerze jeden oznacza, że wiadomość została dostarczona na telefon komórkowy odbiorcy |
| 2 lub 16 | Wiadomość nie została dostarczona. Przyczyn może być kilka. Najbardziej prawdopodobne to: numer odbiorcy jest nieprawidłowy telefon odbiorcy jest wyłączony przez długi czas i wiadomość wygasła |
Typy numerów komórkowych
W tabeli poniżej znajduje się lista typów numerów rozpoznawanych przez system.
Opis typów numerów
| Typ numeru | Opis typu |
|---|---|
| 1 | Numer stacjonarny |
| 2 | Numer komórkowy |
| 3 | W niektórych krajach możliwe jest, że dany numer jest równocześnie numerem komórkowym/stacjonarnym |
| 4 | Darmowy numer |
| 5 | Number o podwyższonej płatności |
| 6 | Koszt za połączenie jest współdzielony między odbiorcą i nadawcą (np. numer typu 801..) |
| 7 | Numer VoIP |
| 8 | Numer osobisty, możliwe że jest równocześnie komórkowy jak i stacjonarny (patrz tutaj: http://en.wikipedia.org/wiki/Personal_Numbers ) |
| 9 | Pager |
| 10 | tzw. Universal Access Numbers lub Company Numbers (Jeden numer firmowy, ale połączenie może być odpowiednio przełączane) |
| 10 lub -1 | Numer niepoprawny lub inny, niezidentyfikowany rodzaj numeru |
