Parametry WhatsApp šablon

Kompletní referenční přehled parametrů objektu whatsapp_template — proměnné v těle a hlavičce, media, všechny typy tlačítek, produktový carousel a časově omezené akce (LTO).

WhatsApp šablonu odešlete objektem whatsapp_template uvnitř pole flow. Kromě povinných polí (template_name, language, sender) můžete do šablony za běhu doplňovat obsah — proměnné v textu, media v hlavičce, dynamická tlačítka, produkty i časově omezené akce. Tato stránka je úplným referenčním přehledem těchto parametrů. Praktický úvod najdete v návodu Odeslat WhatsApp, rozdíl mezi šablonou a volným textem vysvětluje koncept Typy WhatsApp zpráv.

​

Povinná pole

Pole	Typ	Popis
template_name	string	Název předregistrované a schválené šablony.
language	string	Kód jazyka šablony, například cs, en, de.
sender	string	Phone Number ID vašeho WhatsApp odesílatele (číselné ID, ne telefonní číslo), např. 514578330250514.
ttl	integer	Volitelné. Doba života v minutách — jak dlouho se WhatsApp pokouší o doručení, než se přejde na další krok flow.

Minimální šablona

{
  "to": [{ "phone_number": "420777123456" }],
  "flow": [
    {
      "whatsapp_template": {
        "template_name": "welcome_template",
        "language": "cs",
        "sender": "514578330250514"
      }
    }
  ]
}

Pole pro parametry přijímají dvě pojmenování jako aliasy: params / params_header / params_buttons (doporučené, konzistentní s JSON API v2) a starší parameters_body / parameters_header / parameters_buttons. V této referenci používáme tvar params_*.

---

​

Proměnné v těle zprávy (params)

Pole params vyplňuje proměnné v textu šablony. WhatsApp podporuje dva styly proměnných; podle toho, který jste zvolili při vytváření šablony, se liší zápis.

​

Očíslované proměnné

Šablona s očíslovanými proměnnými {{1}}, {{2}}:

Dobrý den {{1}}, potvrzujeme vaši rezervaci dne {{2}}.

Předejte pole řetězců — hodnoty se dosadí pozičně:

{
  "whatsapp_template": {
    "template_name": "potvrzeni_rezervace",
    "language": "cs",
    "sender": "514578330250514",
    "params": ["Tomáši", "12. 11. 2026"]
  }
}

​

Pojmenované proměnné

Šablona s pojmenovanými proměnnými {{jmeno}}, {{den}}:

Dobrý den {{jmeno}}, potvrzujeme vaši rezervaci dne {{den}}.

Předejte pole objektů s jedním klíčem = názvem proměnné:

{
  "whatsapp_template": {
    "template_name": "potvrzeni_rezervace",
    "language": "cs",
    "sender": "514578330250514",
    "params": [
      { "jmeno": "Tomáši" },
      { "den": "12. 11. 2026" }
    ]
  }
}

Počet i pořadí hodnot musí odpovídat proměnným v šabloně. Chybějící nebo přebývající hodnota vede k zamítnutí zprávy (rejected).

---

​

Hlavička (params_header)

Pole params_header obsahuje vždy jediný prvek — WhatsApp šablona má nejvýše jednu hlavičku. Nejjednodušší zápis je řetězec; SmsManager podle jeho tvaru sám určí typ hlavičky:

Hodnota řetězce	Rozpoznaný typ
URL končící .jpg, .jpeg, .png	Obrázek
URL končící .mp4, .3gp	Video
URL končící .pdf	Dokument
Jakýkoli jiný text	Textová hlavička

Obrázek v hlavičce (zkrácený zápis)

{
  "whatsapp_template": {
    "template_name": "potvrzeni_rezervace",
    "language": "cs",
    "sender": "514578330250514",
    "params_header": ["https://example.com/soubor.jpg"]
  }
}

Podporované formáty a limity: obrázek png/jpg do 5 MB, video mp4/3gp (H.264 + AAC, se zvukovou stopou) do 16 MB, dokument pdf do 100 MB.

​

Explicitní zápis hlavičky

Místo řetězce můžete předat objekt a typ hlavičky určit explicitně. To využijete pro media přes objekt s link, textovou proměnnou, polohu nebo produkt.

Textová hlavička s proměnnou

{ "params_header": [{ "text": { "objednavka": "ORD-123" } }] }

Obrázek dokument

{ "params_header": [{ "image": { "link": "https://example.com/soubor.jpg" } }] }
{ "params_header": [{ "video": { "link": "https://example.com/soubor.mp4" } }] }
{ "params_header": [{ "document": { "link": "https://example.com/faktura.pdf", "filename": "faktura.pdf" } }] }

Poloha

{
  "params_header": [
    {
      "location": {
        "latitude": "50.1045378",
        "longitude": "14.4501183",
        "name": "SmsManager",
        "address": "Komunardů 36, Praha 7"
      }
    }
  ]
}

Produkt (Single-Product Message)

