Dokumentace

Dokumentace zahrnuje widget 1.2.0, CMS pluginy 1.1.0 a API verze 1.2.0. Poslední aktualizace: červenec 2026.

Rychlý start

CallFlow je bezplatný widget zpětného volání s automatickou frontou hovorů. Návštěvník vašeho webu zanechá telefonní číslo a požadavek okamžitě přejde do aplikace CallFlow ve vašem telefonu. Spuštění trvá několik minut a skládá se ze tří kroků:

1. Vytvořte si účet – v aplikaci CallFlow pro Android nebo novější webový panel. Účet je zdarma.
2. Přidat stránku – V části 'Balíčky a stránky' přidejte adresu svého webu a zkopírujte krátký klíč začínající na CF-. To publiczny klucz strony (PUBLIC_SITE_KEY) — pozwala wyłącznie wysyłać nowe zgłoszenia, nie daje dostępu do Twojego konta.
3. Vložte skript – Umístěte následující kód bezprostředně před značku </body> swojej strony i podmień klucz oraz adres polityki prywatności.

<script

  src="https://callflowdesk.com/widget/widget.js"

  data-site-key="CF-TWOJ-KLUCZ"

  data-variant="floating"

  data-privacy-url="https://twoja-strona.pl/polityka-prywatnosci/">

</script>

To stačí. Na webu se objeví plovoucí tlačítko a každé hlášení spustí v aplikaci oznámení push.

HTML/JS widget

CallFlow 1.2.0 je produkční skript pro běžné HTML stránky. Nevyžaduje rámec nebo externí knihovny. Formulář běží v izolovaném Shadow DOM – nezasahuje do CSS vašeho webu – a může odesílat nové požadavky pouze prostřednictvím veřejného CallFlow API.

Základní instalace (plovoucí widget)

Vložit skript před </body> — dokładnie tak jak w Rychlý start. Výchozí varianta floating wyświetla pływający przycisk w rogu ekranu, który otwiera formularz.

Vložená varianta v obsahu

Pokud chcete formulář umístit na konkrétní místo na stránce (např. na podstránce kontaktů), přidejte prázdný kontejner a označte jej atributem data-target:

<div id="callback"></div>

<script

  src="https://callflowdesk.com/widget/widget.js"

  data-site-key="CF-TWOJ-KLUCZ"

  data-target="#callback"

  data-variant="box">

</script>

Dostupné varianty

• floating — pływający przycisk otwierający formularz (domyślny);
• box — pełny formularz w miejscu osadzenia;
• compact — mniejszy formularz do stopki lub sidebara;
• sticky — pasek przy dolnej krawędzi ekranu;
• ecommerce — pływający formularz przeznaczony dla karty produktu.

Všechny varianty můžete sledovat živě na webu Ukázka widgetu.

Kompletní tabulka atributů konfigurace

Nastavení naléhavosti a zásad ochrany osobních údajů jsou navíc načtena z CallFlow. Uživatel webu nemůže aktivovat funkci, kterou zakázal vlastník účtu.

Zabezpečení a soukromí

• skript nečte data účtu nebo seznam tiketů;
• umožňuje pouze vytvořit tiket;
• přenos probíhá přes HTTPS;
• formulář obsahuje honeypot a vyžaduje výslovný souhlas s kontaktováním;
• widget neukládá soubory cookie a nepoužívá místní úložiště;
• číslo je normalizováno a znovu ověřeno pomocí API;
• má časový limit 15 sekund a klíč idempotence na ochranu před duplikáty.

Přizpůsobení vzhledu

Od verze 1.2.0 widget ve výchozím nastavení dědí písmo z webu (inherit, awaryjnie system-ui), a wygląd można dopasować na dwóch poziomach: Snadno (jednoduché atributy) i Pokročilé (celospektrální CSS). Na štítek lze umístit atributy přizpůsobení <script> nebo na cíl zadaný data-target (atrybut na elemencie docelowym ma pierwszeństwo). Bez tych atrybutów widget wygląda tak jak dotychczas.

