Wiki · Integrace
WhatsApp má dvě úplně různé cesty a plete se to u nich pořád. Kterou zvolit a na co si dát pozor.
📱
WhatsApp má dvě úplně různé cesty a plete se to u nich pořád.
Rychlý most (Baileys) se chová jako WhatsApp Web na vlastním čísle — nastavíte ho za pár minut,
nepotřebujete firemní účet, ale WhatsApp ho oficiálně netrpí. Business Cloud API je oficiální cesta
pro firmu: bez rizika zablokování, ale s firemním účtem, veřejnou HTTPS adresou a placením za konverzace.
Kterou cestu zvolit
| Most (Baileys) | Business Cloud API | |
|---|---|---|
| Nastavení | Minuty — naskenujete QR kód | Hodiny — Meta aplikace, firemní portfolio, webhook |
| Účet | Stačí vaše číslo (ideálně samostatné) | Meta Business + WhatsApp Business Account |
| Veřejná adresa | Nepotřebujete | Potřebujete HTTPS webhook (např. Cloudflare Tunnel) |
| Riziko | Menší riziko omezení účtu (není oficiální) | Žádné — oficiální cesta |
| Platby | Zdarma | Platí se za konverzace podle ceníku Meta |
| Vhodné pro | Vlastní agent, rodinu, malý tým | Zákaznickou podporu, firmu |
Cesta 1: rychlý most
hermes gateway setup # vybrat WhatsApp a projít průvodcem
Průvodce vás nechá naskenovat QR kód (jako při přihlášení WhatsApp Web). Od té chvíle agent odpovídá na zprávy na tom čísle.
| Nastavení | Význam |
|---|---|
WHATSAPP_ENABLED | Zapnutí adaptéru |
WHATSAPP_ALLOWED_USERS | Komu smí agent odpovídat (číslo v mezinárodním tvaru) |
WHATSAPP_GROUP_POLICY | Jak se chovat ve skupinách |
WHATSAPP_REQUIRE_MENTION | Zda musí být ve skupině označen |
WHATSAPP_MODE | Režim bridge (viz dokumentace podle verze) |
⚠️
Tři pravidla, která snižují riziko omezení účtu:
používejte samostatné číslo (ne svoje osobní), neposílejte hromadné zprávy a nepište lidem,
kteří vám první nenapsali. Agent má konverzovat, ne rozesílat.
WhatsApp občas změní protokol a most se na chvíli rozbije. Řešení je obvykle aktualizovat Hermes a číslo znovu spárovat — ne hledat chybu v konfiguraci.
Cesta 2: Business Cloud API
hermes whatsapp-cloud # průvodce, který ověří každý údaj hned při vložení
| Co potřebujete | Kde to vznikne |
|---|---|
| Firemní portfolio a aplikace s WhatsApp | business.facebook.com, developers.facebook.com |
| Phone Number ID a WABA ID | API Setup ve vaší aplikaci |
| Trvalý přístupový token (produkce) | Systémový uživatel v Meta Business |
| Veřejná HTTPS adresa pro webhook | Cloudflare Tunnel (zdarma), ngrok, nebo reverzní proxy na VPS |
| Ověřovací token webhooku | Vymyslíte si ho a vložíte na obou stranách |
| Proměnná | K čemu |
|---|---|
WHATSAPP_CLOUD_ACCESS_TOKEN | Trvalý token |
WHATSAPP_CLOUD_PHONE_NUMBER_ID | ID čísla (ne samotné číslo — častá záměna) |
WHATSAPP_CLOUD_WABA_ID | ID účtu WhatsApp Business |
WHATSAPP_CLOUD_VERIFY_TOKEN | Ověření webhooku při registraci |
WHATSAPP_CLOUD_ALLOWED_USERS | Komu smí agent odpovídat |
Nejčastější past průvodce odchytí sám: do kolonky Phone Number ID se vkládá dlouhé číselné ID, ne telefonní číslo. Když to prohodíte, API vrátí chybu, která vypadá jako špatný token.
Co umí obě cesty
| Vlastnost | Poznámka |
|---|---|
| Text, obrázky, soubory | Ano, v obou režimech |
| Hlasové zprávy | V Cloud API se odchozí hlasovka zobrazí jako „voice note“, když je na serveru ffmpeg |
| Skupiny | Most je zvládá; Cloud API skupiny nepodporuje (jen individuální konverzace) |
| Doručování z cronu | Ano — do domovského chatu (WHATSAPP_CLOUD_HOME_CHANNEL) |
Na co si dát pozor
| Situace | Co s tím |
|---|---|
| Agent neodpovídá na nové číslo | Chybí v allowlistu; zkontrolujte tvar čísla (mezinárodní, bez mezer) |
| Most po aktualizaci WhatsApp přestal fungovat | Aktualizovat Hermes a znovu spárovat |
| Cloud API hlásí chybu tokenu | Používáte testovací token, který vyprší — nasaďte trvalý |
| Webhook se neověří | Ověřovací token nesedí, nebo adresa není dostupná z internetu přes HTTPS |
| Podezření na omezení účtu | Přestaňte posílat hromadné zprávy; pro firmu přejděte na Cloud API |