Seznam čárkou oddělených telefonních čísel příjemců. Česká telefonní čísla mohou být bez mezinárodní předvolby (+420), zahraniční
čísla musí mít předvolbu.
Jedná se o jediný povinný parametr. Musí být zadané alespoň jedno platné telefonní číslo.
text
Text SMS. Maximálně 1000 znaků. V případě wappushe se jedná o URL adresu.
Služba sama provede případné rozdělení na více SMS.
name
Název wappushe. V případě textové SMS nemá parametr žádný význam.
Způsob rozdělení SMS. Seznam možných hodnot naleznete v seznamu konstant.
Výchozí hodnotou je concat.
Parametr má význam pouze u zpráv typu text, u ostatních
je ignorován.
delivery
Zda doručit doručenku na adresu, kterou si uživatel definoval.
Pokud chcete zaslat doručenku, zadejte jako hodnotu 1, v případě, že doručenku nechcete, parametr nezadávejte.
address
Adresa (URL nebo email), na kterou zaslat doručenku.
V případě, že chcete zaslat doručenku na jinou adresu, než jste si, jako výchozí, definovali v nastavení, potom vyplňte tento parametr.
Pokud vyplníte parametry address i delivery má parametr address přednost.
senddate
Čas odeslání SMS. V případě, že chcete definovat, kdy má být SMS odeslána, zadejte tento parametr.
Výchozí hodnotou je prázdný řetězec - SMS bude odeslána okamžitě.
K naúčtování SMS dochází až ve chvíli, kdy má být odeslána, tzn. je možné, že požadavek na API proběhne v pořádku, ale v případě, že nebudete mít
v danou chvíli dostatek prostředků na účtu, nedojde k odeslání.
Možnou hodnotou je řetězec odpovídající GNU date (resp. parametru funkce strtotime() v PHP).
//možné hodnoty
"2011-03-05 15:00:00" = 5. 3. 2011, 15:00
(datum a čes ve formátu rrrr-mm-dd hh:nn:ss = rok, měsíc, den, hodina, minuta, sekunda)
"+1 hour" = za hodinu
"next Monday" = příští pondělí (v 00:00)
"next Monday 15:15" = příští pondělí v 15:15
source
Číslo nebo textový identifikátor odesilatele.
Výchozí hodnotou je prázdný řetězec - SMS bude odeslána z čísla ProfiSMS.
Možnou hodnotou je buď telefonní číslo v mezinárodním tvaru, nebo text skládající se z písmen anglické abecedy, číslic a znaků . a -
(tečka a pomlčka). V případě textu může být tento maximálně 11 znaků dlouhý, bude-li text delší, nebo bude-li obsahovat nepovolené znaky,
potom dojde k jeho automatické úpravě na straně ProfiSMS.
Nelze použít najednou použít session a source. Pokud je použitá session, má přednost a SMS je odeslaná z normálního
MSISDN.
Uživatel smí obecně používat pouze registrovaná telefonní čísla: čísla registrovaná pomocí postupu, který je popsán v uživatelském rozhraní
ProfiSMS. Pokud chcete používat jiná telefonní čísla (např. pevnou linku) nebo textový identifikátor, kontaktujte obchodní oddělení,
kde vám jej povolí a dohodnou s Vámi obchodní podmínky.
currency
Měna účtu, který bude použit pro naúčtování SMS. Seznam možných hodnot naleznete v seznamu konstant.
Výchozí hodnotou je CZK.
validity
Počet minut, po které je SMS platná.
Jedná se o počet minut od předání SMS operátorovi. Pokud se operátorovi nepodaří doručit SMS příjemci v daném čase, operátor SMS zruší
(vizte možné stavy doručení).
Výchozí hodnotou je 2880 (2 dny). Maximální hodnotou je 2880, minimální 5.
pid
Libovolný řetězec, unikátní identifikátor rozesílky. V případě odesílání jedné SMS pomocí HTTP (i na více čísel) nemá význam.
Zda nezobrazovat SMS v listování. Standardně se všechny odeslané SMS listují (zobrazují uživateli).
Hodnota 1 znamená, že SMS nebude listována,
hodnota 0 znamená, že SMS bude listována.
Výchozí hodnota (pokud není parametr zadán) je 0.
userdata
Libovolná textová data, která budou uložena k SMS.
usersource
Libovolná textová data. Data by měla reprezentovat "zdroj" SMS. Pokud uživatel např. používá více kanálů pro zasílání SMS, nebo má více
středisek apod. tento parametr repezentuje název tohoto zdroje. Podle tohoto zdroje lze pak listovat/filtrovat SMS.
session
Systém nabízí možnost příjmout odpověď na odeslanou SMS. Pokud bude SMS odeslána na nějaké číslo, bude nastaven tento
parametr a systém přijme z cílového čísla SMS (do jednoho dne), bude tato SMS přiřazena uživateli, který odeslal původní SMS ze systému.
Toto nastavení (session) platí pro posledního uživatele, který zašle SMS na dané číslo (pro každé číslo mohou být platné pouze session od jendoho uživatele).
Nelze použít najednou použít session a source. Pokud je použitá session, má přednost a SMS je odeslaná z normálního
MSISDN.
Příklady volání API
ukázka 1: Základní požadavek na zaslaní SMS (implementace v PHP)
Stav účtu, ze kterého byly naúčtované SMS. Zůstatek po odeslání.
price
Cena bez DPH za odeslané SMS. Měnou je měna účtu zvoleného při požadavku.
pricevat
Cena s DPH za odeslané SMS. Měnou je měna účtu zvoleného při požadavku.
address
Adresa pro doručenku (na základě parametrů delivery nebo address).
partsCount
Počet částí SMS, na které byla SMS rozdělena. Číslo neudává celkový počet částí, které vzniknou požadavkem, ten závisí i na počtu
platných čísel příjemců.
pid
Zaslaný parametr pid.
Popis pole sms
Objekt data obsahuje vlastnost sms, která je polem, toto pole obsahuje seznam SMS, které byly/budou odeslané,
pro každé číslo příjemce jeden objekt. Každá SMS v tomto poli je objektem s vlastnostmi:
msisdn
Telefonní číslo příjemce (zformátované do mezinárodního tvaru).
id
Unikátní identifikátor SMS (nejedná o sekvenční číslo, nereprezentuje pořadí v systému ProfiSMS).
V současné době má vlastnost formát čísla, ale jedná se o řetězec, v budoucnosti se může tato vlastnost změnit na čistý řetězec.
Tento identifikátor se používá při předávání doručenek a pro dotazovaní na stav SMS.
V některých případech může dojít k "částečné" nemožnosti odeslání:
Pokud jsou některá čísla neplatná a alespoň jedno platné, potom dojde k odeslání SMS na platná čísla
(vizte popis odpovědi a ukázky).
V případě, že není dostatek prostředků na účtu k odeslání SMS na všechna čísla, potom se neodešle žádná SMS a dojde k chybě
BA_LOW_CREDIT
Doručenky
Doručenky se týkají SMS zaslaných s parametry delivery nebo address. Doručenky jsou zasílány na
zadaný email, nebo je voláno zadané URL s parametry identifikujícími SMS a stav doručení. Informace se poskytují jak
pro celou SMS, tak pro jednotlivé části SMS (s výjimkou uvedenou níže).
Doručenky na email
V případě, že se SMS má doručit na email, potom:
Pokud je SMS zaslána najednou, potom je zaslán email pouze pro SMS (pro jedinou část se email nezasílá).
Pokud je SMS rozdělena na více částí, zasílají se emaily postupně pro jednotlivé části, jak jsou doručované (nebo nedoručované)
a pokud jsou informace o doručení pro všechny části SMS, potom se zašle email o doručení pro celou SMS.
Doručenky na URL
V případě doručenek na URL se informace předávají pro všechny části i celou SMS bez ohledu na to,
zda je SMS rozdělena na více částí, nebo odeslána najednou. Informace se předává voláním zadaného URL, ke kterému jsou přidané
další parametry s informacemi o SMS nebo její části (informace je předávána pomocí GET protokolu).
V případě doručení části SMS, je voláno zadané URL. Informace o doručení celé SMS jsou předávané ve chvíli, kdy jsou k dispozici informace
o všech částech.
Předávané parametry v případě části SMS
Parametry, jejich název a formát hodnoty jsou částečně definované požadavkem a kompatibilitu s předchozí verzí.
msisdn
Telefonní číslo příjemce.
msg
Prvních 500 znaků textu části SMS.
queuetime
Datum a čas odeslání části SMS ve formátu rrrr-mm-dd hh:nn:ss (odeslání, nikoliv zařazení do fronty).
deliveredtime
Datum a čas získání informací o doručení ve formátu rrrr-mm-dd hh:nn:ss. Datum a čas je zaokrouhlen na minuty dolů.
Parametr má hodnotu 1, pokud se podařilo část SMS doručit (Smsout::DELIVERY_DELIVERED), v ostatních případech
má hodnotu 0.
smsid
Identifikátor části SMS (vizte vlastnost part v odpovědi při odeslání SMS).
fullsmsid
Identifikátor SMS (vizte vlastnost id v odpovědi při odeslání SMS).
ukázka 9: Volání URL
/**
V nísledujícím příkladě jsou vidět doručenky pro SMS s textem
příliš žluťoučký kůň úpěl ďábelské ódy, PŘÍLIŠ ŽLUŤOUČKÝ KŮŇ ÚPĚL ĎÁBELSKÉ ÓDY
která byla rozdělena na 2 části a byla úspěšne doručena
http://test.company.cz/receive.php?msisdn=%2B420605582922
&msg=p%C5%99%C3%ADli%C5%A1%20%C5%BElu%C5%A5ou%C4%8Dk%C3%BD%20k%C5%AF%C5%88%20%C3%BAp%C4%9Bl%20%C4%8F%C3%A1belsk%C3%A9%20%C3%B3dy,%20P%C5%98%C3%8DLI%C5%A0%20%C5%BDLU%C5%A4OU%C4%8CK%C3%9D%20K%C5%AE%C5%87%20%C3%9AP%C4%9AL%20%C4%8E
&queuetime=2010-12-28%2017:55:03&deliveredtime=2010-12-28%2017:56:00
&statdeliver=0&statdeliverstr=delivered&ok=1&smsid=44109244
&fullsmsid=1544185
http://test.company.cz/receive.php?msisdn=%2B420605582922
&msg=%C3%81BELSK%C3%89%20%C3%93DY&queuetime=2010-12-28%2017:55:03
&deliveredtime=2010-12-28%2017:56:00&statdeliver=0
&statdeliverstr=delivered&ok=1&smsid=44109245
&fullsmsid=1544185
*/
Předávané parametry v případě celé SMS
Parametry, jejich název a formát hodnoty jsou částečně definované požadavkem a kompatibilitu s předchozí verzí.
msisdn
Telefonní číslo příjemce.
msg
Prvních 500 znaků textu celé SMS.
queuetime
Datum a čas odeslání poslední části SMS ve formátu rrrr-mm-dd hh:nn:ss (odeslání, nikoliv zařazení do fronty).
deliveredtime
Datum a čas získání informací o doručení poslední části SMS ve formátu rrrr-mm-dd hh:nn:ss. Datum a čas je zaokrouhlen na minuty dolů.
Parametr má hodnotu 1, pokud se podařilo celou SMS doručit (Smsout::DELIVERY_DELIVERED), v ostatních případech
má hodnotu 0.
smsid
Parametr má vždy hodnotu 0
fullsmsid
Identifikátor SMS (vizte vlastnost id v odpovědi při odeslání SMS).
ukázka 10: Volání URL
/**
V následujícím příkladě je vidět doručenka pro celou SMS s textem
příliš žluťoučký kůň úpěl ďábelské ódy, PŘÍLIŠ ŽLUŤOUČKÝ KŮŇ ÚPĚL ĎÁBELSKÉ ÓDY
http://test.company.cz/receive.php?msisdn=%2B420605582922
&msg=p%C5%99%C3%ADli%C5%A1%20%C5%BElu%C5%A5ou%C4%8Dk%C3%BD%20k%C5%AF%C5%88%20%C3%BAp%C4%9Bl%20%C4%8F%C3%A1belsk%C3%A9%20%C3%B3dy,%20P%C5%98%C3%8DLI%C5%A0%20%C5%BDLU%C5%A4OU%C4%8CK%C3%9D%20K%C5%AE%C5%87%20%C3%9AP%C4%9AL%20%C4%8E%C3%81BELSK%C3%89%20%C3%93DY
&queuetime=2010-12-28%2017:55:03&deliveredtime=2010-12-28%2017:55:00
&statdeliver=0&statdeliverstr=delivered&ok=1&smsid=0&fullsmsid=1544185
*/
SMS zaslaná pomocí PDU a UDH
SMS se zasílají ve formě tzv.
PDU (data zprávy) a
v případě některých specifických zpráv je toto doplněno o tzv.
UDH (typ zprávy, hlavička).
Pro textové správy, i včetně diakritiky, i dlouhé zprávy (rozdělené do více SMS) a
wappush zprávy, jsou tyto údaje (PDU/UDH) vypočítávány systémem, pokud používáte výše popsané
API.
Pokud ale posíláte i jiné
typy zpráv, nebo máte již PDU a UDH předpočítané, je možné je zasílat přímo.
Parametry volání API
API pro zaslání zprávy přímo pomocí PDU/UDH je až na pár výjimek shodné s
výše uvedeným odesíláním SMS.
Není-li v následujícím seznamu uveden některý ze standardních
parametrů, potom zůstal jeho význam nezměněn.
text
Není nutné uvádět, nemá význam (je-li parametr zadán, je ignorován).
name
Není nutné uvádět, nemá význam (je-li parametr zadán, je ignorován).