Proměnná je zástupné místo v textu zprávy. Každý příjemce na ní dostane svou vlastní hodnotu — jméno, název firmy, číslo objednávky. Jeden text tak pošlete tisícům lidí a každý si přečte zprávu psanou jemu. Zápis proměnných je stejný v kampani i v API.

## Jak se proměnná zapisuje

Proměnná je název v lomených závorkách, třeba `<first_name_vokativ>`. Při odeslání se nahradí hodnotou, kterou pro daného příjemce máte:

| text zprávy | co dostane příjemce |
|:--|:--|
| `Dobrý den <first_name_vokativ>, vaše objednávka je na cestě.` | `Dobrý den Petře, vaše objednávka je na cestě.` |

- **Název musí sedět přesně.** Záleží na velikosti písmen i na mezerách — `<First_Name>` ani `< first_name >` se hodnotou `first_name` nenahradí.
- **Prázdná hodnota je totéž co žádná.** Prázdný text nebo samé mezery se berou jako chybějící hodnota — co se pak stane, popisuje [Když hodnota chybí](#kdyz-hodnota-chybi).

> [!WARNING]
> Zápis ve tvaru `<něco:něco>` nebo `<něco=číslo>` se bere jako proměnná vždycky, i když žádnou takovou nemáte, a v odeslané zprávě se změní. Nepomůže ani zápis přes `&lt;`. Samotné `<` nebo `<b>` zůstane beze změny.

## Když hodnota chybí

Když pro příjemce hodnotu nemáte, zůstane proměnná ve zprávě **doslova** — příjemce dostane `Dobrý den <first_name_vokativ>, …`. Tomu zabráníte výchozí hodnotou, kterou napíšete za dvojtečku:

| zápis | co dostane příjemce bez hodnoty |
|:--|:--|
| `<first_name_vokativ>` | doslova `<first_name_vokativ>` |
| `<first_name_vokativ:zákazníku>` | náhradní text `zákazníku` |
| `<first_name_vokativ:>` | nic — proměnná se vynechá |

Příjemce, pro kterého hodnotu máte, dostane ve všech třech případech tu svou.

> [!TIP]
> Proměnnou bez výchozí hodnoty používejte jen tam, kde máte data pro všechny příjemce. Jinak raději doplňte náhradní text, nebo ji nechte vynechat.

## Omezení délky

Za rovnítko napíšete, kolik znaků smí dosazená hodnota nejvýš mít: `<company_name=8>`. Hodí se u dlouhých hodnot, jako je název firmy nebo adresa, které by jinak zprávu natáhly do dalšího dílu SMS. Písmeno za číslem určuje, co se s delší hodnotou stane:

| zápis | co se stane s delší hodnotou | „Kytary Novák“ s limitem 8 |
|:--|:--|:--|
| `<company_name=8>` nebo `<company_name=8c>` | zkrátí se na limit — kde to jde, na celá slova | `Kytary` |
| `<company_name=8t>` | zkrátí se a doplní `...`, dohromady se vejde do limitu | `Kytar...` |
| `<company_name=8s>` | nahradí se `(...)` | `(...)` |
| `<company_name=8e>` | vynechá se | nic |
| `<company_name:vaše firma=8d>` | nahradí se výchozí hodnotou | `vaše firma` |

Hodnota, která se do limitu vejde, se dosadí celá.

> [!IMPORTANT]
> Proměnná s limitem se u příjemce bez hodnoty **vynechá** — doslova v textu nezůstane. Chcete-li i tady náhradní text, napište ho před rovnítko: `<company_name:vaše firma=8>`.

## Proměnné v kampani

Kampaň bere hodnoty z kontaktů, které do ní přidáte — z adresáře, z importu souboru i z ručně zadaných čísel.

1. **Nejdřív přidejte příjemce.** Nabídka proměnných ukazuje jen pole, která má vyplněná aspoň jeden příjemce kampaně. Bez příjemců je prázdná.
2. V editoru textu klikněte na ikonu `Přidat proměnnou`, nebo rovnou napište `@`. Psaním názvu nabídku zúžíte.
3. Vyberte proměnnou. U každé vidíte, kolik procent příjemců pro ni má data.

Proměnná se v textu zobrazí jako štítek s názvem pole a barvou ukazuje, jak jste na tom s daty:

- **bez zvýraznění** — data má každý příjemce, nebo je nastavená výchozí hodnota,
- **varování** — data má 30 až 99 % příjemců,
- **chyba** — data má méně než 30 % příjemců, nebo takové pole neexistuje.

Kliknutím na štítek proměnnou upravíte: doplníte náhradní text, necháte ji vynechat, nebo omezíte počet znaků (1 až 50). Editor to uloží ve stejném zápisu, jaký popisují [Když hodnota chybí](#kdyz-hodnota-chybi) a [Omezení délky](#omezeni-delky).

### Která pole můžete použít

| proměnná | co obsahuje |
|:--|:--|
| `<first_name>`, `<last_name>` | jméno a příjmení |
| `<first_name_vokativ>`, `<last_name_vokativ>` | jméno a příjmení v 5. pádě — dopočítají se samy, viz [České oslovení (vokativ)](https://www.bulkgate.com/cs/centrum-napovedy/nastroje/ceske-osloveni-vokativ/) |
| `<title_before>`, `<title_after>` | titul před jménem a za jménem |
| `<company_name>` | název firmy |
| `<company_number>`, `<company_vat>` | IČO a DIČ |
| `<email>` | e-mail |
| `<url>` | webová adresa |
| `<street1>`, `<street2>`, `<city>`, `<zip>`, `<state>`, `<country>` | adresa — ulice, město, PSČ, kraj, země |
| `<phone_mobile>` | telefonní číslo |
| `<note>` | poznámka |
| `<custom_field_0>` až `<custom_field_9>` | vlastní pole |

Při [importu ze souboru](https://www.bulkgate.com/cs/centrum-napovedy/kampan/import-kontaktu-pres-csv-excel/) přiřadíte každý sloupec k jednomu z těchto polí. Sloupec, pro který se žádné nehodí — číslo objednávky, výše slevy —, přiřaďte k vlastnímu poli a v textu použijte třeba `<custom_field_0>`.

### Kanály, délka a náhled

- **Kanály.** Proměnné fungují v textu zprávy SMS, Viber i RCS, u RCS i v titulku.
- **Délka a cena.** Počítadlo znaků v editoru počítá s hodnotami kontaktu, kterého máte vybraného v náhledu. Každý příjemce ale může mít jinak dlouhé hodnoty — počet dílů SMS a cena se proto počítají pro každého zvlášť, až po dosazení.
- **Unicode.** Diakritika z dosazené hodnoty přepne SMS do Unicode jen tehdy, když ho máte v nastavení textu zapnutý.
- **Náhled.** Náhled zprávy i `Odeslat testovací zprávu` dosazují hodnoty kontaktu vybraného v náhledu — ještě před odesláním tak vidíte, jak text dopadne.

## Proměnné v API

V API posíláte hodnoty přímo v požadavku, v parametru `variables`: objekt, kde klíč je název proměnné a hodnota to, co se má dosadit. V textu platí stejný zápis včetně výchozích hodnot a omezení délky.

```json
{
	"number": "420777777777",
	"text": "Dobrý den <first_name_vokativ:zákazníku>, objednávka <order> je na cestě.",
	"variables": {"first_name": "Petr", "order": "12345"}
}
```

Příjemce dostane `Dobrý den Petře, objednávka 12345 je na cestě.` Název proměnné si můžete zvolit libovolný — `<order>` v příkladu není pole kontaktu, jen klíč z `variables`.

### Kam proměnné patří

| API | kam patří `variables` |
|:--|:--|
| [Advanced API – transakční](https://www.bulkgate.com/cs/dokumentace/advanced-api/advanced-transactional/2.0/) | k celé zprávě; ve verzi 2.0 i ke každému číslu v `number` zvlášť — hodnoty u čísla mají přednost |
| [Advanced API – promoční](https://www.bulkgate.com/cs/dokumentace/advanced-api/advanced-promotional/2.0/) | ke každému číslu v `number` zvlášť; `variables` u celé zprávy se nepoužije |
| [Advanced API – skupiny z adresáře](https://www.bulkgate.com/cs/dokumentace/advanced-api/advanced-promotional-posilani-zprav-skupinam-z-adresare/) | nepředávají se — dosadí se pole kontaktů z adresáře, se stejnými názvy jako v [kampani](#ktera-pole-muzete-pouzit) |
| [Integration API](https://www.bulkgate.com/cs/dokumentace/integration-api/integration-transactional/) | ke každé zprávě |

### Jaké hodnoty posílat

- **Text nebo číslo.** Čísla se dosadí tak, jak jsou (`12` → `12`).
- **`null`, `false` a prázdný text** se berou jako chybějící hodnota — uplatní se [výchozí hodnota](#kdyz-hodnota-chybi), jinak proměnná zůstane v textu doslova.
- **Pole ani objekt jako hodnotu** Advanced API nepřijme a vrátí chybu `invalid_input_parameters`.
- **Klíče navíc**, které v textu nejsou, se ignorují.
- **5. pád.** Advanced API z `first_name` a `last_name` samo dopočítá `first_name_vokativ` a `last_name_vokativ` — vlastní hodnoty těchto dvou klíčů přepíše. Integration API 5. pád nedopočítává. Jak oslovení funguje, popisuje [České oslovení (vokativ)](https://www.bulkgate.com/cs/centrum-napovedy/nastroje/ceske-osloveni-vokativ/).

### Kanály a délka

| kanál | kam se proměnné dosadí |
|:--|:--|
| SMS | text |
| Viber | text, popisek a odkaz tlačítka |
| RCS | text, titulek a popis karty |
| Voice | text |

Počet dílů SMS i cena se počítají z textu po dosazení. Diakritika z dosazené hodnoty přepne SMS do Unicode jen s `"unicode": true`. Text Viberu, RCS a WhatsAppu, který po dosazení přeroste limit kanálu (Viber 1 000 znaků, RCS a WhatsApp 5 000), se zkrátí.

> [!NOTE]
> Pluginy do e-shopů mají vlastní sadu proměnných, například `<customer_firstname>`. Popisuje je [Zákaznické SMS](https://www.bulkgate.com/cs/centrum-napovedy/integrace/sms-moduly/zakaznicke-sms/).