Proč SMS nedorazila: co znamenají stavy doručení a chybové kódy

„Poslali jsme SMS, zákazník tvrdí, že nic nepřišlo." Tahle věta zní v každé firmě, která posílá SMS, a u každého poskytovatele. Ve většině případů má nedoručení jednoduché vysvětlení, které je vidět přímo v doručence. Stačí umět číst stav zprávy a chybový kód. V tomto článku najdete oba přehledy, radu, co v které situaci udělat, a vysvětlení, proč se za nedoručenou SMS obvykle nevrací kredit.

Krátká odpověď

SMS prochází třemi místy: bránou (TopSMS), operátorem a telefonem příjemce. Doručenka říká, kde cesta skončila:

Stav	Co to znamená	Kredit
pending	Přijato, právě se odesílá (zlomek sekundy).	účtuje se
queued	Ve frontě nebo čeká na naplánovaný čas (send_at).	účtuje se
sent	Předáno operátorovi, čeká se na doručenku.	účtuje se
delivered	Doručeno na telefon (čas v deliveredAt).	účtuje se
failed	Nedoručeno, důvod v errorCode a errorMessage.	účtuje se, výjimkou je not_sent
expired	Vypršela platnost, operátor zprávu během ní nedoručil.	účtuje se

Dlouhá zpráva složená z více částí je delivered až po doručení všech částí. Když některá část nedorazí, celá zpráva skončí jako failed, protože telefon ji nedokáže složit.

Chybové kódy a co s nimi

Operátor nám u nedoručené zprávy vrací jen stavové slovo, konkrétní důvod od něj nepřichází. Překládáme ho do pole errorCode, které vidíte v dashboardu, ve stavu přes API i ve webhooku. Navíc přidáváme kód pro čísla, která selhávají opakovaně.

errorCode	Srozumitelně	Co udělat
expired	Telefon byl po celou dobu platnosti zprávy vypnutý nebo mimo signál.	Číslo je zřejmě v pořádku. Pošlete zprávu znovu později.
undelivered	Operátor vrátil zprávu jako nedoručitelnou: číslo neexistuje, není aktivní nebo telefon SMS nepřijímá. U některých zahraničních sítí i dočasně nedostupný telefon.	Zkontrolujte číslo (překlep, chybějící předvolba). U zahraničí zkuste po pár minutách znovu.
rejected	Operátor zprávu odmítl: příjemce má zablokované SMS od firem, nebo operátor nepřijal odesílatele či obsah.	Neznamená špatné číslo. Pokud se opakuje u více příjemců, ozvěte se nám, podíváme se na odesílatele a text.
deleted	Operátor zprávu před doručením zrušil.	Pošlete znovu. Pokud se opakuje, napište nám.
unknown	Operátor nevrátil výsledek doručení.	Ověřte u příjemce; doručenka nemusí vždy dorazit.
repeated_failure	Na stejné číslo selhalo doručení nejméně potřetí za 90 dní.	Číslo pravděpodobně neexistuje nebo je trvale nedostupné. Vyřaďte ho ze seznamu.
not_sent	Zprávu se nepodařilo předat operátorovi.	Nic. Cena se automaticky vrátila na kredit, zprávu můžete poslat znovu.

Zpráva u undelivered a expired má ještě jednu užitečnou vlastnost. Když se na stejné číslo v posledních 90 dnech někdy doručilo, napíšeme to do errorMessage včetně data posledního doručení. Víte tak hned, že číslo je platné a telefon byl jen vypnutý.

Nejčastější příčiny v praxi

Z doručenek se dá většina případů zařadit do několika skupin:

1. Chyba v čísle. Překlep, chybějící předvolba, číslo bez +420. Před rozesílkou pomůže validátor čísel, který odhalí formálně neplatná čísla ještě před odesláním.
2. Vypnutý telefon nebo bez signálu. České sítě zprávu drží a doručí ji po zapnutí telefonu; pokud zůstane vypnutý celou dobu platnosti, skončí jako expired.
3. Blokace firemních SMS u příjemce. Někteří lidé mají u operátora zablokované zprávy od firemních odesílatelů. Výsledek je rejected a z vaší strany s tím nic neuděláte.
4. Zahraniční síť vrátila zprávu okamžitě. Některé sítě, typicky v Německu, nedrží zprávu pro vypnutý telefon, ale vrátí undelivered během pár minut. Víc níže.
5. Vícedílná zpráva, které chybí část. Dlouhý text s diakritikou se dělí po 67 znacích; když jedna část nedorazí, zpráva je failed. Kratší text bez diakritiky má méně dílů a méně rizik, viz Kolik znaků má SMS.