{
  "params_header": [
    {
      "product": {
        "product_retailer_id": "nqryix03ez",
        "catalog_id": "194836987003835"
      }
    }
  ]
}

---

​

Tlačítka (params_buttons)

Pole params_buttons doplňuje parametry tlačítek. Hodnoty se přiřazují pozičně ke tlačítkům v šabloně, proto na pozici statického tlačítka (bez parametru) vložte null.

Statická tlačítka (pevná URL nebo telefonní číslo) při odesílání uvádět nemusíte. Dynamická tlačítka a tlačítka s vyžadovanými parametry musíte uvést vždy a ve správném pořadí.

Jen druhé tlačítko je dynamické

{
  "whatsapp_template": {
    "template_name": "...",
    "language": "cs",
    "sender": "514578330250514",
    "params_buttons": [null, "kontaktujte-nas"]
  }
}

Typ tlačítka určíte tvarem hodnoty:

Hodnota	Typ tlačítka
"kontaktujte-nas" (řetězec)	Dynamické URL — doplní se za základní URL tlačítka
{ "url": "kontaktujte-nas" }	Dynamické URL (explicitně)
{ "payload": "TAP_CONTACT" }	Rychlá odpověď (postback s vlastním payloadem)
{ "code": "ABCD10" }	Kupón ke zkopírování do schránky
{ "catalog": "nqryix03ez" }	Katalog — zobrazí produkt z katalogu
{ "voice_call": { "ttl_minutes": 5 } }	WhatsApp volání na váš profil
{ "mpm": { … } }	Multi-produkt (MPM)
{ "flow": { … } } nebo { "flow": null }	Flow formulář pro sběr dat

Kupónové tlačítko používá klíč code ({ "code": "ABCD10" }), nikoli coupon.

​

Multi-produkt (MPM)

Klíčem objektu je product_retailer_id náhledového produktu, hodnotou je pole sekcí katalogu:

{
  "params_buttons": [
    {
      "mpm": {
        "2lc20305pt": [
          {
            "title": "Název sekce",
            "product_items": [
              { "product_retailer_id": "2lc20305pt" },
              { "product_retailer_id": "nseiw1x3ch" },
              { "product_retailer_id": "n6k6x0y7oe" }
            ]
          }
        ]
      }
    }
  ]
}

​

Flow tlačítko

Flow tlačítko musí být v požadavku uvedeno, i když nepředáváte žádná data — v takovém případě použijte null. Pro předvyplnění formuláře předejte objekt s daty:

Bez dat

{ "params_buttons": [{ "flow": null }] }

S předvyplněnými daty

{
  "params_buttons": [
    {
      "flow": {
        "first_name": "Tomáš",
        "last_name": "Marný"
      }
    }
  ]
}

---

​

Produktový carousel (params_carousel)

Pole params_carousel odešle šablonu typu carousel — pole karet, každá s jedním produktem:

{
  "whatsapp_template": {
    "template_name": "...",
    "language": "cs",
    "sender": "514578330250514",
    "params_carousel": [
      { "product": { "product_retailer_id": "vrpj01fvwp", "catalog_id": "194836987003835" } },
      { "product": { "product_retailer_id": "va2l5ioeat", "catalog_id": "194836987003835" } }
    ]
  }
}

---

​

Časově omezená akce (params_lto)

Pole params_lto nastavuje konec platnosti nabídky u šablony typu Limited Time Offer. Hodnotou je timestamp v milisekundách (řetězec nebo číslo):

{
  "whatsapp_template": {
    "template_name": "...",
    "language": "cs",
    "sender": "514578330250514",
    "params_lto": ["1698562800000"]
  }
}

Odpočet LTO se zobrazuje pouze v mobilní aplikaci WhatsApp, ne ve webovém klientovi ani na počítači.

---

​

Kompletní příklad

Šablona s pojmenovanou proměnnou v těle, obrázkem v hlavičce, dynamickým URL tlačítkem a SMS zálohou:

cURL

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 ORD-123 byla odeslána!",
    "to": [{ "phone_number": "420777123456" }],
    "callback": "https://yourapp.com/webhooks/whatsapp",
    "flow": [
      {
        "whatsapp_template": {
          "template_name": "order_shipped",
          "language": "cs",
          "sender": "514578330250514",
          "ttl": 60,
          "params": [{ "jmeno": "Jan" }],
          "params_header": ["https://example.com/track.png"],
          "params_buttons": ["ORD-123"]
        }
      },
      {
        "sms": { "sender": "MujObchod", "gateway": "high" }
      }
    ]
  }'

---

​

Další kroky

Odeslat WhatsApp

Praktický průvodce odesíláním šablon i volného textu.

Typy WhatsApp zpráv

Kdy použít šablonu a kdy volný text v 24hodinovém okně.

SMS záloha pro WhatsApp

Automatický přechod na SMS, když WhatsApp selže.

Webhooky

Stavy doručení WhatsApp a formát doručenek.