Snadná úroveň - barvy, rozměry, písmo

Každý atribut je volitelný a mapuje se na sadu proměnné CSS v hostitelském prvku widgetu (.callflow-widget-host):

Příklad přiřazení widgetu k temné straně se zlatými akcenty:

<div id="callback"

  data-accent="#c8953f"

  data-accent-text="#0b0b09"

  data-bg="#11181d"

  data-text="#f4f4f1"

  data-muted="#a9b0b4"

  data-border-color="rgba(255,255,255,.14)"

  data-radius="0px"

  data-shadow="none"></div>

<script

  src="https://callflowdesk.com/widget/widget.js"

  data-site-key="CF-TWOJ-KLUCZ"

  data-target="#callback"

  data-variant="box">

</script>

Stejné proměnné prostupují Shadow DOM prostřednictvím dědičnosti CSS, takže místo atributů můžete použít čisté CSS stránky (list nebo <style>):

#moj-kontener {

  --callflow-accent: #b8860b;

  --callflow-radius: 4px;

  --callflow-max-width: 460px;

}

Pořadí priority: atribut data-* na elemencie docelowym → atrybut data-* na tagu <script> → zmienna CSS strony → starsze atrybuty data-*-color → wartości domyślne.

Pokročilá úroveň - celé spektrum CSS

::part() - Důležité prvky formuláře mají atributy part, więc strona może je stylować dowolnym CSS bez ograniczeń Shadow DOM. Dostępne nazwy części:

container, title, subtitle, form, field, label, phone-label, input, phone-input, urgent-field, urgent-checkbox, urgent-reason-label, urgent-reason-input, checkbox, checkbox-input, consent, consent-input, link, privacy-link, button, submit-button, status, close-button, floating-trigger, launch-button, sticky-bar, sticky-copy, action-button, config-error.

