Přeskočit na hlavní obsah

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.

info

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.

...
    "whatsapp_template": {
        "template_name": "potvrzeni_rezervace",
        "language": "cs",
        "sender": "51457833025121",
        "params_header":[
            "https://www.adresa-obrazku.com/nazev-souboru.jpg"
        ]
    }
...

Více příkladů použití na samostatné stránce: Šablony - Hlavička zprávy

Odesílání tlačítek​

Šablony mohou obsahovat také tlačítka a to buď statická a nebo dynamická. V případě, že šablona obsahuje statická tlačátka, je možné je z odesílání vyřadit (nemusíte je uvádět v odesílání na API). Pokud jsou tlačítka dynmická nebo mají vyžadované parametry, je nutné je v rámci odesílání na API vždy definovat.

Příklady použití na samostatné stránce: Šablony - Tlačítka

Další typy šablon​

WhatsApp nabízí také další speciální typy a komponenty pro šablony. Více na samostatné stránce Šablony - Ostatní

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)