SemaSMS posílá z webu Joomla SMS přes brány BulkGate a SMSbrána.cz: notifikace o objednávkách VirtueMart podle stavu, ruční SMS z detailu objednávky a SMS kampaně na seznamy AcyMailingu. Všechny zprávy jdou přes jednu frontu s opakováním, záložní bránou a doručenkami.
| Joomla | PHP | Brány | Aktuální verze |
|---|---|---|---|
| 5.4+, 6.x | 8.2+ se sodium | BulkGate, SMSbrána.cz | 1.1.2 |
1. Požadavky
- Joomla 5.4 nebo novější, nebo Joomla 6
- PHP 8.2 nebo novější s rozšířením
sodium(šifrování přístupových údajů bran) - účet u brány BulkGate nebo SMSbrána.cz s přístupem k API
- cron hostingu, nebo Plánovač úloh Joomla
- VirtueMart 4 – jen pro SMS k objednávkám (nepovinné)
- AcyMailing – jen pro SMS kampaně (nepovinné)
Jazyky: čeština, slovenština a angličtina – administrace i texty, které SemaSMS předvyplňuje.
2. Jak začít
- Nainstalujte balíček SemaSMS for Joomla (Systém → Instalace → Rozšíření). Nainstaluje komponentu a pluginy Systém - SemaSMS, Úloha - SemaSMS a VM Extended - SemaSMS. Pluginy se při první instalaci samy zapnou, plugin pro VirtueMart jen tehdy, když je VirtueMart nainstalovaný.
- Komponenty → SemaSMS → Brány: přidejte bránu, vyplňte přístup a klikněte na Poslat testovací SMS (kapitola Brány).
- V Nastavení vyplňte Token cron URL a nastavte cron, nebo založte úlohu plánovače SemaSMS – zpracovat frontu (kapitola Fronta a cron).
- Pro doručenky a odhlášení STOP vyplňte Klíč webhooků a adresu z Přehledu zadejte v portálu brány (kapitola Doručenky a příchozí SMS).
- Založte Šablony a v Pravidlech VirtueMart určete, při kterém stavu objednávky se která pošle.
- Na kampaně nastavte v Nastavení → Kampaně pole s telefonem v AcyMailingu.
Karta Stav instalace v Přehledu ukáže, co ještě chybí: aktivní brána, zapnuté pluginy a poslední běh cronu.
3. Brány
Komponenty → SemaSMS → Brány jsou účty, přes které SMS odcházejí. Bran může být víc.
- Název – pro vaši orientaci, např. „BulkGate – hlavní účet“.
- Brána – BulkGate, SMSbrána.cz nebo Test (nic neodesílá). Po výběru se formulář načte s poli dané brány. U uložené brány už typ změnit nejde.
- Pořadí – nižší číslo se zkouší dřív. Když brána zprávu odmítne nebo je opakovaně nedostupná, převezme ji další v pořadí.
Hesla a tokeny se ukládají šifrovaně a do formuláře se už nevracejí. Pole s uloženou hodnotou nechte prázdné, pokud ji neměníte.
BulkGate
- Application ID a Application token najdete v portálu BulkGate v Moduly a API → API → vaše aplikace.
- Kontrola duplicit – BulkGate zahodí stejný text na stejné číslo do 5 minut. Chrání před dvojím odesláním, když se zpráva po výpadku spojení zkouší znovu.
- Štítek – nepovinný, zobrazí se ve statistikách BulkGate.
SMSbrána.cz
- Přihlašovací jméno API a Heslo API najdete v portálu SMSbrány v API → Nastavení API. API musí být aktivní a IP adresa serveru povolená.
- Varianta přihlášení – když test spojení s výchozí variantou selže na přihlášení, zkuste druhou.
Země a odesílatel
Bez řádků brána posílá do všech zemí s výchozím odesílatelem účtu. S řádky posílá jen do uvedených zemí; řádek * platí pro všechny ostatní. U každé země zvolíte Typ odesílatele (systémové číslo, textový odesílatel, vlastní ověřené číslo…) a Odesílatele. Textový odesílatel a vlastní číslo musí být schválené v portálu brány.
Odhlášení odpovědí STOP funguje jen s číselným odesílatelem, na kterého jde odpovědět. Na textového odesílatele odpovědět nejde.
Vyzkoušet bránu
Pod formulářem jsou Otestovat spojení (ukáže i kredit) a Poslat testovací SMS na zadané číslo. Test používá uložené nastavení – po změnách nejdřív uložte.
Brána Test (nic neodesílá) jen zapíše zprávu jako odeslanou, nebo podle Chování vrátí chybu či vyčerpanou kvótu. Slouží k vyzkoušení opakování a převzetí jinou bránou. Je-li aktivní jen ona, Přehled upozorní, že zákazníkům žádná SMS nepřijde.
4. Šablony
Komponenty → SemaSMS → Šablony jsou texty SMS s proměnnými.
- Kód – pod ním šablonu volají pravidla VirtueMart a jiná rozšíření, např.
order_shipped. Malá písmena, číslice a znaky_ . -. - Texty – jeden řádek na jazyk. Text pro Všechny jazyky se použije, když pro jazyk objednávky vlastní text není.
- Bez diakritiky – odstraní háčky a čárky i z dosazených hodnot (jméno zákazníka). Jedna SMS pak pojme 160 znaků místo 70.
Proměnné se píšou do složených závorek a vkládají kliknutím v panelu Proměnné:
| proměnná | co dosadí |
|---|---|
{shop_name} | název webu |
{first_name}, {last_name} | jméno a příjmení zákazníka |
{order_number} | číslo objednávky |
{order_total} | celková cena s měnou |
{order_status} | stav objednávky |
{shipping_method} | způsob dopravy |
{tracking_number}, {tracking_url} | číslo a odkaz na sledování zásilky |
Náhled s ukázkovými hodnotami ukazuje počet znaků a SMS a kódování: GSM-7 (160 znaků na SMS) nebo Unicode (70 znaků). Když text přepne na Unicode, náhled vypíše znaky, které to způsobily.
Na co si dát pozor
- Šablona s neznámou proměnnou se neodešle. Uložení na to upozorní.
- Číslo a odkaz na sledování zásilky dnes VirtueMart ani rozšíření dopravců SemaSMS nepředávají a zůstanou prázdné. Do šablon je zatím nedávejte.
- Text delší, než brány přijmou, uložení označí. Zkraťte ho nebo zapněte Bez diakritiky.
5. SMS k objednávkám VirtueMart
Komponenty → SemaSMS → Pravidla VirtueMart určují, kdy se zákazníkovi pošle SMS.
- Stav objednávky – SMS se pošle, když objednávka do stavu přejde, nebo když je v něm nová objednávka.
- Šablona – text se vybere podle jazyka objednávky.
- Skupina zákazníků a Jazyk – nepovinné zúžení.
Když pro stav platí víc pravidel, vyhraje nejkonkrétnější (skupina i jazyk, pak skupina, pak jazyk, pak obecné) a pošle se jen jedna SMS. Mezi stejně konkrétními rozhoduje Pořadí. Jedna objednávka dostane pro každý stav nejvýš jednu SMS, i když se do něj vrátí.
Nastavení → VirtueMart → Telefon z adresy určuje, odkud se telefon bere: z doručovací adresy, a když chybí, z fakturační, nebo jen z fakturační. Číslo bez předvolby dostane předvolbu podle země téže adresy.
Pravidla posílá plugin VM Extended - SemaSMS, musí být zapnutý.
Ruční SMS z objednávky
V detailu objednávky VirtueMart je v liště tlačítko Poslat SMS. Formulář předvyplní telefon z objednávky; vyberete šablonu (vyplní se údaji objednávky a text jde upravit), nebo napíšete vlastní text. SMS jde do fronty jako transakční a odejde hned. Tlačítko vidí uživatelé s oprávněním Odeslat SMS.
6. SMS kampaně
Komponenty → SemaSMS → Kampaně jsou hromadné SMS na seznamy AcyMailingu v nastavený čas. Potřebují nainstalovaný AcyMailing a v Nastavení → Kampaně → Pole s telefonem v AcyMailingu systémový název (namekey) vlastního pole s telefonem (výchozí telefon). Čísla bez předvolby se berou jako čísla výchozí země.
- Nová, vyplňte Název (jen pro administraci) a vyberte Seznamy AcyMailingu. U každého seznamu je počet odběratelů a kolik z nich má telefon.
- Napište Text SMS. Patička s odhlášením se předvyplní z Nastavení; nechte ji v textu.
- Nepovinně Text SMS anglicky – dostanou ho odběratelé s angličtinou nastavenou v AcyMailingu.
- Zaškrtněte Potvrzuji právní základ: příjemci dali souhlas se zasíláním obchodních sdělení, nebo jsou to vaši zákazníci a SMS se týká podobných služeb (§ 7 zákona č. 480/2004 Sb.).
- Spočítat ukáže příjemce a počet SMS a kolik kontaktů vypadne: bez telefonu, neplatné číslo, odhlášené (STOP), duplicitní číslo.
- Testovací SMS pošle výchozí text hned na jedno číslo, mimo kampaň.
- Nastavte Čas odeslání a klikněte na Naplánovat.
Příjemci se načtou až v čase odeslání: kdo se mezitím odhlásí v AcyMailingu nebo odpoví STOP, SMS nedostane. Jedno číslo dostane jednu SMS, i když je ve více seznamech. Úprava naplánované kampaně ji vrátí do konceptu – po změně ji naplánujte znovu. Rozeslání stovek SMS trvá podle cronu desítky minut, průběh a výsledek ukazuje kampaň.
Tiché hodiny a platnost
Kampaň se v tichých hodinách země příjemce nerozesílá a počká na jejich konec (kapitola Země). SMS, které do 12 hodin od startu neodejdou (Nastavení → Kampaně → Platnost SMS kampaně), propadnou, aby pozvánka nepřišla po akci. Tiché hodiny se transakčních SMS netýkají.
Rozpracovanou kampaň zastavíte tlačítkem Zrušit kampaň. SMS, které ještě neodešly, se už nepošlou.
7. Odhlášení STOP
Příchozí SMS, která začíná klíčovým slovem z Nastavení → Kampaně → Klíčová slova pro odhlášení (výchozí STOP, ODHLASIT, bez ohledu na velikost písmen a diakritiku), odhlásí odesílatele ze všech kampaní. Číslo se zapíše do Odhlášených čísel a čekající SMS kampaní na něj se zruší. Transakční SMS (stav objednávky) dostává dál.
Funguje to jen s číselným odesílatelem (kapitola Brány) a s příchozími SMS nastavenými u brány (kapitola Doručenky a příchozí SMS).
Komponenty → SemaSMS → Odhlášená čísla ukazují důvod (Odpověď STOP nebo Ručně). Číslo jde přidat ručně tlačítkem Přidat, i s poznámkou. Smazané číslo bude kampaně zase dostávat.
8. Fronta a cron
Každá SMS jde do Fronty. Transakční SMS (objednávky, ruční) se odešlou hned po požadavku, který je vytvořil – to dělá plugin Systém - SemaSMS. Opakované pokusy, kampaně a vše, co hned neodešlo, odesílá cron.
Stačí jedno z toho:
- Cron URL – v Nastavení → Cron vyplňte Token cron URL. Celou adresu najdete v Přehledu; cron hostingu ji volá každých 1–5 minut, např.
wget -q -O /dev/null "…". - Plánovač Joomla – Systém → Naplánované úlohy → Nová → SemaSMS – zpracovat frontu, interval 1–5 minut. Plánovač spouštěný návštěvami webu běží nepravidelně; spolehlivější je spouštět ho cronem.
Adresu cronu nikomu nedávejte. Token se mění v Nastavení, pak je potřeba upravit adresu u cronu.
Nastavení fronty
| volba | výchozí | význam |
|---|---|---|
| Výchozí země čísla | CZ | země pro čísla bez předvolby, když ji objednávka neurčí |
| Max. počet pokusů | 5 | na všech branách dohromady; mezi pokusy se čeká 1, 2, 4, 8… minut, nejvýš hodinu |
| Přepnout bránu po dočasných chybách | 2 | po tolika výpadcích v řadě převezme zprávu další brána; po trvalé chybě brány hned, po chybě čísla nebo textu ne |
| Platnost transakční zprávy (hodiny) | 24 | starší neodeslaná zpráva vyprší – pozdní SMS o objednávce zákazníka spíš zmate |
| Časový limit běhu (s) | 20 | na sdíleném hostingu nechte 20 s nebo méně |
| Velikost dávky | 50 | kolik zpráv se načte z fronty najednou |
Když brána hlásí vyčerpanou kvótu (hodinový nebo denní limit), do konce běhu odpočívá a zprávy na ni počkají, aniž by se jim ubíraly pokusy. Transakční zprávy s další bránou přejdou hned.
Přehled fronty
Seznam ukazuje stav zprávy (Čeká, Odesílá se, Odesláno, Doručeno, Neúspěšné, Vypršelo, Zrušeno), bránu, počet pokusů a čas. Detail zprávy obsahuje kódování, počet částí, cenu a historii pokusů a doručenek. Odeslat znovu jde u neúspěšných, vypršelých a zrušených zpráv, Zrušit odeslání u čekajících.
9. Doručenky a příchozí SMS
Brány posílají doručenky a příchozí SMS (odpovědi STOP) na adresu webu s tajným klíčem.
- V Nastavení → Webhooky a log vyplňte Klíč webhooků (písmena a číslice).
- Adresu pro každou bránu najdete v Přehledu, kartě Webhooky (doručenky).
- Zadejte ji v portálu brány: BulkGate Application → Settings → Web hooks, SMSbrána nastavení Push.
Bez webhooků SMS odcházejí normálně, jen zůstanou ve stavu Odesláno místo Doručeno a STOP nefunguje. Uchovávat log (dny) (výchozí 90) určuje, jak dlouho se drží historie pokusů a doručenek; zprávy ve frontě zůstávají.
10. Země
Komponenty → SemaSMS → Země jsou pravidla podle země příjemce. Po instalaci jsou založené CZ (+420) a SK (+421).
- Země – kód ISO, např. CZ. Podle něj se páruje země z adresy objednávky.
- Předvolba – bez „+“, např. 420. Čísla zapsaná bez předvolby ji dostanou podle země adresy.
- Časové pásmo – podle něj se počítají tiché hodiny.
- Tiché hodiny Od – Do a Celý víkend – platí jen pro kampaně. Okno může přecházet přes půlnoc, výchozí je 20:00–08:00.
Číslo ze země, která tu není, potřebuje v objednávce mezinárodní předvolbu.
11. Přehled
Komponenty → SemaSMS → Přehled ukazuje odeslané SMS za den, 7 a 30 dní, doručenost a chyby za 30 dní, počet zpráv ve frontě, náklady za 30 dní a kredit bran (načítá ho cron). Dále adresu cronu, adresy webhooků a Stav instalace s upozorněním na vypnutý plugin, chybějící bránu nebo cron, který neběžel déle než 30 minut.
12. Časté potíže
SMS k objednávce nepřišla. Podívejte se do Fronty. Když tam zpráva není: chybí pravidlo pro daný stav, objednávka nemá telefon, nebo je vypnutý plugin VM Extended - SemaSMS. Když tam je jako Čeká, neběží cron nebo je vypnutý plugin Systém - SemaSMS. Když je Neúspěšné, důvod je v detailu zprávy.
Kampaň odeslala méně SMS, než má seznam. Výsledek kampaně rozepíše kontakty bez telefonu, s neplatným číslem, odhlášené a duplicitní. Zkontrolujte, že Pole s telefonem v AcyMailingu je správný namekey.
Zprávy čekají u brány s vyčerpanou kvótou. Brána odpočívá a zkusí to znovu (BulkGate hodinový limit 15 minut, denní 60 minut). Kvótu navýšíte v portálu brány, nebo přidáte další bránu.
STOP nic neodhlásil. Kampaň šla z textového odesílatele, na kterého nejde odpovědět, nebo u brány není nastavená adresa webhooku pro příchozí SMS.
Test spojení SMSbrány selhává na přihlášení. Přepněte Variantu přihlášení a ověřte, že je v portálu SMSbrány povolená IP adresa serveru.
Jak to vypadá v praxi