.callflow-widget-host::part(submit-button) {

  background: linear-gradient(135deg, #e0b96f, #c8953f);

  text-transform: uppercase;

  letter-spacing: .06em;

}

.callflow-widget-host::part(title) {

  font-weight: 500;

}

data-custom-css - surové CSS vložené do Shadow DOM po základních stylech (kaskáda vítězí, ovlivňuje interní selektory widgetů):

<div id="callback"

  data-custom-css=".cf-panel{border:0;padding:14px} .cf-submit{letter-spacing:.06em}"></div>

data-css-href - Adresa externího listu načteného do Shadow DOM. Z bezpečnostních důvodů jsou přijímány pouze adresy https:// oraz ścieżki względne; http://, javascript: i inne schematy są odrzucane.

<script

  src="https://callflowdesk.com/widget/widget.js"

  data-site-key="CF-TWOJ-KLUCZ"

  data-css-href="https://twoja-strona.pl/assets/callflow-theme.css">

</script>

Pořadí stylů stínů DOM: základní styly → list z data-css-href → data-custom-css. Personalizacja jest w pełni opcjonalna i wstecznie kompatybilna — istniejące osadzenia działają bez zmian.

události JavaScriptu

Widget generuje události na hostitelském prvku a přenáší je do dokumentu, takže můžete například po úspěšné sestavě odeslat konverzi do analytického systému:

document.addEventListener('callflow:submitted', (event) => {

  console.log(event.detail.receiptId);

});



document.addEventListener('callflow:error', (event) => {

  console.warn(event.detail.code);

});

Dostupné události:

• callflow:open — formularz został otwarty;
• callflow:close — formularz został zamknięty;
• callflow:submitted — zgłoszenie zostało przyjęte (w event.detail.receiptId znajdziesz identyfikator potwierdzenia);
• callflow:error — wysyłka się nie powiodła (w event.detail.code znajdziesz kod błędu).

WordPress plugin

CallFlow 1.1.0 přidá widget na celý váš web WordPress bez úpravy šablony. Podporuje varianty floating, box, sticky i compact oraz osadzanie formularza w treści przez shortcode.

Požadavky

• WordPress 6.0 nebo novější;
• PHP 7.4 nebo novější (testováno na PHP 7.4 a 8.3);
• klíč webu Klíč webu CF-… utworzony w aplikacji CallFlow.

Instalace krok za krokem

1. Stáhněte si plugin - soubor callflow-wordpress-1.1.0.zip znajdziesz w sekcji Stáhnout.
2. Nainstalujte do řídicího panelu WordPress - přejděte na Pluginy → Přidat nový plugin → Nahrát plugin na server, ukažte na stažený soubor ZIP a klikněte Instalovata po instalaci Povolit.
3. Konfigurace - přejděte na Nastavení → CallFlow a:
   • vložte klíč do pole PUBLIC_SITE_KEY (formát CF-XXXX-XXXX);
   • vybrat Vyžaduje se Varianta (výchozí floating);
   • zadejte adresu Zásady ochrany osobních údajů vašeho webu;
   • Globálně povolit widget a klikněte Uložte změny.

Vkládání do obsahu (krátký kód)

Chcete-li zobrazit formulář uvnitř příspěvku nebo stránky, použijte krátký kód:

[callflow variant="box"]

Použití krátkého kódu automaticky deaktivuje druhý, globální widget na této podstránce – formulář nebude nikdy duplikován.

Běžné problémy

• Klíč se neukládá - Plugin ověřuje formát: klíč musí začínat CF- i zawierać wyłącznie wielkie litery, cyfry i myślniki. Skopiuj go ponownie z aplikacji, bez spacji.
• Widget se na stránce nezobrazuje - zaškrtávací pole Globálně povolit widget je zkontrolováno a klíč není prázdný. Pokud používáte plugin mezipaměti (např. LiteSpeed, WP Super Cache), vymažte mezipaměť po uložení nastavení.
• Widget se zobrazí dvakrát - máte také aktivní plugin CallFlow for WooCommerce; viz sekce WooCommerce.

plugin WooCommerce

CallFlow for WooCommerce 1.1.0 je plugin šitý na míru obchodům – používá variantu ecommerce z nagłówkiem zachęcającym do pytania o produkt. Wersja 1.1.0 jest publiczną betą przeznaczoną do testów na sklepie stagingowym.

Požadavky

• WordPress 6.0 nebo novější, PHP 7.4 nebo novější (testováno na PHP 7.4 a 8.3);
• aktivní plugin WooCommerce (povinné - bez něj se widget nezobrazí);
• klíč webu Klíč webu CF-… z aplikacji CallFlow.

Instalace krok za krokem

1. Stáhněte si plugin - soubor callflow-woocommerce-1.1.0.zip z sekcji Stáhnout.
2. Instalovat — Pluginy → Přidat nový plugin → Nahrát plugin na server, vyberte ZIP, Instalovat, Povolit.
3. Konfigurace - přejděte na Nastavení → CallFlow WooCommerce a:
   • vložit PUBLIC_SITE_KEY;
   • vybrat Vyžaduje se Varianta: ecommerce (domyślny), floating lub sticky;
   • nastavte si vlastní Záhlaví formulář (výchozí "Máte dotaz k produktu?");
   • Povolit widget obchodu a uložte.

Funguje se základním pluginem CallFlow

Oba pluginy mohou být aktivní současně. Když je widget WooCommerce povolen, automaticky deaktivuje globální widget základního pluginu, takže formulář se nikdy nezobrazí dvakrát. Pokud necháte pole klíče v nastavení WooCommerce prázdné, plugin použije klíč ze základního pluginu CallFlow.

Běžné problémy

• Widget se nezobrazuje - ujistěte se, že je WooCommerce nainstalován a aktivní; plugin zobrazí widget, pouze když je spuštěn WooCommerce.
• Dva widgety najednou - aktualizujte oba pluginy na verzi 1.1.0; starší verze nekoordinovaly viditelnost. Případně zrušte zaškrtnutí políčka „Povolit widget globálně“ v základním pluginu.
• Toto je beta - nejprve otestujte plugin na pracovní kopii obchodu, než jej povolíte v produkci.

Modul PrestaShop 8

Beta modul CallFlow 1.1.0 vkládá produkční widget do zápatí obchodu PrestaShop (háček displayFooter). Obsługuje warianty ecommerce, floating i sticky.

Požadavky

• PrestaShop 8.0 nebo novější;
• klíč webu Klíč webu CF-… z aplikacji CallFlow;
• nejprve nainstalujte beta verzi do zkušebního úložiště.

Instalace krok za krokem

1. Stáhnout modul - soubor callflow-prestashop8-1.1.0.zip z sekcji Stáhnout.
2. Instalovat do panelu - přejděte na Moduly → Správce modulů → Načíst modul a přejděte na stažený ZIP. Modul najdete v kategorii „Reklama a marketing“.
3. Konfigurace - klikněte Konfigurace pro modul CallFlow a:
   • vložit PUBLIC_SITE_KEY;
   • vybrat Vyžaduje se Varianta: Elektronický obchod (výchozí), Plovoucí nebo Lepkavý;
   • sada Záhlaví widgetu (výchozí "Máte dotaz k tomuto produktu?" - zadejte svůj vlastní v polštině);
   • prosím uveďte adresa zásad ochrany osobních údajů obchod;
   • nastavit přepínač Povoleno na "Ano" a klikněte Uložit.

Běžné problémy

• Chyba "Klíč CallFlow musí začínat CF-" - modul ověřuje formát klíče; zkopírujte jej z aplikace bez mezer.
• Widget se po uložení nezobrazí - vymazat mezipaměť úložiště (Pokročilé → Výkon → Vymazat mezipaměť) a zkontrolujte, zda je přepínač Enabled nastaven na "Yes".
• Motiv nevyvolá zápatí - widget je připojen k háku displayFooter; jeśli Twój motyw go nie renderuje, podepnij moduł do innego hooka w Vzhled → Položky.

Jiné platformy

Následující integrace jsou technické beta verze 1.1.0 – nejprve je nainstalujte do svého pracovního prostředí. Všechny balíčky najdete v sekci Stáhnout.

Drupal 10/11

Po instalaci modulu přejděte na Konfigurace → Síťové služby → CallFlow, vložte veřejný klíč webu a vyberte variantu.

Joomla 4/5

Po instalaci povolte plugin Systém – CallFlow (v Systém → Pluginy), vložte PUBLIC_SITE_KEY, wybierz wariant i podaj adres polityki prywatności.

Magento 2 / Adobe Commerce

Kopírovat modul do app/code/CallFlow/Callback, uruchom bin/magento setup:upgrade i skonfiguruj go w Stores → Configuration → General → CallFlow. Modul obsahuje whitelist CSP pro skript a API samael.pl, więc nie musisz ręcznie modyfikować polityki bezpieczeństwa treści.

e107 2.3

Po instalaci otevřete konfiguraci CallFlow, vložte klíč CF-…, wybierz wariant i włącz widget.

Strapi 4/5

Plugin poskytuje konfiguraci veřejných modulů /api/callflow/config (endpoint nie ujawnia żadnych danych konta ani zgłoszeń). Ustaw zmienne środowiskowe CALLFLOW_SITE_KEY oraz opcjonalnie CALLFLOW_VARIANT, a we frontendzie użyj:

import {mountCallFlow} from 'strapi-plugin-callflow/client';

await mountCallFlow();

Shopify

Balení obsahuje zdrojový kód Rozšíření aplikace Theme (vložení aplikace pro plovoucí widget a blok aplikace s formulářem vloženým do sekce) – nejedná se o instalační program obchodu. Nasazení vyžaduje aplikaci Shopify Partner a obchod pro vývojáře:

shopify app dev

shopify app deploy

Po instalaci prodejce aktivuje CallFlow Nastavení motivu → Vložení aplikace nebo přidá blok formuláře do sekce motivu.

API pro vývojáře

CallFlow poskytuje REST API verze 1.2.0 – stejná smlouva pohání mobilní aplikaci a veřejné widgety.

Základy

• Základní adresa URL: https://callflowdesk.com/api/v1
• Ověření: záhlaví Authorization: Bearer <access_token> (JWT). Token uzyskasz przez POST /auth/login, a odświeżysz przez POST /auth/refresh z refresh_token.
• Žádný token funguje pouze: /auth/register, /auth/login, /auth/refresh oraz /public/leads.
• Chyby: formát odpovědí application/problem+json z polami type, title, status, code, detail, trace_id i (dla walidacji) errors.
• Stránkování: seznamy se vrátí next_cursor; kolejną stronę pobierzesz parametrem zapytania cursor.

Auth – Registrace a životní cyklus relace

Účet – hlavní účet, podúčty a statistiky

Zdroje – webové stránky a kontaktní balíčky

Zájemci - žádosti o zpětné volání a jejich stavy

Plán - plánování hovorů

Zařízení - tlačná zařízení

Veřejné – koncové body pro widgety

Příklad: přihlášení

curl -X POST https://callflowdesk.com/api/v1/auth/login \

  -H "Content-Type: application/json" \

  -d '{"email":"jan@firma.pl","password":"TwojeBezpieczneHaslo"}'

Odpovědět 200 zawiera access_token (przekazuj go w nagłówku Authorization: Bearer …), refresh_token, czas życia expires_in (w sekundach) oraz obiekt user. Przykład żądania uwierzytelnionego:

curl https://callflowdesk.com/api/v1/leads?status=new \

  -H "Authorization: Bearer ACCESS_TOKEN"

Příklad: veřejné odeslání potenciálního zákazníka

Koncový bod POST /public/leads nie wymaga tokenu — identyfikuje stronę po publicznym kluczu CF-…. Nagłówek Idempotency-Key jest značka (16–128 znaků, např. UUID): Opakování požadavku se stejným klíčem nevytvoří duplicitní požadavek.

curl -X POST https://callflowdesk.com/api/v1/public/leads \

  -H "Content-Type: application/json" \

  -H "Idempotency-Key: 4b1f2c62-9e0a-4d7c-8f5e-6a3d2b1c0e9f" \

  -d '{

    "site_public_key": "CF-TWOJ-KLUCZ",

    "phone": "+48601234567",

    "consent": true,

    "language": "pl",

    "widget_variant": "box",

    "source_url": "https://twoja-strona.pl/kontakt",

    "urgent": false,

    "website": ""

  }'

