WhatsApp Business API
Jak to funguje
Pro využívání WhatsApp Business API je nutné projít registračním procesem inicializovaným z webové administrace SmsManager (v menu "Odesílatelé", dále klikněte na "Nový odesílatel" a vyberte "WhatsApp").
Po registraci získáte nového WhatsApp odesílatele, který je identifikovaný číselným ID (ve formátu 514578330250514). Toto ID je nutné použít jako hodnotu sender v objektu flow v rámci JSON API.
Pro správné fungování odesílání zpráv na WhatsApp je nutné, aby váš WhatsApp Business Account v rámci Facebooku měl definovanou platební metodu. Tlačítko na nastavení platební metody je součástí průvodce pro připojení WhatsApp účtu a odkaz je také odeslán e-mailem po aktivaci telefonního čísla.
Použití šablony
Pokud má vaše aplikace odesílat zprávy koncovým příjemcům (bez jejich úvodní interakce), je nutné nejprve registrovat šablony. Pomocí WhatsApp Business API není možné odesílat zprávy na zákazníky ve volném textovém formátu (to je možné jen pokud vám uživatel píše zprávu jako první nebo pokud vám na odeslanou zprávu odpověděl. V takovém případě je možné použít SmsManager Inbox pro realtime 1-to-1 konverzaci s daným telefonním číslem).
Šablony lze registrovat přímo v prostředí Facebooku v tzv. WhatsApp Manager. Další možností je vytvořit je během registračního procesu nebo ve webové administraci SmsManager vybrat (v menu "Šablony", dále "Přidat šablonu" a vyberte "WhatsApp").
Každá šablona má své unikátní jméno (template_name). Tuto hodnotu použijte v API.
Použití proměnných v šabloně
Každá šablona může také obsahovat proměnné. V WhatsApp Manageru můžete zvolit, zda preferujete proměnné pojmenované nebo očíslované.
Očíslované proměnné
Očíslovaná proměnná v textu zprávy vypadá např. následujícím způsobem:
Dobrý den {{0}},
potvrzujeme vaší rezervaci dne {{1}}.
Těšíme se na návštěvu!
Při volání API požadavku je nutné doplnit správné hodnoty pro proměnné 0 a 1, jinak odesílání skončí chybou. Proměnné zašlete následujícím způsobem:
...
"whatsapp_template": {
"template_name": "potvrzeni_rezervace",
"language": "cs",
"sender": "51457833025121",
"params":[
"Tomáši",
"12. 11. 2026"
]
}
...
Pojmenované proměnné
Pojmenovaná proměnná v textu zprávy vypadá např. následujícím způsobem:
Dobrý den {{first_name}},
potvrzujeme vaší rezervaci dne {{day}}.
Těšíme se na návštěvu!
Při volání API požadavku je nutné doplnit správné hodnoty pro proměnné first_name a day, jinak odesílání skončí chybou. Proměnné zašlete následujícím způsobem:
...
"whatsapp_template": {
"template_name": "potvrzeni_rezervace",
"language": "cs",
"sender": "51457833025121",
"params":[
{"first_name": "Tomáši"},
{"day": "12. 11. 2026"}
]
}
...
Obrázek v hlavičce šablony
Hlavička šablony může obsahovat také media (obrázek, video, PDF dokument aj.). Při vytváření šablony nahrajete konkrétní obrázek/video/PDF které slouží jako příklad.
V rámci API volání se pak tato hodnota může měnit podobně, jako v případě proměnných v textu zprávy. Použijte parametr params_header. Pozor, každá zpráva, může mít jen jeden parameter v rámci hlavičky, nicméně pro budoucí kompatibilitu zachováváme stejný formát tohoto parametru (tedy pole).
Na základě adresy souboru (zda končí jpg/jpeg/png nebo pdf nebo mov/3gp) se pak nastavují odpovídající parametry pro správné zobrazení.
Pokud hodnotou není URL adresa, použije se vložený text jako náhrada textové proměnné.
...
"whatsapp_template": {
"template_name": "potvrzeni_rezervace",
"language": "cs",
"sender": "51457833025121",
"params_header":[
"https://www.adresa-obrazku.com/nazev-souboru.jpg"
]
}
...
Speciální případ je také možnost zasílat k nám přímo obrázek, který je u nás uploadován a hostován. V takovém případě zašlete obrázek jako base64 text a na začátek vložte data:image/jpeg;base64, (s odpovídajícím typem). Pozor, maximální velikost celého POST požadavku je cca 200 KB.
Parametry v tlačítkách
Stejně jako mohou být parametry v textu zprávy, tak i URL tlačítka mohou obsahovat parametry pro doplnění při odesílání pomocí API. Při vytváření šablony u tlačítky nastavce typ na "DYNAMICKÝ" a zajdete URL, které bude vždy stejné (např. název domény https://www.smsmanager.cz nebo adresu, do které se má doplnit parametr: https://www.smsmanager.cz/?page=). Při použití API pak vkládáte do parametrů tu část, která se doplní za URL.
...
"whatsapp_template": {
"template_name": "potvrzeni_rezervace",
"language": "cs",
"sender": "51457833025121",
"params_buttons":[
"kontaktujte-nas"
]
}
...
Pro správné fungování je nutné použít stejné pořadí URL jako je pořadí tlačítek v šabloně. Např. pokud máte v šabloně 2 tlačítka a jen druhé z nich je dynamické, vložte na první místo hodnotu null.
Postback v tlačítkách
Pokud chcete pracovat s tlačítky, které vám zpátky pošlou custom data (tzv. "postback" tlačátka s vlastním payloadem) tak namísto pole řetězců použijte podobný zápis jako v případě pojmenovaných proměnných:
...
"whatsapp_template": {
"template_name": "potvrzeni_rezervace",
"language": "cs",
"sender": "51457833025121",
"params_buttons":[
{"url": "kontaktujte-nas"},
{"payload": "TAP_BUTTON_CONTACT"}
]
}
...
Stejně jako v předchozím případě je nutné pro správné fungování použít stejné pořadí parametrů jako je pořadí tlačítek v šabloně. Např. pokud máte v šabloně 3 tlačítka a jen druhé a třetí z nich je dynamické, vložte na první místo pole hodnotu null:
...
"whatsapp_template": {
"template_name": "potvrzeni_rezervace",
"language": "cs",
"sender": "51457833025121",
"params_buttons":[
null,
{"url": "kontaktujte-nas"},
{"payload": "TAP_BUTTON_CONTACT"}
]
}
...
FAQ
Co když příjemce nepoužívá WhatsApp?
Pokud příjemce nepoužívá WhatsApp, dojde k chybě během odesílání a pokračuje se v odesílání zprávy přes další kanál (pokud je definovaný). Pokud ne, zpráva nebude doručena a nebude účtována.
Proč někdy zpráva při odeslání přes WhatsApp čeká na doručení a někdy je označena jako nedoručená okamžitě?
Záleží na tom, zda příjemce měl někdy WhatsApp nainstalovaný. Pokud ano, tak se zpráva vždy čeká na doručení až do hodnoty ttl (viz flow) nebo do výchozí hodnoty. Pokud příjemce nikdy WhatsApp nepoužíval, tak se zpráva označí jako nedoručená okamžitě.
Kdy použít whatsapp_template a kdy whatsapp_text
Pokud odpovídáte na zprávu, kterou odeslal uživatel tak je možné použít definici objektu whatsapp_text a do hodnoty body vložit kompletní text, který se odešle na zadané telefonní číslo.
Typicky na odesílání odpovědi na přijatou zprávu máte 24 hodin. Dále již odpověď tímto způsobem není možná a doporučený postup je, zaslat uživateli v takovém případě šablonu s žádostí o odpověď (pokud uživatel na tuto zprávu odepíše nebo např. klikne na tlačítko v šabloně), pak se opět otevírá konverzační okno na dalších 24 hodin.
Pokud chcete uživateli odeslat zprávu bez jeho interakce s vaším WhatsApp Business účtem, je nutné použít existující šablonu. Tato šablona musí být registrována a schválena. Může obsahovat proměnné (ve formátu {{1}}, {{2}} atd.) které budou při odeslání nahrazeny za poskytnuté personalizované texty.
Stav zprávy
Stav zprávy při odesílání přes WhatsApp je odlišný od běžného chování SMS. U SMS zpráv je odeslání definováno jako situace kdy operátor zprávu přijme k doručení. Operátor vždy účtuje všechny odeslané zprávy bez ohledu na doručení. Doručení není vždy jisté a záleží na tom, zda příjemce existuje, je registrován v systému operátora apod.
Proto u SMS existují zvlášť stavy sent a delivered.
U WhatsApp je zpráva účtována jen když dojde k doručení a zpráva je odesílána jen v případě, že příjemce může zprávu přijmout. Proto při odesílání na WhatsApp existují jen stavy:
delivered(označuje situaci kdy zpráva byla odeslána a doručena)failed(označuje situaci kdy zpráva nebyla odeslána nebo doručena)