Message flow - SmsManager Developers

Při odesílání zprávy přes SmsManager můžete definovat flow — seřazený seznam kanálů, které se pro každého příjemce zkusí. Pokud první kanál není schopen zprávu doručit (například příjemce nemá nainstalovaný Viber), SmsManager automaticky vyzkouší další kanál v seznamu. To vám umožňuje maximalizovat míru doručení přes SMS, Viber a WhatsApp bez nutnosti psát vlastní logiku pro opakování.

Co je flow zpráv?

Vlastnost flow je pole objektů kanálů. Každý objekt obsahuje přesně jeden klíč — sms, viber, whatsapp_text, whatsapp_template nebo rcs — spolu s konfigurací toho kanálu. SmsManager prochází pole od prvního k poslednímu: vyzkouší první kanál, a pokud selže nebo je nedostupný pro daného příjemce, přejde na druhý a tak dále.

"flow": [
  { "viber": { "sender": "MujSender", "ttl": 60, "body": "Ahoj přes Viber" } },
  { "sms":   { "sender": "MujSender", "body": "Ahoj přes SMS" } }
]

Ve výše uvedeném příkladu se SmsManager nejprve pokusí doručit zprávu přes Viber. Pokud příjemce nemá Viber, nebo Viber TTL vyprší před doručením, SmsManager přejde a odešle zprávu jako standardní SMS.

Výchozí chování (bez flow)

Pokud do svého požadavku nezahrnete vlastnost flow, SmsManager použije jeden krok sms bez nastavené brány. To odpovídá zápisu:

"flow": [
  { "sms": {} }
]

Bránu pak SmsManager určí podle odesílatele:

Pokud je sender vyhrazené virtuální číslo registrované pro váš účet, použije se brána direct a zpráva se účtuje za cenu direct.
Jinak se zpráva směruje i účtuje jako high.

Stejně se chová i krok sms ve vlastním flow, kterému gateway nenastavíte. Explicitně uvedená gateway má vždy přednost. Text zprávy a odesílatele vezme SmsManager z kořene požadavku (body, sender). Pokud sender neuvedete, použije se výchozí odesílatel vašeho účtu (default_sender).

Zpráva bez flow

{
  "body": "Váš ověřovací kód je 4821.",
  "sender": "MojeFirma",
  "to": [{ "phone_number": "420777123456" }]
}

Příklady flow

Jednoduché flow pouze pro SMS

Když chcete jemné řízení SMS — například určení jména odesílatele, brány nebo zpracování Unicode — definujte jednoprvkový flow s kanálem sms:

{
  "body": "Váš ověřovací kód je 4821.",
  "to": [{ "phone_number": "420777123456" }],
  "flow": [
    {
      "sms": {
        "sender": "MojeFirma",
        "gateway": "high",
        "type": "sms",
        "ttl": 10
      }
    }
  ]
}

Viber s SMS zálohou (nejčastější vzor)

Toto je doporučený produkční vzor pro propagační nebo transakční zprávy. Nejprve se pokusí doručit přes Viber; pokud selže z jakéhokoli důvodu, zpráva přejde na SMS, abyste dosáhli každého příjemce.

{
  "body": "Ahoj! Vaše objednávka #1042 byla odeslána.",
  "to": [{ "phone_number": "420777123456" }],
  "flow": [
    {
      "viber": {
        "sender": "MujObchod",
        "ttl": 60,
        "body": "Ahoj! Vaše objednávka #1042 byla odeslána. 📦",
        "buttons": [
          { "title": "Sledovat zásilku", "url": "https://example.com/track/1042" }
        ]
      }
    },
    {
      "sms": {
        "sender": "MujObchod",
        "body": "Ahoj! Vaše objednávka #1042 byla odeslána. Sledovat: https://example.com/track/1042"
      }
    }
  ]
}

Všimněte si, že Viber krok má bohatší tělo s emoji a tlačítkem, zatímco SMS záloha používá prostý textový ekvivalent. Hodnoty body na úrovni kanálu vám umožňují přizpůsobit obsah pro každý kanál.

WhatsApp šablona s SMS zálohou

Pro proaktivní oslovování, kdy vám příjemce jako první nenapsal, použijte předschválenou WhatsApp šablonu. Pokud doručení přes WhatsApp selže, SmsManager přejde na SMS.

{
  "to": [{ "phone_number": "420777123456" }],
  "flow": [
    {
      "whatsapp_template": {
        "sender": "514578330250514",
        "template_name": "order_shipped",
        "language": "cs",
        "params": ["Jan", "1042"],
        "ttl": 60
      }
    },
    {
      "sms": {
        "sender": "MujObchod",
        "body": "Ahoj Jane, vaše objednávka #1042 byla odeslána!"
      }
    }
  ]
}

Podmínky selhání flow

SmsManager přeskočí kanál a zkusí další, když nastane některá z následujících podmínek: Viber

Příjemce nemá na svém zařízení nainstalovaný Viber.
Viber ttl vyprší před doručením zprávy.

WhatsApp šablona

Určená šablona nebyla ještě schválena Metou.
WhatsApp ttl vyprší před doručením zprávy.

WhatsApp text

Příjemce vám nikdy neposlal zprávu ani neodpověděl na jednu z vašich šablonových zpráv. WhatsApp textové zprávy jsou povoleny pouze v rámci 24hodinového zákaznického okna, které se otevře poté, co příjemce zahájí kontakt.