Povinná pole: site_public_key, phone, consent (musi być true), language i widget_variant. Pole website to honeypot antyspamowy — musi pozostać puste. Odpowiedź 202 zawiera receipt_id, accepted, message_key oraz opcjonalnie queue_position i estimated_callback_at.

aplikace pro Android

Aplikace CallFlow je řídicím centrem pro vaše hovory: sem směřují všechna hlášení z widgetů, zde spravujete stránky, tlačítka a kalendář zpětných volání. Aplikace se na Google Play objeví již brzy – do té doby instalační balíček najdete v sekci Stáhnout.

Klíčové vlastnosti

• Fronta hovorů - nové požadavky jsou automaticky odesílány do příslušného projektu a zařazeny do fronty podle pracovní doby a očekávané doby konverzace; stavy (nové, probíhají, zpracované, zmeškané, spam) organizují práci.
• Rozvrh - kalendář zpětného volání s automatickým plánováním další dostupné schůzky jediným dotykem.
• Push oznámení - každá nová zpráva okamžitě spustí upozornění; Seznam registrovaných zařízení spravujete v nastavení a ztracenému telefonu můžete zrušit přístup.
• Podúčty - jako vlastník účtu (hlavní role) zvete kolegy (vedlejší role) e-mailem a přiřazujete jim vybrané stránky; vidí pouze zdroje a zprávy, které jsou jim přiřazeny.
• Export dat - úplný export dat účtu (stránky, sestavy, plán, souhlasy) do souboru JSON v souladu s GDPR.
• Smazání účtu - trvalé smazání účtu se všemi údaji přímo z aplikace (vyžaduje potvrzení hesla a pro účty Google - fráze "DELETE ACCOUNT"); podrobnosti v sekci Smažte svůj účet.

