> ## Documentation Index
> Fetch the complete documentation index at: https://developers.smsmanager.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/cs/guides/send-whatsapp), rozdíl mezi šablonou a volným textem vysvětluje koncept [Typy WhatsApp zpráv](/cs/concepts/whatsapp-message-types).
## 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`. |
```json Minimální šablona theme={null}
{
"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](/cs/api-reference/json-v2/overview)) 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}}`:
```text theme={null}
Dobrý den {{1}}, potvrzujeme vaši rezervaci dne {{2}}.
```
Předejte **pole řetězců** — hodnoty se dosadí pozičně:
```json theme={null}
{
"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}}`:
```text theme={null}
Dobrý den {{jmeno}}, potvrzujeme vaši rezervaci dne {{den}}.
```
Předejte **pole objektů** s jedním klíčem = názvem proměnné:
```json theme={null}
{
"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 |
```json Obrázek v hlavičce (zkrácený zápis) theme={null}
{
"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.
```json Textová hlavička s proměnnou theme={null}
{ "params_header": [{ "text": { "objednavka": "ORD-123" } }] }
```
```json Obrázek / video / dokument theme={null}
{ "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" } }] }
```
```json Poloha theme={null}
{
"params_header": [
{
"location": {
"latitude": "50.1045378",
"longitude": "14.4501183",
"name": "SmsManager",
"address": "Komunardů 36, Praha 7"
}
}
]
}
```
```json Produkt (Single-Product Message) theme={null}
{
"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í.
```json Jen druhé tlačítko je dynamické theme={null}
{
"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:
```json theme={null}
{
"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:
```json Bez dat theme={null}
{ "params_buttons": [{ "flow": null }] }
```
```json S předvyplněnými daty theme={null}
{
"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:
```json theme={null}
{
"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):
```json theme={null}
{
"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:
```bash cURL theme={null}
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
Praktický průvodce odesíláním šablon i volného textu.
Kdy použít šablonu a kdy volný text v 24hodinovém okně.
Automatický přechod na SMS, když WhatsApp selže.
Stavy doručení WhatsApp a formát doručenek.