Zaslání SMS
Toto API slouží k zaslání SMS pomocí ProfiSMS (jejich naúčtování je součástí zaslání).
Základní popis a tvar API volání a odpovědi najdete popsané samostatně.
Pro testovací účely můžete používat testovacího uživatele.
Služba
SMS API patří do služby SMS (sms).
Parametry volání API
Volání musí obsahovat všechny základní parametry.
- CTRL
-
Pevná hodnota: sms
- msisdn
-
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.
- type
-
Typ SMS (textová, wappush, pdu).
Výchozí hodnota je text.
- split
-
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.
Vizte Vícenásobné zaslání SMS.
- hide_sms
-
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.
- rm_diacritics
-
Parametr pro klienty bývalé Aximy, parametr odstraňuje diakritiku.
Hodnota 1 znamená, že znaky budou odstraněny, hodnota 0 znamená, že zůstanou beze změny.
Výchozí hodnota (pokud není parametr zadán) je 0.
- maxFragmentsLimit
-
Parametr pro klienty bývalé Aximy, parametr nastavuje limit pro fragmentaci zpráv uložených do databáze.
Výchozí hodnota (pokud není parametr zadán) je null.
Příklady volání API
V případe více čísel nebo delšího textu doporučujeme použít protokol POST
.
URL může být maximálně 2048 znaků dlouhé.
Odpověď na úspěšný požadavek na API
Základní formát odpovědi naleznete v obecném popisu API.
Popis objektu data
Objekt data obsahuje tyto vlastnosti:
- invalid
-
Pole neplatných čísel. V případě, že některá čísla v požadavku jsou neplatná, dojde k odeslání SMS na platná čísla a toto pole se naplní neplatnými.
V případě, že jsou všechna čísla neplatná, požadavek skončí s chybou
SMSOUTSMS_MISSING_MSISDN
. - sms
- Pole SMS, vizte níže.
- credit
- 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.
- state
- Stav SMS.
- delivery
- Stav doručení SMS.
- queued
- Datum zařazení SMS do fronty ve formátu rrrr-mm-dd hh:nn:ss.
- delivered
- Datum doručení SMS (nastavení stavu SMS, tzn. i datum nedoručení SMS, apod.) ve formátu rrrr-mm-dd hh:nn:ss.
- part
-
Pole unikátních identifikátorů částí 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.
Ukázky požadavků a odpovědí
Základní ukázka zaslání krátké SMS na jedno telefonní číslo.
Všimněte si, že:
- state obsahuje queued. SMS byla právě zařazena do fronty.
- delivery obsahuje nostate. SMS ještě nebyla odeslána, nejsou žádné informace o doručení.
- delivered je prázdné. SMS ještě nebyla odeslána, nejsou žádné informace o doručení.
- Pole part obsahuje 1 identifikátor, SMS byla zaslána najednou.
Ukázka zaslání SMS na více telefonních čísel.
Všimněte si, že:
- Pole invalid obsahuje neplatná čísla.
- Pole sms obsahuje 3 objekty, každý objekt reprezentuje jedno telefonní číslo.
- Pole part pro všechny SMS obsahuje 2 identifikátory, SMS byla rozdělena na 2 části.
Ukázka zaslání zpožděné SMS.
Všimněte si, že:
- state obsahuje inserted. SMS byla vložena do platformy, ale není ve frontě.
- Všechny položky ukazující cenu SMS jsou nulové, k naúčtování dojde, až bude SMS zařazena do fronty.
- queued je prázdné, SMS není zařazena do fronty.
- part je prázdné, SMS není zařazena do fronty.
Odpověď na neúspěšný požadavek na API
Základní formát odpovědi naleznete v obecném popisu API.
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 seznamu konstant naleznete výčet a popis konstant, které definují stav doručení SMS a stav doručení části SMS .
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ů.
- statdeliver
-
Stav doručení části SMS jako číslo.
Vizte stavy doručení části SMS, číslo potom odpovídá pořadí stavu, jak jsou uvedena v seznamu, počínaje -1.
- statdeliverstr
- Stav doručení části SMS, jak je uveden v seznamu (jako řetězec).
- ok
- 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).
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ů.
- statdeliver
-
Stav doručení SMS jako číslo.
Vizte stavy doručení SMS, číslo potom odpovídá pořadí stavu, jak jsou uvedena v seznamu, počínaje -1.
- statdeliverstr
- Stav doručení SMS, jak je uveden v seznamu (jako řetězec).
- ok
- 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).
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).
- type
-
Požadovaná hodnota je pdu.
- encoding
-
Standardní možné hodnoty jsou 7 (pro běžnou textovou SMS bez diakritiky), 16 (pro běžnou SMS s diakritikou) a 8 (pro binární SMS).
- udh
-
UDH zprávy.
UDH musí obsahovat i bity s délkou UDH. Parametr zadávejte ve formě hexadecimálního zápisu.
- pdu
-
PDU zprávy.
V případě 7bitového kódování zadávejte vždy text zprávy. V případě ostatních kódování zadávejte obsah zakódovaný a ve formě hexadecimálního zápisu.
Formát odpovědi je shodný.