Kdy se vrací kredit a proč operátoři nerefundují

Kredit vracíme automaticky, když se zprávu nepodařilo předat operátorovi. To je stav not_sent a stejně se chovají i chyby při samotném odeslání přes API: neplatné číslo, číslo na blacklistu nebo odmítnutí bránou (502) se z kreditu nestrhnou. U hromadné dávky se účtují jen zprávy se stavem sent.

Jakmile operátor zprávu přijme, účtuje si ji vůči nám bez ohledu na to, zda ji telefon nakonec přijal. Cenu za přepravu zaplatil operátor ve chvíli přijetí, ne až při doručení. Proto se už odeslané, ale nedoručené zprávy nerefundují, a takhle to funguje u SMS bran obecně, nejde o specialitu TopSMS. Jediný rozdíl mezi poskytovateli je, jak poctivě to říkají dopředu.

Zahraničí a volitelné automatické opakování (Německo)

České sítě zprávu pro vypnutý telefon podrží. Některé zahraniční sítě, které potkáváme u německých čísel, vrátí místo toho rychle konečné „nedoručeno". Zpráva pak skončí jako undelivered, i když číslo existuje a telefon je jen chvíli mimo signál.

Pro tento případ máme volitelnou funkci automatické opakování do Německa, kterou si zapnete v Nastavení účtu:

• platí jen pro čísla s předvolbou +49 a jen pro undelivered, které přišlo do 3 minut od odeslání;
• zprávu pošleme znovu za 5, 15, 30, 60, 120 a 240 minut (celkem asi 8 hodin) pod stejným ID;
• každý pokus se účtuje jako nová SMS (2,35 Kč za segment do Německa), protože nám ho účtuje operátor;
• marketingové kampaně se neopakují v noci (21:00 až 8:00), ověřovací kódy mají jen jeden pokus, protože dál nemají smysl;
• dostanete až konečnou doručenku, průběh pokusů vidíte v errorMessage.

Pokud opakování nepotřebujete, nic se nezapíná a zpráva prostě skončí jako undelivered s radou zkusit to později. Přes API můžete opakování řešit i sami: pošlete zprávu znovu se stejným Idempotency-Key rozšířeným o číslo pokusu.

Jak nedoručení zjistit

Máte tři cesty, podle toho, zda posíláte z dashboardu nebo z vlastního systému:

Způsob	Kde	Pro koho
Historie zpráv v dashboardu	U každé zprávy stav, čas a srozumitelný důvod nedoručení.	Posíláte ručně nebo z CSV.
GET /api/sms/status/	Vrátí status, errorCode, errorMessage, deliveredAt, failedAt. Vyžaduje scope read.	Vlastní integrace, občasná kontrola.
Webhook	Při doručení, selhání či expiraci pošleme HTTP POST s podpisem X-TopSMS-Signature (HMAC-SHA256), 3 pokusy doručení.	Rezervační systémy, e-shopy, cokoli, co má reagovat hned.

Podrobnosti k formátu odpovědí najdete v dokumentaci REST API a na stránce Webhooky. Testovací API klíč simuluje doručenky i webhooky zdarma, takže si zpracování stavů ověříte bez odeslání jediné ostré zprávy.

Co s tím, když nedoručených zpráv přibývá

Jednotlivé expired a undelivered jsou normální součást provozu. Hlídat se vyplatí dvě věci:

• Podíl rejected u více příjemců najednou. Může ukazovat na problém s odesílatelem nebo obsahem. Napište nám na kontakt, vidíme víc než vy a umíme to prověřit u operátora.
• Čísla s repeated_failure. Každé další odeslání na ně je vyhozená koruna. Vyřaďte je z kontaktů; u kampaní z CSV stačí sloupec optOut nebo smazání řádku.

Co pro doručitelnost udělat dopředu: posílat přes bránu s přímým routováním na české operátory (viz Doručitelnost SMS a přímé routování), používat schválené Sender ID a nepřehánět to s délkou a frekvencí, abyste se nedostali do konfliktu s pravidly operátorů (Jak nezablokovat účet u operátora).

Jak začít

• Registrace zdarma trvá minutu, bez karty a bez měsíčního poplatku.
• Po ověření telefonu máte 10 testovacích SMS, doručenky vidíte hned v Historii zpráv.
• Stavy a chybové kódy ve vašem systému: REST API a Webhooky.