SMS

Protože SMS je nejuniverzálnějším dostupným kanálem, jen zřídka selže na úrovni kanálu. Selhání SMS označuje hlubší problém (neplatné číslo, nedostatečný kredit apod.), nikoli problém dostupnosti kanálu.

Kdy se přejde na další kanál — `ttl` a `ttl_condition`

První objekt v poli flow je vždy ihned přijat a zařazen k odeslání. Ve stejném okamžiku vznikne pravidlo, které po uplynutí ttl zkontroluje výsledek odesílání — a podle něj se rozhodne, zda přejít na další kanál. Pole ttl se zadává v minutách (typ float), nejméně 0.5 (30 sekund), nejvíce 43200 (30 dní). Hodnoty do 15 včetně mohou mít jedno desetinné místo (1.5 = 90 sekund); od 15 výše se zaokrouhluje nahoru na celé minuty (16.1 = 17 minut). Co přesně znamená „doručeno” se ale liší kanál od kanálu — u SMS je sent často konečný účtovaný stav, kdežto u WhatsApp nebo Viberu sent ještě nezaručuje doručení. Proto lze podmínku splnění časového testu určit polem ttl_condition:

Kanál předchozího kroku	Výchozí `ttl_condition`
`sms`	`sent`
`whatsapp_template`, `whatsapp_text`, `viber`	`delivered`

Hodnota ttl_condition určuje, které stavy se považují za „splněno” (a tedy se další kanál neodešle):

`ttl_condition`	Splněno stavy
`sent`	`sent`, `delivered`, `seen`
`delivered`	`delivered`, `seen`
`seen`	`seen`

WhatsApp šablona s SMS zálohou po 30 s

"flow": [
  {
    "whatsapp_template": {
      "template_name": "smspin",
      "language": "cs",
      "sender": "514578330250514",
      "ttl": 0.5,
      "ttl_condition": "delivered",
      "params": ["123456"]
    }
  },
  {
    "sms": {
      "body": "Váš kód je 123456",
      "sender": "MojeFirma",
      "gateway": "high"
    }
  }
]

V tomto příkladu se v čase T+30s ověří, zda byla WhatsApp zpráva doručena. Pokud ano, SMS se už neodesílá; pokud ne, odejde SMS záloha.

Priorita body a sender

Pole body můžete definovat na kořenové úrovni požadavku i uvnitř jednotlivých objektů kanálů v flow. Pokud jsou přítomny obě hodnoty, body na úrovni kanálu má prioritu pro daný kanál. Pokud kanál nezadá své vlastní body, použije se kořenové body.

{
  "body": "Prostý záložní text pro všechny kanály.",
  "to": [{ "phone_number": "420777123456" }],
  "flow": [
    {
      "viber": {
        "sender": "MujSender",
        "body": "🎉 Kanálově specifická Viber zpráva s emoji!"
      }
    },
    {
      "sms": {
        "sender": "MujSender"
      }
    }
  ]
}

V tomto příkladu Viber krok použije tělo s emoji, zatímco SMS záloha využije prostý kořenový text. Stejně funguje sender: hodnota v kroku má přednost před sender v kořeni požadavku. Pokud sender neuvedete ani na jedné úrovni, použije se výchozí odesílatel vašeho účtu (default_sender). Kořenový sender se v kroku ignoruje, pokud ho pro kanál daného kroku nemáte zaregistrovaný. Místo konkrétního odesílatele můžete použít i alias odesílatele. Podrobnosti najdete v konceptu Odesílatelé. Pole, která krok vyžaduje (body, sender), tak můžete uvést jen v kořeni požadavku. Hodnota v kroku má vždy přednost.

Kořenový sender s přepsáním v kroku

{
  "sender": "MojeFirma",
  "to": [{ "phone_number": "420777123456" }],
  "flow": [
    {
      "viber": {
        "body": "Vaše objednávka je připravena k vyzvednutí",
        "sender": "MujViber",
        "ttl": 10,
        "ttl_condition": "delivered"
      }
    },
    {
      "sms": {
        "body": "Vaše objednávka je připravena k vyzvednutí"
      }
    }
  ]
}

Krok Viber použije vlastního registrovaného odesílatele MujViber, krok SMS zdědí MojeFirma z kořene požadavku.

Vždy zahrnujte SMS jako poslední kanál ve svém flow pro produkční provoz. SMS je k dispozici na každém mobilním zařízení a nevyžaduje instalaci žádné aplikace, což z ní činí nejspolehlivější zálohu, která zajistí, že vaše zpráva dojde každému příjemci.

​Co je flow zpráv?

​Výchozí chování (bez flow)

​Příklady flow

​Jednoduché flow pouze pro SMS

​Viber s SMS zálohou (nejčastější vzor)

​WhatsApp šablona s SMS zálohou

​Podmínky selhání flow

​Kdy se přejde na další kanál — ttl a ttl_condition

​Priorita body a sender

Co je flow zpráv?

Výchozí chování (bez flow)

Příklady flow

Jednoduché flow pouze pro SMS

Viber s SMS zálohou (nejčastější vzor)

WhatsApp šablona s SMS zálohou

Podmínky selhání flow

Kdy se přejde na další kanál — `ttl` a `ttl_condition`

Priorita body a sender