Jak nastavit SMS fallback pro WhatsApp zprávy

Tento návod ukazuje, jak odeslat WhatsApp zprávu s automatickou SMS zálohou pomocí pole flow v JSON API v2. SmsManager se nejprve pokusí doručit přes WhatsApp a v případě selhání automaticky přejde na SMS — bez psaní vlastní logiky pro opakování. Návod předpokládá, že už umíte odeslat základní zprávu a máte API klíč. Pokud teprve začínáte s WhatsAppem, projděte nejdřív Odeslání WhatsApp zprávy.

Jak fallback funguje

Pole flow je seřazený seznam kanálů. SmsManager je zkouší postupně od prvního k poslednímu a zastaví se u prvního, který zprávu doručí. Jakmile uvedete whatsapp_template (nebo whatsapp_text) jako první a sms jako druhý, získáte přesně fallback z WhatsAppu na SMS. Podrobnosti o řazení kanálů a podmínkách selhání najdete v konceptu Tok zpráv a Kanály.

Vždy uvádějte SMS jako poslední kanál ve flow. SMS funguje na každém mobilním telefonu bez instalace aplikace, takže je nejspolehlivější finální zálohou.

Předpoklady

Připojený WhatsApp Business účet a jeho Phone Number ID — viz Odeslání WhatsApp zprávy.
Pro proaktivní oslovení předschválená šablona s přesným názvem a kódem jazyka. Rozdíl mezi šablonou a volným textem popisuje Typy WhatsApp zpráv.

Sestavte požadavek s fallbackem

Nastavte kořenové body pro SMS zálohu

Kanál sms nemá vlastní obsah, takže jako text SMS použije kořenové pole body. Vždy jej nastavte — jinak by SMS záloha dorazila prázdná.

Kořen požadavku

{
  "body": "Ahoj Jane, vaše objednávka ORDER-123 byla odeslána!",
  "to": [{ "phone_number": "420777123456" }]
}

Přidejte WhatsApp jako první krok flow

Uveďte whatsapp_template jako první prvek pole flow. Nastavte sender na vaše Phone Number ID, template_name na název schválené šablony a language na kód jazyka. Proměnné šablony předejte v poli params.

Přidejte SMS jako druhý (záložní) krok

Za WhatsApp přidejte objekt sms. Pokud WhatsApp krok selže — příjemce nemá WhatsApp, šablona není schválená nebo vyprší ttl — SmsManager automaticky přejde na SMS.

Kompletní příklad

curl -X POST https://api.smsmngr.com/v2/message \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Ahoj Jane, vaše objednávka ORDER-123 byla odeslána!",
    "to": [{ "phone_number": "420777123456" }],
    "tag": "transactional",
    "callback": "https://yourapp.com/webhooks/sms",
    "flow": [
      {
        "whatsapp_template": {
          "sender": "514578330250514",
          "template_name": "order_update",
          "language": "cs",
          "params": ["Jan", "ORDER-123"],
          "ttl": 60
        }
      },
      {
        "sms": {
          "sender": "MujObchod",
          "gateway": "high"
        }
      }
    ]
  }'

{
  "body": "Ahoj Jane, vaše objednávka ORDER-123 byla odeslána!",
  "to": [{ "phone_number": "420777123456" }],
  "tag": "transactional",
  "callback": "https://yourapp.com/webhooks/sms",
  "flow": [
    {
      "whatsapp_template": {
        "sender": "514578330250514",
        "template_name": "order_update",
        "language": "cs",
        "params": ["Jan", "ORDER-123"],
        "ttl": 60
      }
    },
    {
      "sms": {
        "sender": "MujObchod",
        "gateway": "high"
      }
    }
  ]
}

Chcete-li fallback z volného textu (v otevřeném 24hodinovém okně) na SMS, nahraďte první krok kanálem whatsapp_text s vlastním body. Kompletní pole obou kanálů popisuje Kanály.

Jak zjistit, který kanál doručil

Odpověď API potvrdí přijetí požadavku, ale samotné doručení proběhne asynchronně. Který kanál nakonec zprávu doručil, zjistíte z doručovacích webhooků: SmsManager pošle POST na vaši callback URL při každé změně stavu a payload obsahuje kanál, přes který byla zpráva odeslána. Nastavení příjemce webhooků a strukturu payloadu popisuje Doručovací webhooky. Sekvenci pokusů napříč kanály detailně vysvětluje Tok zpráv.

Poznámky a řešení potíží

Prázdná SMS záloha — kanál sms bez vlastního body použije kořenové body. Pokud kořenové body chybí, SMS dorazí prázdná. Vždy jej nastavte.
WhatsApp krok se přeskočí — nejčastěji šablona ještě není schválená Metou, číslo nemá souhlas příjemce, nebo vyprší ttl před doručením. Ve všech těchto případech flow korektně přejde na SMS.
whatsapp_text mimo 24hodinové okno — volný text lze odeslat jen v aktivním zákaznickém okně. Mimo něj kanál selže a flow přejde na SMS. Pro proaktivní oslovení použijte whatsapp_template.

Kanály whatsapp_template a whatsapp_text mají odlišná pravidla doručitelnosti. Před sestavením flow ověřte, který typ odpovídá vašemu scénáři — viz Typy WhatsApp zpráv.

Odesílání zpráv

Příjem a ověření

Přístup a klíče

Jak nastavit SMS fallback pro WhatsApp zprávy

Jak fallback funguje

Předpoklady

Sestavte požadavek s fallbackem

Kompletní příklad

Jak zjistit, který kanál doručil

Poznámky a řešení potíží

Další kroky

Doručovací webhooky

Tok zpráv

​Jak fallback funguje

​Předpoklady

​Sestavte požadavek s fallbackem

​Kompletní příklad

​Jak zjistit, který kanál doručil

​Poznámky a řešení potíží

​Další kroky

Doručovací webhooky

Tok zpráv

Jak fallback funguje

Předpoklady

Sestavte požadavek s fallbackem

Kompletní příklad

Jak zjistit, který kanál doručil

Poznámky a řešení potíží

Další kroky