Odstraňování problémů

Widget se vůbec nezobrazuje

Nejčastější příčinou je neplatný klíč. Zkontrolujte atribut data-site-key: klucz musi zaczynać się od CF- i składać się wyłącznie z wielkich liter, cyfr i myślników (bez spacji na początku i końcu). Otwórz konsolę przeglądarki (F12) — widget zgłasza tam problemy z konfiguracją. Upewnij się też, że skrypt jest wklejony przed </body> i że adres src nie został zmieniony.

Widget zobrazuje zprávu „Neplatná konfigurace“.

Klíč je ve správném formátu, ale není aktivní. To se stane, když byl vygenerován nový klíč (rotace okamžitě zruší platnost starého) nebo byla stránka archivována. Přejděte na podrobnosti o webu v aplikaci a zkopírujte aktuální klíč a nahraďte jej v nastavení kódu nebo pluginu.

Formulář funguje, ale aplikace se k aplikaci nedostanou

Zkontrolujte stav stránek v aplikaci: aplikace přijímají pouze aktivní stránky. Pozastavená nebo archivovaná stránka nepřijímá nové potenciální zákazníky. Zkontrolujte také, zda si nezobrazujete přehledy s filtrem stavu nebo na podúčtu bez přístupu na tuto stránku.

Widget se na WordPressu s WooCommerce objeví dvakrát

Máte aktivní oba pluginy: základní CallFlow a CallFlow pro WooCommerce. Od verze 1.1.0 plugin WooCommerce automaticky deaktivuje globální základní widget – aktualizujte oba na 1.1.0. Pokud problém přetrvává, zrušte zaškrtnutí políčka „Povolit widget globálně“. Nastavení → CallFlow. Pamatujte také na tento krátký kód [callflow] sam wyłącza widget globalny na danej podstronie.

Obchod s omezujícím CSP widget blokuje

Pokud váš web odesílá záhlaví Content-Security-Policy, přidejte doménu https://samael.pl do dyrektyw script-src (skrypt widgetu) i connect-src (wysyłka zgłoszeń do API). W Magento 2 nie musisz nic robić — nasz moduł zawiera gotową whitelistę CSP.

Widget neodesílá zprávy na localhost

Toto je záměrné: pole source_url zgłoszenia wymaga prawdziwej domeny z TLD (np. .pl, .com). Adresy typu localhost czy 127.0.0.1 nie przechodzą walidacji. Testuj widget na domenie stagingowej lub tymczasowej subdomenie — formularz i wygląd możesz oczywiście podejrzeć lokalnie.

Jak změnit barvy widgetu bez úpravy CSS stránky?

Použijte atributy snadné úrovně přímo na štítku <script> (lub kontenerze data-target): data-accent zmienia kolor przewodni, data-bg tło, data-text kolor tekstu, data-radius zaokrąglenia. Pełna lista w sekcji Personalizacea hotové sady ukázková galerie.

Kde najdu CF klíč svého webu?

V aplikaci CallFlow otevřete "Packages and Pages", zvolte page - key CF-… jest w jej szczegółach razem z gotowym kodem instalacyjnym do skopiowania. Możesz też wysłać sobie instrukcję instalacji e-mailem prosto z aplikacji.

Nedostávám oznámení push o nových přehledech

Zkontrolujte, zda má aplikace oprávnění pro oznámení v nastavení systému Android a zda je vaše zařízení v seznamu zařízení v aplikaci a nebylo odvoláno. Zakažte optimalizaci baterie pro CallFlow, pokud systém uspí aplikaci na pozadí.

Vygeneroval jsem nový klíč a widget přestal fungovat

Otočení klíče okamžitě zruší platnost předchozího - jedná se o bezpečnostní prvek. Po vygenerování nového klíče jej aktualizujte na všech místech, kde je widget vložen: v kódu webu a v nastavení každého CMS pluginu.